In Chapter 2, A Complete Mini Application, we developed a complete web application using the dvdcatalog project template, using the exact same configuration as the original template. To use the template for real life web applications, you will need to change the template. For instance, at least you are most likely to change your project and application file names from dvdcatalog to your own names.
To change the template for your own applications, you need to understand how the template assembles a complete application. Let's take the dvdcatalog project as an example again. A JBoss web application is packaged in an EAR (Enterprise Archive) file, in this case dvdcatalog.ear. The dvdcatalog.ear file contains two JAR files and two XML configuration files. Figure 3.1, “Structure of the dvdcatalog.ear file” shows the contents of the dvdcatalog.ear file.
The app.jar file packages all Java classes for EJB3 components, as well as their related configuration files.
The app.war file contains all the JSF web pages, backing bean classes, and JSF configuration files.
The META-INF/application.xml file declares the contents of the EAR file to the JBoss server. This file is required by the Java EE standard.
The META-INF/jboss-app.xml file contains JBoss-specific configuration options for this application.
In this chapter, we will go over those files and discuss how to customize them in the template. We will also cover how to take advantage of JBoss AS's hot deployment features to enable agile development feedback cycles.
The first task to customize the template is to change the application name from dvdcatalog to your own. Let's assume that your application should be named mywebapp. Now, open the build.xml file in the project template, and replace the "projname" property from "dvdcatalog" to "mywebapp". That would build the mywebapp.ear application archive file. You should also make sure that the ejbjar and war tasks include the EJB3 bean classes and JSF backing bean classes in their build targets respectively. You would not need to change anything if you place all EJB3 components under *.ejb.* Java package and all JSF backing beans under *.web.* package.
Example 3.1. The ejbjar and war tasks in the build.xml file
<target name="war" depends="compile">
... ...
<war ...>
... ...
<classes dir="${build.dir}">
<include name="**/web/**/*.class" />
</classes>
</war>
</target>
<target name="ejbjar" depends="compile">
... ...
<jar ...>
... ...
<fileset dir="${build.dir}">
<include name="**/ejb/**/*.class"/>
</fileset>
</jar>
</target>
Then, in the dd/ear/application.xml file (corresponding to META-INF/application.xml file in the EAR file), you should specify custom your application's context root URL. For instance, the following example, the application is available from http://localhost:8080/mywebapp/ URL.
Example 3.2. The application.xml file
<application ...>
<display-name>My App</display-name>
<description>My App</description>
<module>
<ejb>app.jar</ejb>
</module>
<module>
<web>
<web-uri>app.war</web-uri>
<context-root>mywebapp</context-root>
</web>
</module>
</application>
Finally, the dd/ear/jboss-app.xml file (corresponding to META-INF/jboss-app.xml in the EAR file) specifies an arbitrary string name for the application's Java class loader (i.e., a scoped class loader). The scoped class loader isolates each WAR application in its own runtime environment, even if there are multiple applications with different versions of the same class deployed in the same JBoss server instance. So, it is important that you specify a string unique to your application here. We recommend you use the appname:archive=appname.ear string pattern for the unique classloader name. The scoped classloader will be discussed in more detail in Chapter 4, Develop a Data Model.
The EJB3 components in the dvdcatalog application are packaged in the app.jar file. Figure 3.2, “Contents in the app.jar file” shows the contents of that file. It includes all the EJB3 Java classes, a META-INF/persistence.xml file to configure entity bean persistence settings, and an import.sql file to initialize the database.
The dd/ejb/persistence.xml file (corresponding to the META-INF/persistence.xml file in the .jar file) specifies which backend database to use, and configures the runtime options for the EJB3 persistence engine. The following listing shows the persistence.xml file for the dvdcatalog application. It specifies that all entity beans in this application should be persisted to the default database in the application server, as specified by the java:/DefaultDS data source. In a typical JBoss AS installation, the java:/DefaultDS data source points to the embedded HSQL database. Please see Chapter 4, Develop a Data Model on how to configure other data sources, such as the MySQL database, in JBoss AS.
Example 3.4. The persistence.xml file
<entity-manager>
<persistence-unit name="dvdcatalog">
<jta-data-source>
java:/DefaultDS
</jta-data-source>
<properties>
<property name="hibernate.hbm2ddl.auto"
value="create-drop"/>
<property name="hibernate.dialect"
value="org.hibernate.dialect.HSQLDialect"/>
</properties>
</persistence-unit>
</entity-manager>
The persistence.xml file can also take implementation-specific configuration properties beyond the official EJB3 specification for the persistence engine. Since JBoss EJB3 persistence is built on top of the Hibernate framework (a sub-project under the JBoss umbrella), all Hibernate properties can be specified here and they will be passed to the implementation at runtime. In the dvdcatalog example, there are two Hibernate properties. The hibernate.dialect property in the persistence.xml file tells the EJB3 container to generate HSQL's own dialect of SQL statements when saving, updating, retrieving entity bean objects to/from the database. The hibernate.hbm2ddl.auto property tells the EJB3 container to create the tables for the entity beans at deployment time, and to delete them when the application is un-deployed or the server shuts down. This is obviously useful for testing applications. The details of the persistence.xml file will be discussed in Chapter 4, Develop a Data Model.
The dd/ejb/import.sql file is included the .jar file. When the application is deployed, JBoss detects the import.sql file and executes its SQL statements against the data source specified in the persistence.xml file. The import.sql file allows us to initialize the database tables at the application deployment time. It is very useful during the application development phrase when you need to load testing data every time you test the application.
In the dvdcatalog application, we do not have anything in the import.sql file since the database tables are automatically created (i.e., the hibernate.hbm2ddl.auto=create-drop property) and there is no initial data. Please refer to Chapter 4, Develop a Data Model for an concrete example of the import.sql file.
As we discussed in Chapter 2, A Complete Mini Application, the JSF backing bean retrieves a session bean instance via JNDI. The default JNDI string contains the implementation class name of the session bean class. However, for completely de-coupled components, we should ideally assign an arbitrary JNDI string for each session bean so that its client does not have to know the implementation class. You can override the default JNDI name for any session bean using the @LocalBinding or @RemoteBinding annotations. For instance, the following code registers the DvdCatalogBean session bean's local interface under JNDI name "dvd/MyCatalog". The @RemoteBinding specifies the JNDI name for the remote interface of a session bean.
The JSF module of the application is packaged in a WAR file. All the JSP pages are packaged under the root of the archive. The backing bean classes are under the WEB-INF/classes directory. The library files are under the WEB-INF/lib directory. The dd/web/web.xml and dd/web/faces-config.xml files from the project template are packaged under the WEB-INF directory. Figure 3.3, “The Contents in the app.war archive” shows the packaging structure of the WAR file.
We have discussed all the elements in the faces-config.xml in Chapter 2, A Complete Mini Application. The only configuration file we have not yet discussed in Figure 3.3, “The Contents in the app.war archive” is the web.xml file. In order for JSF to work, we must load a controller servlet in the web.xml file, and map all URLs ending with .faces to the JSF controller servlet. The following listing shows the contents of the web.xml file. You probably do not need to modify this file for most projects, unless you need to use container managed security (see Chapter 7, Security) or use some custom JSF component libraries (see Chapter 13, Rich UI and AJAX).
Example 3.6. The web.xml file
<web-app ...>
<listener>
<listener-class>
org.apache.myfaces.webapp.StartupServletContextListener
</listener-class>
</listener>
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>
javax.faces.webapp.FacesServlet
</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.faces</url-pattern>
</servlet-mapping>
</web-app>
A major complaint developers have against heavyweight Java frameworks is that they have long development -- test cycles. Every time you make a change, you have to re-compile, re-build, re-deploy the application, and then re-start the server. That is at least several minutes before you can see the effect of a minor change. The lack of instant feedback is not only frustrating, but also prevents developers from testing.
JBoss AS, on the other hand, provides important features to support fast development -- test turn-around cycles. Those features are crucial for agile developers.
To deploy a JBoss web application, you simply need to copy the .ear file to the server/default/deploy directory in the server and starts the server. If the server were already started, it would detect the new EAR file and automatically deploy it.
If you need to make changes to the application, you can simply delete the EAR file from the server's deploy directory, causing the server to automatically un-deploy the application. Then, you copy the modified EAR file back in and it is re-deployed without server restart.
The hot deployment and un-deployment features are very useful for agile developers. You can make changes and see the effects very quickly without waiting for the server to shutdown and restart.
Another JBoss feature that helps agile development is exploded archives. The EAR, EJB3 JAR and WAR files are not necessarily JAR files in the JBoss container. They can be directories containing the contents of the JAR file. For instance, instead of deploying the dvdcatalog.ear file as a single file, you can deploy it as directory.
With the exploded directories, you can make changes to any single JSP page or Java class file in the application while the server is running. Then you can touch the META-INF/application.xml file in the exploded directory (i.e., update the file's timestamp to current) to re-deploy the entire EAR application. This further saves significant amount of time for rapid turn-around agile developers.
In this Chapter, we covered the configuration files in the dvdcatalog application framework. We explained how the JBoss lightweight web application is packaged and how to leverage JBoss AS's agile deployment cycles.
From the next chapter, we will go through a series of tutorials around a DVD Store web application to study JBoss lightweight technologies in detail.