Web Application Setup and Deployment with JBuilder

by

John B. Moore

Micro-Phyla Systems

Introduction

Deployment is not something you should only think about after the application is finished. It should be built into the very development process. JBuilder integrates most of the setup and deployment process for web applications into the development process. The J2EE platform contains specifications by which the web application will be properly deployed into a web container via the WAR file (Web ARchive). This specification insures that the web application can deploy on any compliant server, or moved from server to server without any changes. There are some aspects of deployment that are server specific, but since servlet version 2.2, and increasingly with version 2.3, more of those server-specific variations are disappearing. JBuilder guides you through much of this by placing your web application resources in the "correct" place and providing the tools to set configurations via the web.xml file that are server neutral. Often what JBuilder is doing can seem mysterious, and one of the intents of this presentation is to "make sense" of much of what JBuilder is doing for you in this regard, as well as guide you through the setup process that will make all of this work correctly.

The first step is to understand the individual web components. Next, we will review the proper setup and how JBuilder sets up and manages each web component. Lastly, we will touch upon a number of deployment-related issues that will make your web application more self-contained, and not server specific. At the very end, a short overview that will indicate any variations that might appear in deploying the WAR file to several common Servlet containers. References will also be supplied at the end for further reading.

Web Components

Web components run and are managed within an environment called a web container. The web container provides such services as request dispatching, security, concurrency, session, and life cycle management. It also gives web components access to the J2EE platform APIs such as naming, transactions, and email. Web components must be installed (or deployed) into a web container before they can be executed. The components of a web application can consist of any of the following:

1. Static HTML pages
2. Servlets
3. JSP pages
4. JavaBeans
5. Resources: images, properties files, resource files, etc.
6. Support and utility classes

Any discussion of web components and deployment must be within the context of the Web ARchive (WAR). Remember that the web application can be deployed "unbundled" by copying the necessary components into the server specific locations. What the servlet specification brings to the table is to handle that complexity and possible "server specific" settings and placement for you. Where a servlet engine deploys the components no longer has to be of concern. Your only concern is to "bundle" the components into a "standardized" package. One last issue comes into play as we attempt to package the web application, and that is to insure that all references to resources within the web app will also deploy on all possible servers. Therefore, these "functional" issues of deployment will be touched upon as well.

Anatomy of a WAR

The fundamental unit of deployment for web applications is the WAR file (Web ARchive) which is basically a JAR file with extra "features" that are particular to web applications. That extra feature is referred to as "descriptive meta information" which ties all of the above listed web components together.

A good place to start is to review what the Servlet Specification has to say about the structure of a web application and "where things go". For this we look to the "Java™ Servlet SpecificationVersion 2.3". I would advise you to actually read this specification. I will only touch here on the key points that are needed for a fairly standard web application deployment.

Basic File structure

The web application will have a "root"directory. This directory's location will vary with the servlet engine. In Tomcat, this directory is called "webapps". The root of a web application would therefore be a folder below the webapps directory, (i.e. ./webapps/myAppRoot). In this root directory will be a folder labeled "WEB-INF". This directory will be set such that there is no public access to this directory and it's subdirectories. In the WEB-INF directory there will be two folders: "lib" and "classes". The "classes" directory contains any "unbundled" classes using the package for the directory structure. The "lib" directory contains all JAR files. Typically, the "classes" directory will contain the specific classes that are unique to this particular web application. Whereas the "lib" directory will contain common utility or third party JAR files. This is not a requirement, only an example of typical usage. The minimum directory structure, therefore, is illustrated as follows:

To summarize the basic minimal requirements:

For larger web applications, other directories, for example an "images" directory, can be added to manage and structure the application for ease of management. As an example of a more structured and detailed directory structure, the following includes a directory for configurations files (conf) , a directory to Tag libraries "tld" and a directory for javascript files.

"Context" and What This Means

Context is how the servlet engine references the root of the web application. It is an important concept and the word will be used frequently throughout any discussion of web application deployment. Most web servers have a default context configured as "/servlet".

http://localhost:8080/servlet/com.somepackage.theservlet

