Deploying and Consuming EJBs in Java Studio Creator

In Part 1 of this series, I described the steps to create a Session EJB-based API that was suitable for use within Java Studio Creator. Part 2 details the steps necessary to deploy and consume that EJB layer within Java Studio Creator (henceforth referred to as Creator for brevity). Part 3 will give more specifics on strategies to use and bind data from such an API in Creator.

Deploying the EJB Enterprise Archive to Sun App Server 8 PE

Deploying in J2EE can be quite an art. For use of the EJB API in Creator, there are really two distinct operations: deploying the EJB API, and deploying any support libraries needed for that API.

It is quite likely that your other tools, or persistence layer, or any one of a number of third-party libraries you have included in your middle-tier construction, bring dependencies in the form of support jar libraries that are needed within the classpath of the run environment to allow the eventual application to run. There are two options for providing these support libraries within the run stack. One is to bundle them into the API Ear, and the other is to make them available within the application server environment. I will give a brief description of each option below, along with advantages and disadvantages:

Deployment as Part of the Enterprise Archive

This is really the simplest option both to understand and to carry out. Any dependencies for the EJB API can be rolled into the EJB Ear file, usually the IDE you use to construct the EJB API will make this easy.

Advantages of this include an easily distributable Enterprise Archive with all dependencies already rolled into it, and little extra work needed in the deployment (just put the Ear file out there and everything necessary is already included).

The main disadvantage of this approach is size. With all of the support libraries included in the Ear file, it will get very large. If you have more than one application being put on a particular server, using the same persistence and other supporting libraries, you will end up with each Ear duplicating numerous files and taking up more space than is necessary.

Deployment Within the Application Server

Instead of rolling everything into the Ear, the other option is to take those libraries that are likely to be shared between Web applications and make them available to the whole application server. Following is a brief description of the steps necessary to do this in Sun App Server 8 PE (which is the application server used by Creator to run the applications):

• Under your Creator install directory, find the SunAppServer8 directory and the lib directory under there.
• Optional, but recommended, create a subdirectory under libs to hold your support libraries. You can just put them in the top level with all of the others, but it makes management and upgrade easier to make your own directory.
• Copy the support jar files into this directory.
• Start the deployment server from within Creator (Server Navigator, right-click on Deployment Server, select Start/Stop Server, and then click the Start Server button).
• When the server has started, open a Web browser and point it to http://localhost:14848; this will open up the app server admin UI. Log in as username: admin and password: adminadmin (unless you have changed from the defaults).
• Click on the JVM Settings tab; then the Path Settings sub-tab.
• In the Classpath Suffix text area, add the full pathnames on your machine to the jar files that you copied into the directory in the step above. This will make them available to the Application Server runtime.
• After adding all of the full paths to the jars (separated by newlines), click Save. You should notice at the top of the page a link that says Restart Required. Click on it and stop the server. The next time you, or the Creator IDE, starts it, it should have access to the libraries needed to support your API layer.

Deployment of Your Enterprise Archive file

Now you have the support libraries in place, it's time to deploy the enterprise archive file ready for Creator to consume it. A good guide to doing that is available from the Sun Java Studio Creator Web site: http://developers.sun.com/prodtech/javatools/jscreator/reference/techart/EJBcomps_building.html. Please refer to this for a more in-depth description of what to do. In a nutshell, the steps are:

• Ensure the deployment server is running inside of Creator (Server Navigator, right-click on Deployment Server, select Start/Stop Server, and then click the Start Server button if necessary).
• Start deploytool in the bin directory of the SunAppServer8 directory in your Creator installation. When it comes up, use File/Open and open the EJB Ear file you created.
• When it opens, you may get a warning about converting to J2EE 1.4 (if your current toolset supports J2EE 1.3). If you get this question, click OK to convert to J2EE 1.4. If this happens, make sure you save any changes (File/Save All) before proceeding.
• If you don't see a Server in the left pane called localhost:14848, add one (File/Add Server, fill in localhost and 14848 in the resulting dialog).
• Deploy your Ear to the creator (Tools/Deploy) and select the localhost:14848 from the Server list at the top, use username: admin, password: adminadmin. Also, check the box that says Return Client Jar and browse to a suitable location to save the resulting jar file. This is the file that Creator will use to access the beans.
• Click the OK button. It should deploy, but errors will show up in the dialog. These generally indicate missing libraries that the API is dependent on. Note them and add the necessary libraries using the procedure detailed in the previous section.
• This same set of steps can be used to re-deploy newer versions of the Ear file during development. It will simply replace the one already in the app server.
• Much more information on the deploytool and its use, as well as app server management and deployment in general, can be found in the excellent guide provided by Sun at http://devservices.sun.com/premium/jscreator/standard/learning/tutorials/aboutdeployment.html. Note, you will need a registered version of Creator to read this because you need a login to the site using your Creator serial number.

