How to use J2EE

Basics

Just like you have your very own copy of Postgres that you can manage you have an instance of the Java Application server J2EE. Like mentioned above, all the J2EE files reside in the following directory:

/opt/j2eeXX/

You will note that there is a huge amount of documentation of the J2EE server available, which might be a little overwhelming at first. While you won't have to read it all, you can't get out of reading at least certain parts of it. One of the most important documents is Chapter 1: Getting Started of the administration guide.

While reading the documentation you must keep in mind that your installation uses different port numbers than the default ones. Here is a quick overview:

Description	Default port number	New port number
Admin console	4848	48XX
HTTP web server	8080	80XX

As always XX is the number of your user account.

The values above are those for the default administrative domain called domain1. Every J2EE server can run multiple so-called domains, each of which occupies different port numbers. For our project, however, there is no need to set up additional domains, you can use domain1 for all your work. If you still want to set up a second domain for testing, you must make sure that the port numbers do not conflict with those reserved for other groups. (Everything above 10000 should be save to use.)

The Administration Console

The administration console is the control center of your J2EE instance. It allows you to carry out all kinds of tasks like changing your password, deploying applications, etc.

To access it simply point your web browser at:

http://lsir-cis-pcY:48XX

This gives you the login screen where you enter the J2EE login data you have received via e-mail. After logging in you get to the welcome page ofthe administration console which looks like this:

Changing your J2EE administrator password is a good opportunity to get acquainted with the interface. The necessary instructions can be found here.

Note that you don't need to understand most of the settings. Some of the more interesting ones can be found right on the Common tasks page. Another interesting section is the list of Web Applications, but you will get to know this in more detail later on during the project.

Basic concepts

In J2EE there are a few very basic concepts that you should understand:

• Web modules (or web applications) are the smallest units used by the J2EE server. Each module consists of different files contained in a web archive (usually a .war file). These web archives can then be deployed to the server, where it provides a certain service to the users.
  [More details]

• Deploying is the process of uploading an application module to the J2EE server. Once deployed a module is immediately ready for use. There are many different ways of deploying a module, some of which you will see below.

• Undeploying is the process of removing a given application module from the J2EE server, thereby deactivating the service it provides.

• Packaging a web application is necessary to be able to deploy it to the server. It involves creating configuration files in XML format and adding the required files to create a web archive. As for deploying there are several ways to package a web module.

Tools

Java application server technologies rely on a number of tools that you can find in your /opt/j2eeXX/bin directory. These are the ones you will use most often:

• asadmin is the text-based administration tool of the J2EE server. You can get more information on how to use it by entering asadmin help on the command line.

