How to create a new Gazelle Web application

From IHE Wiki
Jump to navigation Jump to search

This section explains, with few steps, how to import create a new Gazelle Web application (Web application).


Steps are detailed below.



Step1 - You need to know what is a Gazelle application

Before creating your new application, you need to take a look on the existing applications or examples. If you did not read the Wiki page explaining what is a Gazelle application, and architectures of our applications, it's time to read this page.


Step2 - Design your application on a sheet

You need to give a name to your application, to your different modules and then, to design your architecture.

Here is below an example, with a slide showing the Product Registry application architecture :


In this slide, green modules are used by other applications, the other modules are specific to the Product Registry application.

< see Product Registry screenshot from EAR_architecture.ppt >


It's now important that you respect a standardization.


Respect the standardization of modules' names

  1. Choose the name of your application (for example : ProductRegistry , or InriaHL7MessageProfileRepository), don't use <space> or special ( _,- ...) caracters. Don't use '-' cause it will be used to know the kind of module.
  2. Now you know your application name, you may name your different modules that way :


  • ProductRegistry-ear
  • ProductRegistry-ejb
  • ProductRegistry-persistence
  • ProductRegistry-ui

Respect the standardization into the Forge

One application will have one special repository into the Forge. It will be "/svn/gazelle/YourApplication". This repository will contain the 4 modules above. If you use some common modules, don't include them in this repository, this repository contains only modules specific to your application.

Common modules used by several applications are existing into the Forge in the repository "/svn/gazelle/Common".


Other standardization point : During your developments or projects initialization, please never commit the following directories into the forge :

  • /build directory
  • /dist directory
  • /docs directory
  • /exploded-archives directory
  • /test-output directory
  • /build.properties file

/!\ In another way, please always perform a “svn:ignore” for all generated files after your first compilation/deployment.


Note : For further informations about the Forge access with SVN, please read section Code control - Access to the Forge.

Step3 - Create your EAR module

Create the EAR structure

To do that, from your Eclipse environment :

  • Click on "File" > "New" > "Other".
  • Then, into the J2EE directory, select the "Enterprise Application Project" project.
  • Give the name to this module : YourApplication-ear, then click on "Next".
  • Select the Java version associated to this project : 5.0
  • Then, click to "Finish"


Create the library directory

Create a directory "lib", inside the EarContent directory of your EAR module. Copy inside this "lib" directory, all the libraries existing in the reference project "TestManagement-ear".

Ding: I can copy the jars, but I would like to know where are the jars from and its version. 