Using this in the URL tells the web server that this URL needs to be passed to the servlet engine.(Be that internal, or linked in as a separate servlet "engine", i.e. Apache and Tomcat) Note that the directory "/servlet" does not necessarily exist. (Earlier versions of ServletExec did have a "servlet" directory.) You can create other contexts that have that same function. (You can also create "extensions", but that is another topic) How this is configured can vary in each servlet-engine/web-server combination. But the ultimate effect should be the same. Essentially it is a URL pattern that you use as a "root" to reference "resources" for the web application. The web server "sees" this URL pattern and knows to forward the request to the servlet engine. For example, creating the web application context "CVPortal" would mean that when the web server sees that in the URL, it forwards that request to the servlet engine. The URL:

http://localhost:8080/CVPortal/com.somepackage.theservlet

would refer to some real path defined for the context "CVPortal", and the servlet (or JSP page) "com.somepackage.theservlet", wherever that might exist. (This can also reference static pages as well located at that context.). The real advantage here is that the bogus "/servlet" directory is not used and the URL is simpler and cleaner. Later we will take this even further by giving the servlet or JSP page an alias.

Essentially, the web server requires a configuration setting that tells the web server that a specific URL is to be handled by the servlet engine. This configuration can be different for each type of web server. In Apache this context is handled in the server.xml, and an example of a context configuration would be:

<Context path="/CVPortal" 

   docBase="webapps/TheAppHere"
   crossContext="false"
   debug="0"
   reloadable="true" > 
</Context>

A different directory was intentionally used for the "docBase" to illustrate the difference between the context name and the directory. In fact, it could be the same name. (e.g. "CVPortal") The "docBase" is the full path from the root web application directory, which in this case is "webapps". It is different for various servlet engines, therefore, check the documentation. See below for some default root directories for various servlet engines.

Don't confuse this "context" with the context "alias" created in the web.xml file (discussed next). This "context" is for the web server to properly "hand off" the request to the servlet engine, instead of handling the request as standard static HTML. In those cases where the Web server and the servlet engine are tightly integrated, the web server "context" and the servlet "alias" function of the web.xml configurations will appear to be the same. Be careful, this can be confusing. Also confusing is that some webserver/servlet combinations (for example, Tomcat can be used as a web server as well as a servlet engine) will create the necessary contexts from the very locations of the directories under the default root directories.

Deployment Descriptor

The deployment descriptor is found in the WEB-INF directory as "web.xml". This file can control most all aspects of the web application. There are 23 settings as listed below. We will only discuss in detail, a few of the more critical ones needed for basic configurations. It is important to at least be aware of the existence of other settings, so that, if needed in the future, you will at least know where to look for more information. Keep in mind that the order of these settings is very important, and that many of the settings come in groups. (This will usually be obvious.)

The "servlet" and "servlet-mapping" might be considered a minimum use of the web.xml. This allows the naming of servlets and JSP pages with shorter and easier to understand names. For example, a full standard URL for a servlet might be:

http://localhost:8080/CVPortal/servlet/com.theomegagroup.cvportal.ServletCtrl

can be shortened to something like:

http://localhost:8080/CVPortal/cvportalmgr

When working with the web.xml file, there are a number of specific "suggestions" that should be kept in mind at all times.

JBuilder supplies considerable help in managing the web.xml file. In the navigation pane, locate the web.xml file (found under "Deployment descriptors") and double click this file. The main pane will now display a GUI for editing the web.xml. Don't bother with the icon, name, and such. Note the "welcome files", as this will be a setting you should consider. Of fundamental importance is the setting up of the servlet or JSP name. To do this, locate the structure pane (just below the navigation pane) and right click "Servlets". A small dialog will appear.

Enter the "alias" name for the servlet and click "OK". The main display page will now appear with the name of the servlet.

The critical fields are the "Servlet class" or "JSP file", next the "Load priority" and any "Init Parameters".

<servlet>
   <servlet-name>Error</servlet-name>
   <servlet-class>com.somePackage.ErrorServlet</servlet-class> 
