INFORME DE ENSAYO DE APROBACIÓN DE PATRONES

As I mentioned earlier, seam-gen pro-duces projects that are configured to deploy to JBoss AS out of the box. For now, let’s stick with the convention to keep the effort of getting the applica-tion running to a minimum. Once you’re comfortable with that, you can explore alternatives.

You can take one of two paths when deploying your application to JBoss AS. You can either deploy it as a packaged archive:

seam deploy

or you can deploy it as an exploded archive:

seam explode

These two alternatives are illustrated in figure 2.6.

NOTE Despite its alarming name, the explode command will not perform a destruc-tive process on your project. It simply copies the deployable files to the applica-tion server without packaging them. The name is meant to indicate that the archive is broken open as if it had been “exploded.” A more reassuring name for this command might have been “unfurl” (like a sail). But explode just sort of stuck.

Let’s weigh the attributes of each command and decide which one is best to use.

2.4.1 To deploy…

If you use the deploy command, the build will create an archive that uses one of two stan-dard Java EE package formats, Web Archive (WAR) or Enterprise Archive (EAR), depend-ing on which one you chose durdepend-ing the seam-gen setup routine. If you plan to use only JavaBean components, like the example application presented in this chapter, your best

Figure 2.6 The two deployment scenarios offered by seam-gen. On the left, an exploded WAR (or EAR) directory. On the right, a packaged WAR (or EAR) file. Incremental hot deployment is not available when using a packaged archive.

choice is the WAR format. In this case, the deploy command packages the application into the WAR file open18.war. If you intend to use EJB components in your application, you must use the EAR format. In that case, the deploy command will create the EAR file open18ee.ear for an application named open18ee. The sample code that accompanies the book includes projects for both archive formats. Note, however, that once you make a choice between WAR and EAR, you’re stuck with it. There is no built-in seam-gen com-mand to toggle a project between the two archive formats.

Once the archive has been packaged, seam-gen moves it to the deployment directory in the default domain of the JBoss server, located at ${jboss.home}/server/default/

deploy. The JBoss server monitors this directory for changes. When a new or changed archive is detected, the application is “reloaded.” This feature is known as “hot deploy,” but it’s not just about deployment. The server also recognizes when an archive has been removed from this directory and subsequently unloads the applica-tion. You can remove the deployed archive by running

seam undeploy

The downside to using a packaged archive is that every change you want to apply requires a complete build, package, and deploy cycle. At the end of this cycle, a fresh version of the archive is shipped off to the server, the old application is unloaded, and finally, the new application is loaded. In this case, we’re talking about hot-deploying the application as a whole rather than incremental changes, which is cov-ered later. It’s all or nothing. During a reload, the JBoss server shuts down all the ser-vices that were started by your application. These serser-vices include the database connection, the JPA EntityManagerFactory (or Hibernate SessionFactory), the Seam container, and perhaps others. When the new application is deployed, all of these services are started again under the new deployment. This process can be very time consuming—and that time increases as your project grows and more services have to be stopped and started.

Packaging Java EE applications

There are three prominent archive types that can be used to deploy components to a Java EE–compliant application server. A Web Archive (WAR) is the format with which most people are familiar. A WAR bundles servlets, JSPs, the archive is static resources, and supporting classes for the purpose of serving dynamic web pages.

EJBs are deployed in the pervasive Java Archive (JAR) format, except that the archive is augmented with a special XML deployment descriptor that identifies it as an EJB JAR. Both the WAR and JAR formats are Java EE modules that can be bun-dled inside an Enterprise Archive (EAR), which deploys the containing modules under the same classloader, presenting them as a single application. The EAR is the standard packaging unit for a Java EE application. Basic servlet containers, such as Tomcat, can only handle WAR packages.

To make matters worse, reloading an application terminates all of its active HTTP sessions. If the page you’re testing requires you to be authenticated, or otherwise holds state, you’ll be forced to reestablish your place. Needless to say, the packaged deployment isn’t recommended for development. The good news is that there’s a bet-ter way.

2.4.2 …or to explode

The alternative to a packaged deployment is an exploded archive. An exploded archive is a WAR or EAR that has been extracted into a directory that has the same name as the archive. You can deploy the application as an exploded archive using the seam explode command.

The explode command is a slight variation on the deploy command. Like the deploy command, the explode command assembles the deployable files into the struc-ture of the archive in the build directory. But the explode command skips the bundling step and just copies the build directory in its raw form to the server. Subsequent calls to seam explode synchronize the changed files to the exploded archive directory on the server, thus supporting incremental updates. How the application deals with its changes is determined by its hot deployment capabilities. Section 2.5.1 examines incre-mental hot deployment and what it means in terms of development.

To force a reload of the application when using an exploded archive deployment, mimicking the behavior that occurs when a package archive is dropped into the hot deployment directory of JBoss AS, you use the restart command. As its name may imply, this command doesn’t restart the JBoss AS—it just reloads the application.

The restart command begins by mirroring the work done by the explode com-mand. As a final step, it updates the timestamp of the application deployment descrip-tor, which is application.xml, in the case of an EAR deployment, or web.xml, in the case of a WAR deployment. When the application server detects that the timestamp of the application deployment descriptor has changed, it triggers a reload. To remove an exploded archive, and have it undeployed, you execute

seam unexplode