• asant is a build tool based on Apache Ant. (If you don't know Ant, you should definitely have a look at it. It is very useful for compiling and managing all sorts of Java projects, a little similar to GNU Make.) The build.xml is to Ant/Asant what the Makefile is to Make. Read the Apache Ant manual to get familiar with the principles of the build system.

• deploytool is a graphical tool to help with packaging web modules. Don't forget to append the -X option when starting the SSH connection to enable X forwarding, otherwise you will get "Unable to start UI" error message when trying to start deploytool.

Another very important tool of a developer of web applications is of course the logfile where the J2EE server keeps track of errors (e.g. exceptions in Java code). By default it can be found at the following location:

/opt/j2eeXX/domains/domain1/logs/server.log

Even though the J2EE server usually outputs error messages to the client, you may find more complete information in that logfile. [More information on debugging J2EE applications]

JavaServer Pages (JSP)

JavaServer Pages are a powerful technology suitable especially to create dynamic web content. There are a few technologies based on JSP, some of which you will get to know in more detail as part of the project.

For starters you should have a look at some JSP components in action. We have prepared a few examples that should be easy to understand yet powerful enough so you can build your own applications based on the demonstrated techniques:

JSP examples

After you have seen how it works you should download the sources:

[JSP_Time.tar.gz] [JSP_SQLTag.tar.gz]

You can unpack the archives by entering tar xfz archive.tar.gz.

The Time JSP example

Let's start with the first example by examining the files and directories contained in the archive:

• src/ contains ordinary Java source files that can later be used from within JSP. For this example this is the Time class in the iis package that provides two functions that return formatted strings for the current time and date. Note that the main function is not technically necessary for JSP, but can be useful for testing purposes during development.

• web/ contains both static and dynamic web content that will be served by J2EE's web server. In the case of static content (e.g. simple html pages or images) the files will be served to HTTP clients as is. Dynamic pages, on the other hand, are internally compiled into Java servlets and are executed whenever a client request arrives. (The timefuncs.tld is a special file that we will talk about later.)

• build.xml The configuration file for asant that allows for automatic compilation, packaging, and deployment of the application. Try entering asant -projecthelp to see a list of available targets ("tasks" if you will). To run a given target just append its name to the call of asant, e.g. asant build.

  It is important to know that certain targets depend on other targets and that asant will automatically resolve and build these dependencies. For example if you run the deploy target, the build-war target will automatically executed since a .war file is necessary to deploy something. This in turn will cause the build target to execute because without it there is nothing to package, etc.

  The deploy and undeploy targets both need the password in the admin-password.txt file to be set correctly (see below).

• sun-web.xml The so-called runtime deployment descriptor that determines the URL prefix of the web application on the web server. You can see that the context-root is set to /time, which means that the application can be accessed at "http://machine:port/time".

• web.xml This file contains the so-called deployment descriptor and defines the visible name of the web application (in the admin console), in our example "time".

• admin-password.txt A simple text file containing the admin password of the J2EE server instance. It is used by asant to automatically deploy and undeploy the web module. Since this file contains the administration password for the J2EE server it has to be well protected, i.e. it must not be world readable.

Now let's build the example and deploy it to your server. Before you get started make sure that the admin-password.txt contains the correct password. If that's the case, run the build-war target to compile and package the module:

user01@lsir-cis-pc1:~/JSP_Time$ asant build-war
Buildfile: build.xml

prepare:
    [mkdir] Created dir: /home/user01/JSP_Time/build

copy:
     [copy] Copying 7 files to /home/user01/JSP_Time/build

build:
    [javac] Compiling 1 source file to /home/user01/JSP_Time/build

build-war:
     [echo] Creating the WAR ...
     [copy] Copying 1 file to /home/user01/JSP_Time/assemble/war/WEB-INF
     [copy] Copying 1 file to /home/user01/JSP_Time/assemble/war/WEB-INF/classes
     [copy] Copying 1 file to /home/user01/JSP_Time/assemble/war/WEB-INF
     [copy] Copying 6 files to /home/user01/JSP_Time/assemble/war
      [war] Building war: /home/user01/JSP_Time/assemble/war/time.war
     [copy] Copying 1 file to /home/user01/JSP_Time

BUILD SUCCESSFUL
Total time: 2 seconds
user01@lsir-cis-pc1:~/JSP_Time$

If everything went fine you should now have a file (the web archive) named time.war whose contents you can inspect using the unzip tool if you're interested:

user01@lsir-cis-pc1:~/JSP_Time$ l time.war
-rw-rw----  1 user01 user01 30053 Mar 27 01:34 time.war
user01@lsir-cis-pc1:~/JSP_Time$ unzip -l time.war
Archive:  time.war
  Length     Date   Time    Name
 --------    ----   ----    ----
        0  03-27-05 01:34   META-INF/
      107  03-27-05 01:34   META-INF/MANIFEST.MF
      837  03-27-05 01:34   index.html
    24388  03-27-05 01:34   garfield.gif
      744  03-27-05 01:34   timelet.jsp
      549  03-27-05 01:34   static.html
     1832  03-27-05 01:34   dynamic.jsp
      751  03-27-05 01:34   WEB-INF/timefuncs.tld
      314  03-27-05 01:34   WEB-INF/sun-web.xml
      883  03-27-05 01:34   WEB-INF/classes/iis/Time.class
     1282  03-27-05 01:34   time.jsp
      385  03-26-05 21:29   WEB-INF/web.xml
 --------                   -------
    32072                   12 files
user01@lsir-cis-pc1:~/JSP_Time$

Now you can already deploy the application to your J2EE server using the deploy target like so:

user01@lsir-cis-pc1:~/JSP_Time$ asant deploy
Buildfile: build.xml

prepare:

copy:

build:

build-war:
     [echo] Creating the WAR ...
   [delete] Deleting: /home/user01/JSP_Time/assemble/war/time.war
   [delete] Deleting directory /home/user01/JSP_Time/assemble/war/WEB-INF
     [copy] Copying 1 file to /home/user01/JSP_Time/assemble/war/WEB-INF
     [copy] Copying 1 file to /home/user01/JSP_Time/assemble/war/WEB-INF/classes
     [copy] Copying 1 file to /home/user01/JSP_Time/assemble/war/WEB-INF
      [war] Building war: /home/user01/JSP_Time/assemble/war/time.war
     [copy] Copying 1 file to /home/user01/JSP_Time

deploy:

admin_command_common:
     [echo] Doing admin task deploy time.war
[sun-appserv-admin] Executing: deploy --port 4801 --host localhost
--passwordfile "admin-password.txt"  --user admin time.war
[sun-appserv-admin] Command deploy executed successfully.

BUILD SUCCESSFUL
Total time: 4 seconds
user01@lsir-cis-pc1:~/JSP_Time$

You should now be able to access the web application at the following URL:

http://lsir-cis-pcY.epfl.ch:80XX/time

Tip: Sometimes you may want to access your web server from the console because you only have SSH access or just because it's faster. There is a text browser called ELinks installed that you can launch by simply entering elinks. Press q to quit, F9 to enter the menu, and \ to switch to HTML source mode (very useful for debugging JSP pages!). Everything else you need to know can be found in the man page and the online help.

The SQLTag example

The next example we're going to look at demonstrates the SQL Tag library which is part of the JSP Standard Tag Library (JSTL). This library provides a quick and dirty way of accessing a database from within a JSP page.

If you look at the source code you will see that the entire functionality is contained in a single file, namely index.jsp. It combines some of the techniques that you have seen in the Time example above. Let's look at a few key points:

• Everything surrounded by <%-- ... --%> is a JSP comment and will be stripped out by the server before delivering the page, i.e. unless standard HTML comments they will not appear in the page source.

• The first three non-comment lines enclosed by <%@ ... %> are so-called tag library directives that import the Core, SQL and Formatter tag libraries. The functions provided by these libraries can later be accessed by using the prefix defined here.

• In order to use the Postgres JDBC driver we need to load it like it is the case for an ordinary Java program. We do this from a scriptlet line (contained within <% ... %>) that contains just a single Java statement.

• The following two custom tags use the SQL Tag library (visible from the sql prefix) to connect to the Postgres database server and run a simple SQL query. Note that we are using an enhanced format of the JDBC date source string to specify the user and the password directly, instead of passing arguments to the getConnection() method (which isn't used here at all). More information about this technique can be found in the documentation of the PostgreSQL JDBC driver.

• Because this is such an easy example that doesn't do any postprocessing on the query result we can use a simple forEach loop and transform the date into an HTML table.

• To make the example a little more interesting the page is interspersed with a row counter that uses small scriptlet elements to declare, increase, and finally print an integer variable c.

Building and deploying this example works in much the same way as for the Time example above. Try it! (Make sure the empty directory src exists when you try to build the application. Alternatively you can also adapt the build.xml.) After you have deployed the application it is left up to you to find the right URL to access it in your web browser. :-)

Using the Deployment Tool

Next to using the asant build system there is another way to package and deploy web components. The Deployment Tool that comes with J2EE has a graphical interface and doesn't need any configuration files set up beforehand. Once again though, it is probably a better idea to use the build.xml files from the above examples and adapt them to your needs. You will see why in a minute. :-)

For the demonstration we will deploy another copy of the SQLTag example. So before we start you should create a copy of the JSP_SQLTag directory (say JSP_SQLTag2) and delete all files and directories therein except for web/index.jsp.

To start the Deployment Tool you must once again activate X forwarding or have the tool installed locally. If that is the case you can start it by entering deploytool on the command line. The following window should appear after a moment:

Step 1: Adding the server

First of all you have to add your J2EE server to the servers list. Choose File|Add Server... from the menu and enter the machine name and port number of your J2EE server. By checking the Target Server check box you make this server the default for deploying applications.

Select the new server in the list on the left and enter the username and password when you're asked. This should bring up the list of currently deployed applications.

Step 2: Creating a new web component

Choose File|New|Web Component... from the menu, which will launch the New Web Application Wizard. Click Next to skip the introduction screen.

Step 3: Choosing a location for the WAR file

Click Browse... in the WAR Naming area and select a place to store the .war file, e.g. JSP_SQLTag2/sqltag2.war. Don't worry about the WAR Display Name.

Step 4: Specify the Context Root

The Context Root field corresponds to the context-root XML element in the sun-web.xml file we have used above for asant. Pick a path where the component will be reachable, e.g. /sqltag2.

Step 5: Adding the content

Now comes the most important part, which is the selection of the content we want to add to the web archive. Click the Edit Contents... button to bring up the content chooser. Select the web/index.jsp file and then click the Add button:

Click the OK button to return to the wizard window:

Click Next to continue.

Step 6: Select the component type

Since we are about to package a JavaServer Page, pick the JSP Page option and click Next to go to the final step of the wizard.

Step 7: Define component properties

In the final step you can set some general properties of the component you are about to package. The only important setting here is the JSP Filename, where you should choose the main page, i.e. index.jsp in our case. You can leave the Web Component Name and Web Component Display Name as they are. (They will later appear in the subcomponent list in the admin console but are not visible otherwise.)

Now click Finish to close the wizard window.

Step 8: Checking your settings

Now you should see deploytool's main window again with all the settings that you have entered in the wizard:

Step 9: Deploying the web component

If everything is set up correctly you can deploy the application. Either choose 'Tools|Deploy...' from the menu or click the Deploy icon in the toolbar. After entering the username and password a status window should appear displaying the progress of the deployment process:

Done!

If everything went fine you can close the status window and access the web application in your browser.

Copyright © Martin Rubli & Patrik Bless – Last change:
This page uses valid XHTML 1.0 Strict and valid Cascading Style Sheets, Level 2. This page uses valid XHTML 1.0 Strict. This page uses valid Cascading Style Sheets, Level 2.