</servlet> 
<servlet-mapping>
   <servlet-name>Error</servlet-name>
   <url-pattern>/servlet/*</url-pattern> 
</servlet-mapping>

Once you complete the minimal information save, the project. Click the "Servlet" node and you will see the following page:

Enter the desired URL pattern (anything you want to use) and then the previously entered "servlet" name. The servlet name field has a drop down of all defined servlet names.

Click the "Source" tab and you will see that JBuilder has created the proper xml entries for you.

<web-app>
   <servlet>
      <servlet-name>cvcommunity</servlet-name>
      <servlet-class>com.theomegagroup.cvportal.CVCommunity</servlet-class>
   </servlet>
   <servlet-mapping>
      <servlet-name>cvcommunity</servlet-name>
      <url-pattern>/cvcommunity</url-pattern>
   </servlet-mapping> 
</web-app>

The servlet name has been entered as well as the servlet-mapping. This setup will be needed later when we setup the "Run" configuration.

Static Pages

Static pages are the base HTML and HTM files. These are generally placed in the root web application directory. For large sites you may need to create subdirectories and reference them from the web application root. References to resources within the static pages are relative to the page location.

JSP, JavaBeans, and Custom Tags

Like the static pages, the JSP is also generally placed in the web application root, or in specific sub-directories. References to resources can vary depending on whether the page was invoked directly or via a servlet. (This will be discussed in more detail later)

JavaBeans are stored in either the /WEB-INF/classes or the /WEB-INF/lib directories. JBuilder handles the location of these files seamlessly.

Custom JSP tags are made up of several components. The tag handler is stored similarly to JavaBeans. The TLD file should be stored in the WEB-INF directory or a sub-directory of the WEB-INF directory.

JBuilder WebApps Setup

JBuilder adds a fair amount of support for Servlet and JSP development, and it gets better with every release. So a good start is to do a quick overview of setting up for developing a web application. To a large degree, this is covered in the tutorials ("Working with WebApps and War files", "Creating Servlets", "Developing JSPs", "Working with web applications in JBuilder", and "Deploying your web application" - to name a few that would support material in this paper ). In past versions of JBuilder, I have often found those tutorials fragmented, missing the critical "gotchas" and missing steps that make a difference in understanding what is happening. Fortunately in JBuilder6, they have improved considerably over previous JBuilder releases, but still weak in some isolated areas. For example, I do not find the JSP wizard of any value, mostly because in serious websites, the design of the web page is done by a web designer, not the Java programmer. Because of this, the tutorial should include information that would help the user that is not using the wizard. Second, you don't generally have the JavaBeans that you might need, finished, such that you can just plug them in during the wizard process. A more useful wizard would be one that "imports" an HTML file and does some useful "conversions" (i.e. add the usebean tag..etc.) Also, "use JavaBean" command would be a nice practical touch for this "after the fact" inclusion. That being said, typically, the necessary steps are:

• Create a new Project.
• Add a WebApp to that project (JBuilder Tutorial covers this quite well)
• Copy your HTML templates to the root directory of your web app, renaming them to .jsp.
• Create the necessary sub-directories. Typically I use "conf" for my properties files, "images" for any image files, and "javascript" for all JavaScript files. Copy any files that you need into these directories.)
• Click the project refresh button and you will then see all of your added files.
• Go to project properties and add or remove any libraries you think you will need. (You can do more of this, at any time later)

Step-by-Step Example

Project: First, create a new project using the menu "File|NewProject". This is no different that a project that you create for any JBuilder application.

You will now end up with the following in your navigation pane.

WebApp: Next select "File| New" from the menu, and then select "Web Application".

The first step in the web application wizard is much more critical that it appears (One of the details not included in the tutorials). The "Name" is the name JBuilder uses for the webapp node and the WAR file. The "Directory" entry is the actual name of the directory that the project in placed in under the project directory.

You then end up with a structure in the navigation pane, as follows:

Click the "Make" button and JBuilder will next create the WAR file and add any other structure elements that are necessary.

The WAR file has now been added to your project. Double click the WAR file in the navigation pane, and you can view the structure of that file in the lower pane, as illustrated above. That actual file structure is a bit different (shown below in Explorer). This is because JBuilder only shows you those directories that apply to what you need to edit or view.

The root directory is your project directory. Off this directory there will be added, as needed, the "bak", "class", "src" and "work" directories. The web application directory is off the project directory, and within this directory, will be placed the actual web files.

You now have the basic setup completed. From here you can do the "custom stuff", adding extra directories to the web app directory to place additional files. You can then end up with a much more complex structure, as illustrated below:

From this point on, JBuilder will manage the rest by adding classes and libraries to WEB-INF to the project, as you add them. Your servlet classes will be added to the "classes" branch, and any jar's you add in the Project properties are added to the "lib" directory. As you work on the project, adding and removing files, JBuilder will keep this up-to-date. (Remember that if your project gets really big that you can turn off "auto WAR" creation so that the WAR file is only created when you right click on the WAR file and select "Make". In large projects this can be a real time saver, but generally in smaller web applications, JBuilder is so fast at this that you will hardly notice it is happening).

Our web application is now ready for serious work. JBuilder will maintain the files and keep everything in the right place. Added Servlets, JavaBeans, and JSPs (via the wizards) will be placed in the correct locations and added (or removed) to the WAR file as you work. You can now focus on the actual business solution at hand.

Development Phase Tips

Now comes the most amazing of JBuilder's features: That is the ability to completely run and test the web application in the IDE. What follows are some miscellaneous tips that will make the development process go smoother.

Run Configurations

Go to the "Run" menu and select "Configurations". Give this configuration a name that will show up on the Run button drop-down. Then click "JSP/Servlet" and put in the launch URL. This means you need to either point it to a JSP or a Servlet. If you have set up a servlet name and mapping (see web.xml discussion above) you should use the web application name (which becomes the "context") plus the target servlet or JSP name. The web application can now be run by clicking the little arrow next to the green triangle and selecting this "Run" configuration. You can also configure the (default) run configuration and only use that configuration. Generally, I have found that named configurations, even if there is only one, helps to later document what is happening in the project.

Output Console

Like all applications run in JBuilder, the server "out" is displayed in the console across the bottom. Remember that in between "pages" you can right click the console pane and select "Clear All". This makes it easier to separate the individual "outputs" when doing debugging.

Also, the output of Tomcat is placed in this window, formatted in red. This is handy, in that it shows a lot of the configuration and environment settings.

2002-02-15 08:52:45 - ContextManager: Adding context Ctx(  )
2002-02-15 08:52:45 - ContextManager: Adding context Ctx( /CustomJSP )
Starting tomcat. Check logs/tomcat.log for error messages 
2002-02-15 08:52:45 - Ctx(  ): Removing duplicate *.jsp -> jsp(org.apache.jasper.servlet.JspServlet/null)
2002-02-15 08:52:46 - Ctx(  ): File not found  D:\JBProjects\JSPApps\conf\tomcat-users.xml
2002-02-15 08:52:46 - path="" :jsp: init
2002-02-15 08:52:46 - Scratch dir for the JSP engine is: D:\JBProjects\JSPApps\work\localhost_8080
2002-02-15 08:52:46 - IMPORTANT: Do not modify the generated servlets
2002-02-15 08:52:46 - Ctx( /CustomJSP ): Removing duplicate *.jsp -> jsp(org.apache.jasper.servlet.JspServlet/null)
2002-02-15 08:52:46 - path="/CustomJSP" :jsp: init
2002-02-15 08:52:46 - PoolTcpConnector: Starting HttpConnectionHandler on 8080
2002-02-15 08:52:47 - PoolTcpConnector: Starting Ajp12ConnectionHandler on 8081
2002-02-15 08:52:48 - path="/CustomJSP" :debugjsp: init
2002-02-15 08:52:48 - JspEngine --> /CustomerBody_tlib.jsp
2002-02-15 08:52:48 - 	     ServletPath: /CustomerBody_tlib.jsp
2002-02-15 08:52:48 - 	        PathInfo: null
2002-02-15 08:52:48 - 	        RealPath: D:\JBProjects\JSPApps\JSPDev\CustomerBody_tlib.jsp
2002-02-15 08:52:48 - 	      RequestURI: /CustomJSP/CustomerBody_tlib.jsp
2002-02-15 08:52:48 - 	     QueryString: null
2002-02-15 08:52:48 - 	  Request Params: 
2002-02-15 08:52:48 - Classpath according to the Servlet Engine is: D:\JBProjects\JSPApps\JSPDev\WEB-INF\classes;D:\JBProjects\JSPApps\JSPDev\WEB-INF\lib\beandt.jar;D:\JBProjects\JSPApps\JSPDev\WEB-INF\lib\dx.jar;D:\JBProjects\JSPApps\JSPDev\WEB-INF\lib\interclient.jar;D:\JBProjects\JSPApps\JSPDev\WEB-INF\lib\log4j.jar
2002-02-15 08:52:48 - path="/CustomJSP" :debugjsp: init

The first bold section shows the creation of contexts by the "ContextManager". The first context is the default context for Tomcat (which is set for you in the "defaultroot" directory by JBuilder). The next context is the one created using your web application "name". Outside of JBuilder, this would be a web server specific setting (discussed earlier in the context section), but since Tomcat is being used as both the web server and the servlet engine, JBuilder is able to control both settings for you.

The second bold section shows the "scratch" directory. This is where the compiled servlets from the JSP pages are generated. You can view these servlets at a later time, as it can be instructive to see how a given JSP page is parsed into a servlet.

The third bold section indicates the final "path" that is considered the "root" by the JSP page. All resources will be located in reference to this path.

The last bold section provides some important properties that might help resolve resource or path problems. Also the QueryString and Request Params are displayed. This output can be really handy in tracking down problems.

Accessing the Web Application in an External Browser

Often it is necessary to run your web application outside of the JBuilder IDE. You can do this by deploying the entire application to a free standing web server and servlet engine. There is also another way! Use JBuilder as the web server and servlet engine. To do this, run the web application in the IDE as normal.

In the location window copy the URL.

Paste this URL into your favorite browser and you should be off and running. You will still be able to view the console output in JBuilder as before, but now you can view the full effect of your pages in the browser of your choice.

Additional Notes on Handling Resources and Configuration Files

One of the most frustrating issues that you face in creating a web application that will seamlessly deploy on any server, is to insure that all resources and configuration files are "visible" to your servlets and pages. Servlets and JSP pages have different "root directories" and this will create some confusion. To add to the confusion, JSP pages that are dispatched from a servlet must be treated like a servlet reference because it was the servlet that set up the "root" for that page.

To help keep all of this straight, there are a number of approaches to insure that your resources are always available, regardless of where or how your pages are loaded.

Use the Web Application "context" in the URL

This is the simplest "quick fix". If your application will not be migrating from server to server, this is probably a good solution. But if your web application needs to be deployed in a number of locations, this might require editing many pages, if the root context is ever changed. In that case, it would not be a good solution. To use the web application root context, just append the root context to any resource URL, as follows:

In this case, "WebAppDemo" is the root web application context. (See the discussion on Context, above)

Get the Context Path

This fix involves a bit more up-front work, but it has the advantage of being independent of any "hard-wired" settings. The request object contains the "context path", and this can be used to dynamically place the correct path in front of any resources.

Generally, this is the recommended "fix", because it requires the least maintenance.

I have found other "fixes" listed in various sources. Frankly, I have not had any luck getting them to work in all situations. The above two solutions have worked in every situation I have encountered.

Accessing Property and Other Files

In addition to linking in image files, there are times when you need to access specific files, either as property files or other miscellaneous files. Again, you want to avoid hard-wiring the file path. Following is an example of a method that loads a property file based on the servlet context:

public void loadProp(ServletContext arg_appcontext, String arg_sFile) {
       this.g_sFile = arg_sFile;
       g_inputStrm = arg_appcontext.getResourceAsStream(g_sFile);
     if (g_inputStrm == null) {
        System.out.println("   ServletCtrl - propfile not found");
     }
     try {
          g_ctrprop = new Properties();
          g_ctrprop.load(g_inputStrm);
    } catch (Exception ex) {
           System.out.println("Error reading site properties \n  "+ ex);
    }
}

The key is the method "getResourceAsStream(..)" method. This method is called in the controller servlet as follows:

this.g_siteprop = (SitePropertiesBean)this.g_appcontext.getAttribute("SiteProps");
     if (this.g_siteprop == null) {
        //load properties and pass to application object
        g_logCategory.debug("CVCommunity - New SiteProperties created");
        this.g_siteprop = new SitePropertiesBean();
        this.g_siteprop.loadProp(g_appcontext,"conf/cvportal.properties");
        this.g_appcontext.setAttribute("SiteProps",this.g_siteprop);
}

Above, the site property object is stored in the application context and if it is not available it is created fresh. The path given is always relative to the root web application directory.

Final Deployment

The application is finally at a point where it needs to be deployed on the target server, either for testing or production. Because we have focused on using the WAR file, our deployment becomes a simple two step process.

• Set up the server specific "Context". (See web server documentation)
• Copy the WAR file to that server's web application root (varies from server to server, as listed above)
• Restart the servlet engine.

In practice, I generally have the WAR file directly written to my test deployment web server so that whenever I want to test the full site, all I have to do (Tomcat specific) is shut down the servlet engine, delete the web application directory, then start the servlet engine. The WAR file is then automatically deployed and ready for testing.

Server Specific Deployment Issues

Fortunately, the latest Servlet specification has standardized the vast majority of all deployment settings. Following is a quick listing of the few remaining server specific issues that apply to the deployment and setup of web applications on that servlet engine.

TomCat 3.2

Disabling the Invoker: In the "conf/server.xml" include the following:

<RequestInterceptor>
   className="org.apache.tomcat.request.InvokerInterceptor"
   debug="0" prefix="/servlet/*"/>

WebApp Root:

Security: User roles and passwords are server specific settings. (../conf/tomcat-users.xml)

TomCat 4.0

Disabling the Invoker: In the global web.xml found in the "conf" directory, comment out the following:

<servlet-mapping>
   <servlet-name>invoker</servlet-name>
   <url-pattern>/servlet/*</url-pattern> 
</servlet-mapping>

WebApp Root:

Security: User roles and passwords are server specific settings. (../conf/tomcat-users.xml)

JRun

Disabling the Invoker: (v3.1) In the file "install-dir/lib/global.properties" and commenting out the line with a "#" that reads:

WebApp Root:

Security: User roles and passwords are server-specific settings. (See documentation)

ServletExec

Diabling the Involker: This is not possible in ServletExec 4.0. (The web.xml method outlined earlier, also does not work in v4.0 but does work in v4.1).

WebApp Root:

Security: User roles and passwords are server specific settings. (See documentation)

Wrap up

Using JBuilder, the entire deployment process can be integrated into the development of the web application. All of the configuration settings need by JBuilder are the same settings used by the target servlet engine. The Java Web Deployment specification now covers the vast majority of the configuration issues, making the goal of a truly ubiquitous deployment module , the WAR file, very close to a reality. The server specific "loose ends" are few and minor. Hopefully, I have exposed enough of the details of this process, that you can leverage this knowledge in your own web application development.

Enjoy!

References

Links

WebComponent Tutorial - http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/WebComponents.html

Writing Enterprise Applications with JavaTM 2 Platform, Enterprise Edition - http://developer.java.sun.com/developer/onlineTraining/J2EE/Intro/

Installing and Configuring TomCat - http://www.onjava.com/pub/a/onjava/2001/03/29/tomcat.html

Using TomCat - http://www.onjava.com/pub/ct/33

Application Developer's Guide - TomCat 4.0.x - http://jakarta.apache.org/tomcat/tomcat-4.0-doc/appdev/index.html

Java Servlet 2.3 Specification and JavaServer Pages 1.2 Specification - http://jcp.org/aboutJava/communityprocess/first/jsr053/index.html

Books

More Servlets and JavaServer Pages, Marty Hall, Sun Microsystems Press, ISBN 0-13-067614-4. This is a just-released book that covers material that most other Servlet and JSP pages do not cover in much detail. I consider it a "must have" book.