Consuming the EJBs Within Creator

Okay, we have deployed the EJB enterprise archive file, and we have the client stubs to access it. Now, we have to import those into Creator. This is pretty easy:

• In the Creator Server Navigator pane, right-click on the Enterprise Java Beans and select Add Set of Session EJBs.
• In the resulting dialog, enter a name for your set; for the server, use localhost; and for the RMI port, use 13700.
• Click the add button and navigate to the client API jar file you created within the deploy tool, and click Open.
• Click the add button. This should create your EJB set in the list of Enterprise Java Beans.
• Note that if you re-deploy a new version of the Session EJB API, you can simply right-click on the EJB set in the creator list and select refresh to update the references to it. Just make sure you save the client API jar file in the same location from deploytool as you imported it from into Creator. See the "gotchas: below for some notes on this.

Creator now knows about the EJB. To use it in a page, open the set and select the EJB you want to use, drag and drop it on the page, and it will create a reference to it on that page. It will do the lookup and narrow, and make it ready for your use in general. More information and examples on doing this exist in the http://developers.sun.com/prodtech/javatools/jscreator/reference/techart/EJBcomps_building.html document.

Some Gotchas

Refreshing the EJB API: after deploying a new version of the EJB API to the app server, you will want to update the references in Creator, and also in the projects that use that EJB API. The steps to do this are:

• When deploying the EJB API using deploytool, re-create the Client Jar, and make sure you save it in the same location that you told Creator to use for its EJB set reference. Then, right-click in Creator on the EJB set in question and click refresh.
• The above will update the reference that Creator has, but will not affect the projects that use it.
• To update the projects that consume this EJB set, I keep a page around that is empty and essentially unused. To update the EJB reference, remove the client jar from the Library References section in the Project Navigator pane for the project. Then, drag one of the beans from the set into the empty page, and this will re-create the client jar reference using the new details. You then can delete the EJB reference from the page; the libraries will remain pointing to the new details. The empty page can be used time and again for this purpose.

Conclusion

This article has covered in general the steps necessary to create an API based on Session EJBs suitable for use in a Creator project, and further, the consumption of that API using Creator. Examples were kept general when given, but tended towards explanation using the JDeveloper IDE that is what we use internally at NewEnergy Associates. It is hoped that these examples will provide enough insight to provide clues to accomplishing the same in other tools.

The article stops short of giving examples of actually writing Creator back-end code using the EJB API. There are examples of this in the document provided (Using EJBs in Creator), but it may also be something I cover in greater detail in future articles (particularly going into greater depth of returning serializable beans from the EJB API and using them to set data or even directly bind into a Creator page control).

For Further Information

http://www.informit.com/articles/article.asp?p=21630&rl=1—Creating Session EJBs

http://www.oracle.com/technology/obe/obe9051jdev/EJBtoJSP/defaultejb.htm—Oracle JDeveloper-specific EJB creation.

http://developers.sun.com/prodtech/javatools/jscreator/reference/techart/EJBcomps_building.html—Using EJBs in Creator.

http://devservices.sun.com/premium/jscreator/standard/learning/tutorials/aboutdeployment.html—Sun guide to deployment

About the Author

Dick Wall is a Lead Systems Engineer at NewEnergy Associates, a Siemens Company based in Atlanta, GA that provides energy IT and consulting solutions for decision support and energy operations. He can be reached for comment on this and other matters at dick.wall@newenergyassoc.com.