The explode command is best suited for development. With support for incremental updates, it gives you the “instant change” capabilities that you may be familiar with if you’ve ever developed in a scripting language like PHP. The degree to which a Seam application supports instant change will be put to the test later.

To summarize your options, you can use the deploy command to deploy a package archive or you can use the explode command to deploy an exploded archive. The undeploy and unexplode commands serve as their complements by removing the archive from the server. That covers the deployment life cycle to a single environment.

seam-gen sets up your project with additional deployment profiles, which allow you to tune the archive based on environment, possibly even deploying it to a different server instance. Let’s take one more tangent to learn about deployment profiles before we move on to starting JBoss AS.

2.4.3 Switching between environments

The build that seam-gen creates for your project supports the concept of deployment profiles. Profiles can be used to customize deployment descriptors and configuration settings for different environments. To cite a common case, you may need to use a dif-ferent database in production than the one used in development. You certainly don’t want to be burdened with having to switch the database connection settings every time you cut a production release. Instead, you can set up a profile for that environment, which you can activate with a single flag when executing the production build. The appropriate database settings, and any other settings specific to that environment, will then be applied.

Seam configures three profiles out of the box: dev, prod, and test. The test profile is a special case, which we look at next. By default, Seam uses the dev profile when com-mands are executed. You can enable a different profile by changing the value of the Ant profile property. Adding the following key-value pair to the build.properties file in the root of the project activates the prod profile, effectively deactivating the dev profile:

profile=prod

Having to change the build.properties file feels too manual for my taste. As another option, you can set the profile property from the seam command:

seam clean deploy -Dprofile=prod

TIP When you switch profiles, it’s a good idea to run clean—and possibly even undeploy or unexplode—prior to running deploy or explode to be sure that settings from the previous profile do not linger.

As I mentioned, the test profile is handled as a special case. It’s not activated using the profile property. Instead, there are special Ant targets for running tests that know to use the test versions of the environment-specific files. Writing and executing tests will be covered in chapter 4.

Table 2.4 itemizes the files that are selected according to the active profile, indicat-ing whether the file is used in the case of the test profile. These files contain settindicat-ings and configurations that you have control over between environments. You can intro-duce your own profile, such as qa, by creating each of the files listed in table 2.4.

When naming the file, replace the token %PROFILE% with the name of the profile.

For instance, the build properties file for the qa profile would be build-qa.properties.

Table 2.4 Files that are selected based on the profile property value

File selected based on profile value Purpose of file Used in test profile?

build-%PROFILE%.properties Used to set Ant build proper-ties, such as the location of the JBoss AS deploy directory and the debug mode flag

No

resources/META-INF/persistence-%PROFILE%-war.xml The JPA persistent unit config-uration file

Yes

If you want to change the location of the JBoss AS deploy directory for a production build, you can set the jboss.home property in build-prod.properties. You probably want to disable debug mode as well, since it’s only desirable in development:

jboss.home=/opt/jboss-production debug=false

You now know how to deploy and undeploy the application to the JBoss AS deploy-ment directory, both as a packaged archive and an exploded directory structure. You can also control the settings and configurations for the target environment, such as development, QA, or production, by toggling the value of the profile property. With-out further ado, let’s fire up JBoss AS and see what the application looks like.

2.4.4 Launching JBoss AS

Without any customization, JBoss AS runs on port 8080, so first ensure this port isn’t already in use (be aware that Apache Tomcat also runs on port 8080 by default). In your console, navigate to the JBoss AS installation directory, ${jboss.home}, and then descend into the bin directory. If you’re using a Unix platform, execute the command:

/run.sh

If you’re on Windows, execute the command:

run

These scripts start the default domain of the JBoss AS server. As an alternative to using the console, you may also choose to launch JBoss AS from your IDE. Eclipse, NetBeans, and IntelliJ IDEA all support launching the JBoss Application Server.

Keep an eye on the console while the server is starting to watch for any exceptions that may occur. When the console output settles down, the final line should give you the thumbs up that JBoss AS is running:

00:00:00,426 INFO [Server] JBoss (MX MicroKernel) [4.2.2.GA (build:

[CA]SVNTag=JBoss_4_2_2_GA date=200710221139)] Started in 17s:14ms

If you’re using the Sun JVM, I can almost guarantee that when you start hot-deploying applications to JBoss AS, you’re going to get out-of-memory errors using the default JVM

resources/import-%PROFILE%.sql A SQL script that will be used to load seed data into the database when the applica-tion starts if the database is being re-created each time

Yes

resources/open18-%PROFILE%-ds.xml^a The data source configuration file for JBoss AS

No

a. Named according to the application, which in this case is open18.

Table 2.4 Files that are selected based on the profile property value (continued)

File selected based on profile value Purpose of file Used in test profile?

options. I strongly urge you to follow the advice in the accompanying sidebar. These set-tings can be applied to the JBoss AS runtime configuration either by adding them to the

${jboss.home}/bin/run.conf or by using the configuration screen in the IDE.

If⁶JBoss⁷AS started cleanly, you can open your browser and point it to http:// local-host: 8080/open18 to see the result of your work. In the next section, I walk you through the application and point out the work seam-gen has done for you. I then demonstrate how you can continuously make changes to the application without hav-ing to suffer the wait of restarthav-ing either the application or the server.