Java EE Packaging

During my off hours, I do a little teaching. The course I teach relates to Java EE and EJB development. Over the past 3 years that I've been teaching this course, I've realized there are quite a few common issues that students get hung up on. Initially, the issues with classpaths, packaging, and deployment are the biggest hurdles. So, here is an overview about the packaging of Java components. I just JBoss as an example, but most Java EE servers are handled in a similar way.

First, we have the Java ARchive, or jar, file. A jar file is one of the earliest package formats in Java, and can be used to compress, and package classes together in a neat library. In the EJB world, the jar is what you use to package your EJBs. You can package EJBs by themselves, and deploy them separately, or they can be included as an Enterprise application (more on that later). The jar file contains your classes, and a META-INF directory. The META-INF directory contains config and deployment descriptor files. To create a JAR file, just go to the top level of your class hierarchy and type "jar cvf jarFile.jar .". This will package your classes, properties, config, and deployment descriptor files into a single jar file. From here, you can deploy it straight to the Java EE server. It should be noted that some Java EE servers require some extra deployment descriptor files, refer to the vendor documentation for more information. However, in the case of JBoss, you can just copy the file into the "deploy" directory, and JBoss will run with it.

Upon deployment, JBoss will unpack the code, and set up the EJBs to be used. During the deployment, errors can happen. This is a good time to pay attention to the logs. Many problems happen with the deployment descriptors, or when you are using injection, with annotations. So, looking at the logs will help you to determine if the problems are runtime, or deployment time. A successful deployment would contain something similar to the following in your server.log, or standard output.

2010-12-29 10:01:08,666 INFO [org.jboss.ejb3.session.SessionSpecContainer] (HDScanner) Starting jar=MyTestEjbs.jar,name=HelloWorld,service=EJB3
2010-12-29 10:01:08,677 INFO [org.jboss.ejb3.EJBContainer] (HDScanner) STARTED EJB: awg.ejb.session.HelloWorldImpl ejbName: HelloWorld
2010-12-29 10:01:08,752 INFO [org.jboss.ejb3.proxy.impl.jndiregistrar.JndiSessionRegistrarBase] (HDScanner) Binding the following Entries in Global JNDI:
HelloWorld/remote - EJB3.x Default Remote Business Interface
HelloWorld/remote-awg.ejb.session.HelloWorldRemote - EJB3.x Remote Business Interface


The above log entry not only tells me that the ejb was deployed without problems, but it also give me some information about the ejb. For example, the JNDI name. In this case, the JNDI name is "HelloWorld/remote". This is very useful for when you are writing your client code.

Once the EJB is deployed successfully, you can use it in some client code. You can write a local client, or you can create a web based client. The important thing to remember when writing a client to access an ejb is that ejbs are considered remote objects. So, you need to supply some information in your code on where to find the references to the ejbs. This is commonly performed using the JNDI. If you are accessing the ejbs from a jsp, and it is deployed on the same server instance, then the access to the ejb is pretty simple. Just get a reference to the Initial Context of the JNDI, and pass in a String, for the name of the resource you are trying to get. For example, if we want a reference to the HelloWorld ejb I deployed, I would use the following code:

InitialContext ctx = new InitialContext();
awg.ejb.session.HelloWorldRemote hwr = (awg.ejb.session.HelloWorldRemote) ctx.lookup("HelloWorld/remote");


However, if we are using a client remotely, we need to write code that is more involved. For example, consider the following command line client:

package awg.client;

import java.util.Properties;
import javax.naming.Context;
import javax.naming.InitialContext;
import awg.ejb.session.HelloWorldRemote;

public class CommandLineHelloEJBClient {

 public static void main(String[] args) {
   try {
     // create an InitialContext, with JNDI properties
     Properties p = new Properties();
     p.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory");
     p.put(Context.PROVIDER_URL, "jnp://localhost:1099");
     Context ic = new InitialContext(p);

     // Get the a reference to the Remote Object from JNDI
     HelloWorldRemote client = (HelloWorldRemote)ic.lookup("HelloWorld/remote");

     // run methods on the ejb
     client.....();

   } catch (Exception e) {
     e.printStackTrace();
   }
  }
}

In the above example, I am giving the URL, jnp://localhost:1099, and the Context type.

With local clients, we can wrap them in jar files as well and run them from the local command line. But what about web resources, like JSPs? In the Java world, web resources can be packaged up in their own package as well. The Web ARchive, or war file. The WAR follows a specific directory structure to allow for easy deployment of web resources.

The top level directory is considered the webroot, and it contains JSPs, HTML, CSS, JavaScript files, images, and any other file you want to be exposed to the web. Within the webroot, there is also a WEB-INF directory. Inside the WEB-INF directory, config files, and deployment descriptors, are kept. Also in the WEB-INF directory, there is a directory for your classes, and a lib directory, for any libraries your'd like to package with your web application. To create a war file, just go to the webroot directory and type "jar cvf warFile.war .". This will package your web files, and additional classes and jars into a war file. From here, you can deploy it your Java EE server, just like you did with the ejb jar file.

The jar and war files are technically all you need to run your web files, and ejbs. But to make the deploying and submitting even easier, and cleaner, you can use an Enterprise ARchive, or ear, file.
The ear file is nothing more than a single package containing your war file(s), jar file(s), and deployment descriptors. To build an ear file, follow these steps:

1. Package up your ejbs into a jar file
2. Package up your web resources into a war file
3. Throw your war and jar files into a directory where you can package them together
4. Create a new directory called META-INF (under the directory containing your packages)
5. In the META-INF directory, create a deployment descriptor called application.xml.
   * The application.xml file defines the modules in your application.
6. From the directory containing your packages, package everything up as an ear file: jar cvf MyApplication.ear .
7. Deploy the ear to the JBoss deploy directory.

Seems like a lot of work, however, you can build Ant script, or use an IDE like Eclipse or Net Beans to do all of the heavy lifting. I'll talk more about that in another post.

The ear file makes deployment much more organized, and testing of the module is simpler. One thing to remember is that the Context lookup will be different with an ear, compared to using a war and jar separately. The ear context is basically the name of your ear file. For your lookup, you need to reference the ear context, when using JBoss. For example:

• I created an ear called MyApplication.ear. The file contains all of the examples from the class. changed all of the lookups to include "MyApplication/" at the beginning of the look up. If I deployed the war and jar files separate, the code in the HelloWorld client would look like this:
  HelloWorldRemote hwr = (HelloWorldRemote) ctx.lookup("HelloWorld/remote");
• However, since I am deploying it as an ear file, the code now references the ear context:
  HelloWorldRemote hwr = (HelloWorldRemote) ctx.lookup("MyApplication/HelloWorld/remote");

It should be noted that the JNDI names are not standard. Each Java EE server has it's own way for referencing ejbs on the JNDI. You may need to refer to documentation to get the format of the name. You can also use the ejb-jar.xml file in the META-INF directory of you ejb package, to customize the name, but there are still vendor specific formats tied in. That is why they are called by string names. If you write your code correctly, you can hold the names in a properties file, XML, or even a database. This will keep your code more portable. However, in EJB 3.1, JNDI names will be global and will follow a standard pattern that will make your code more portable across different application servers. But that is another story.

For more information, you can refer to the JBoss "Getting Started" documentation: https://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Getting_Started_Guide/beta500/html-single/index.html#Configuration_Files