<your_workspace>/YourNewApplication-ear/EarContent/lib/*.jar

Create a jboss-app.xml file

For the application, you need to create the file 'jboss-app.tpl2.xml'.


To do that, please create the file : 


<your_workspace>/YourNewApplication-ear/earContent/META-INF/jboss-app.tpl2.xml

Take a look on the TestManagement application (TestManagement-ear module) to create this file, and update to fit it to your application.

Update the application.xml file

For the application, you need to declare all the modules you will add. This step will add the module in the EAR application.


To do that, please create the file : 


<your_workspace>/YourNewApplication-ear/earContent/META-INF/application.tpl2.xml

And add lines, to declare all your futures modules.

  • If the module is an EJB module, here are the lines add :

  <module>
      <ejb>YOUR_EJB_MODULE_TO_ADD-ejb.jar</ejb>
  </module>


  • If the module is a WEB module, here are the lines add :

  <module>
    <web>
      <web-uri>YOUR_WEB_MODULE_TO_ADD-ui.war</web-uri>
      <context-root>/YOUR_CONTEXT_YOU_WANT_TO_REACH_THIS_MODULE</context-root>
    </web>
  </module>

/!\ Note : The value you will give to <context-root> will be the way to access to your web module. For example, if your <context-root> is /ProductRegistry , then you will access to this module, going to http://localhost:8080/ProductRegistry


You can see an example of application.xml clicking on that page .

Create a datasource file

For the connection of your application with the database, you need to create a datasource file. You will put this file in a resources directory.


Please create the file : 


<your_workspace>/YourNewApplication-ear/resources/YourNewApplication-ear-ds.xml

Take a look on the SampleGazelle application (SampleGazelle-ear module) to create this file, and update to fit it to your application.


Create 'build.properties' files

For building and deployment, you have now to define your environment properties. For that, you need a file build.properties and a file build.properties.template.

Create the files : 


<your_workspace>/YourNewApplication-ear/build.properties
<your_workspace>/YourNewApplication-ear/build.properties.template

/!\ Important Note : Only the file 'build.properties.template' has to be committed into the Forge, tihis file should be a template generic to all systems, 'build.properties' has to be svn:ignore, because specific to your system. Take a look on the SampleGazelle application to create those files and get more informations



Create your Ant tasks

For building and deployment, you have now to create your Ant tasks. For that, you need a file build.xml and a file build-macros.xml.

Create the files : 


<your_workspace>/YourNewApplication-ear/build.xml
<your_workspace>/YourNewApplication-ear/build-macros.xml

Take a look on the SampleGazelle application (SampleGazelle-ear module) to create those files, and update to fit them to your application.



Create the read-me.txt file corresponding to your application

For documentation, please declare your application and the different modules used inside the read-me.txt file inside the EAR project. This file helps developers to understand the application and installation. And if you plug a module to an existing application, then Gazelle developers will need to know that they will have to check it out, to work in this application.


To do that, please create the file : 


<your_workspace>/<existing-application-name>-ear/read-me.txt

Take a look on the SampleGazelle application (SampleGazelle-ear module) to create this file, and update to fit it to your application.





Step4 - Create your Persistence module

Create the structure of your Persistence module

To do that, from your Eclipse environment :

  • Click on "File" > "New" > "Other".
  • Then, into the EJB directory, select the "EJB3 Project" project.
  • Give the name to this module : YourApplication-persistence, then click on "Next".
  • Select the version associated to the EJB Module : 3.0
  • Select the version associated to the Java Module : 5.0
  • Then, click to "Finish"


Create a persistence.xml file

To map your the application with the database using a persistence layer with Hibernate, you need to create the file 'persistence.xml'.


To do that, please create the file : 


<your_workspace>/YourNewApplication-persistence/ejbModule/META-INF/persistence.xml

Take a look on the TestManagement application (TestManagement-persistence module) to create this file, and update to fit it to your application.


You can see an example clicking on that page .


Create your Ant tasks

For building and deployment, you have now to create your Ant tasks. For that, you need a file build.xml. This Ant script will be called by the master script, existing in the EAR module.


Create the file : 


<your_workspace>/YourNewApplication-persistence/build.xml

Take a look on the TestManagement application (TestManagement-persistence module) to create this file, and update to fit it to your application.


Create your import files

You will have to performed that step when when you will have some entities. But you can already create the directories : 


<your_workspace>/YourNewApplication-ejb/sql/data-dev/
<your_workspace>/YourNewApplication-ejb/sql/data-prod/


Create your ejb-jar.xml file

Take a look on the TestManagement application (TestManagement-persistence module) to create this file, and update to fit it to your application.







Step5 - Create your EJB module specific to your application

Create the structure of your EJB3 module

To do that, from your Eclipse environment :

  • Click on "File" > "New" > "Other".
  • Then, into the EJB directory, select the "EJB3 Project" project.
  • Give the name to this module : YourApplication-ejb, then click on "Next".
  • Select the version associated to the EJB Module : 3.0
  • Select the version associated to the Java Module : 5.0
  • Then, click to "Finish"


Create your Ant tasks

For building and deployment, you have now to create your Ant tasks. For that, you need a file build.xml. This Ant script will be called by the master script, existing in the EAR module.


Create the file : 


<your_workspace>/YourNewApplication-ejb/build.xml

Take a look on the SampleGazelle application (SampleGazelle-ejb module) to create this file, and update to fit it to your application.


Configure your EJB module

For a good configuration and deployment, you have now to create the following files.


Create the files : 


<your_workspace>/YourNewApplication-ejb/ejbModule/components.properties
<your_workspace>/YourNewApplication-ejb/ejbModule/seam.properties

Take a look on the SampleGazelle application (SampleGazelle-ejb module) to create this file, and update to fit them to your application.

Create your import files

You will have to performed that step when when you will have some entities. But you can already create the directories : 


<your_workspace>/YourNewApplication-ejb/sql/data-dev/
<your_workspace>/YourNewApplication-ejb/sql/data-prod/


You will need to populate your database during your development (normally, only during development). For that, you need some SQL files importing datas for some classes that you developed and defined in this EJB module. You need to put them in a specific location : /data/sql. This location is common to all EJB modules (and managed by the Ant scripts)


Create the files you need inside a /data/sql repository. One sql file is corresponding to one table : 


<your_workspace>/YourNewApplication-ejb/sql/data/00_<your_object>_data.sql            (if this table contains none foreign key)

<your_workspace>/YourNewApplication-ejb/sql/data/10_<your_object>_data.sql            (if this table contains one foreign key)

<your_workspace>/YourNewApplication-ejb/sql/data/20_<your_object>_data.sql            (if this table contains two foreign keys)

<your_workspace>/YourNewApplication-ejb/sql/data/30_<your_object>_data.sql            (if this table contains three foreign keys)

<your_workspace>/YourNewApplication-ejb/sql/data/40_<your_object>_data.sql            (if this table contains four foreign keys)


Datas will be inserted into the database during the deployment (by order... 00_*, then 10_*, then 20_*, etc...).

Take a look on the SampleGazelle application (SampleGazelle-ejb module) to create those files, and update to fit them to your application.





Step6 - Create your Web module specific to your application

Create the structure of your Web module

To do that, from your Eclipse environment :

  • Click on "File" > "New" > "Other".
  • Then, into the Web directory, select the "Dynamic Web Project" project.
  • Give the name to this module : YourApplication-ui, then click on "Next".
  • Select the version associated to the Dynamic Web Module : 2.4
  • Select the version associated to the Java Module : 5.0
  • Then, click to "Finish"


Create your Ant tasks

For building and deployment, you have now to create your Ant tasks. For that, you need a file build.xml. This Ant script will be called by the master script, existing in the EAR module.


Create the file : 


<your_workspace>/YourNewApplication-ui/build.xml

Take a look on the SampleGazelle application (SampleGazelle-ui module) to create this file, and update to fit it to your application.




Prepare your Web module configuration

For your application, you will need to create the following files into your Web Modules.


Create the files : 


<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/components.xml
<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/components.tpl2.xml
<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/faces-config.xml
<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/jboss-web.xml
<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/pages.xml
<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/components.xml
<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/components.tpl2.xml
<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/web.xml (it should normally exist)

Note : When a file has a template, you have to edit the template (eg. components.tpl2.xml will generate the components.xml file through the Ant execution)


Create a directory "WebContent/WEB-INF/lib". Copy inside this "lib" directory, all the libraries existing in the reference module "SampleGazelle-ui". 



<your_workspace>/YourNewApplication-ui/WebContent/WEB-INF/lib/*.jar


Take a look on the SampleGazelle application (SampleGazelle-ui module) to create those files, and update to fit them to your application.

Prepare your Web module for development

For your application, you will need to create the following files into your Web Modules.


Create the files : 


<your_workspace>/YourNewApplication-ui/src/META-INF/orm.xml
<your_workspace>/YourNewApplication-ui/src/messages-YourNewApplication-ui.xml


Copy/Set your home.xhtml, css files and template.xhtml


Take a look on the SampleGazelle application (SampleGazelle-ui module) to create those files, and update to fit them to your application.



Step7 - Check your application can be successfully deployed in your application server

Deploy your application in JBoss Application Server. For that step, open a console, and from the <your_workspace>/YourNewApplication-ear directory, launch the ant commands in a console :

  • ant help
  • then follow instructions explaining how execute the targets clean, then all


/!\ Note : When these steps are done, don't forget to take a look to the JBoss deployment logs inside your console. You should see none error.


You can now check that application works with your modules :

  • If you added an EJB3 module with entities, check that the tables of your entities have been created in your application database.
  • If you added an EJB3 module with just Java classes/business layer, check that your code is well-called by the application.
  • If you added a Web module with entities, check that the module is reachable from the context path.




Step8 - Check in your application into Forge

You don't mess up Forge, if you respect the recommendations noticed in section :

Respect the standardization of modules' names.

and

Respect the standardization into the Forge.


You can now check in your application. To do that, create a repository in the Forge. This repository will contain the specific modules of your application (listed above). Example : "/svn/gazelle/YourApplication". If you use some common modules, don't include them in this repository, this repository contains only modules specific to your application.

The Common modules are stored into Forge in : "/svn/gazelle/Modules".

Now with Eclipse, right click on your projects to check in, and select 'Team > Share project'. Then use the SVN option to check them in the corresponding repository.


Please make sure that the following elements are not commitable (using svn:ignore in Team tab):

  • '/build' directory
  • '/dist' directory
  • '/exploded-archives' directory
  • '/lib-TF' directory (which contains the .jar file corresponding to this project)
  • '/build.properties' file


Please make sure that those files are checked in :

  • '/.classpath' file
  • '/.project' file


Back to the Gazelle Developers Guide homepage.





...







Back to the Gazelle Developers Guide homepage.


Retrieved from "http://wiki.ihe.net/index.php?title=How_to_create_a_new_Gazelle_Web_application&oldid=114270"