Migrating Web Applications From Apache Tomcat 5.x to Sun Java System Web Server 7.0

   
By Krishnamohan (Krishna) Meduri and Marina Sum, May 31, 2006  

Sun Java System Web Server 7.0 (henceforth, Web Server 7.0), now in Technology Preview 1, supports the Java Servlets 2.4, JavaServer Pages (JSP) 2.0, and Java Standard Tag Libraries (JSTL) 1.1 specifications. This article explains how to migrate Web applications—servlet and JSP examples—on Apache Tomcat 5.5.16 (henceforth, Tomcat) to Web Server 7.0. You'll also learn how to create user accounts in file-based realms. Lastly, this article steps you through the configuration procedures for a Java Naming and Directory Interface (JNDI) application with Java Database Connectivity (JDBC) Datasource and the set up procedure for Secure Sockets Layer (SSL).

Note that this article is intended as a quick start guide only. For details, see the documentation for Web Server 7.0.

 

Contents
 
Setup for Administration Server CLI
Assumptions, Terminology, and Prerequisites
Servlet Examples
JSP Examples
Example of JNDI With JDBC Datasource
SSL Configuration in Web Server 7.0
References
 
Setup for Administration Server CLI

You perform administration tasks for Web Server 7.0 either from its Administration Console or from the command-line interface (CLI). This article uses the CLI tool wadm, which resides in WS7_INSTALL_ROOT /bin, where WS7_INSTALL_ROOT is the root installation directory of Web Server 7.0.

Note: Even though some of the command lines in this article wrap as multiple lines, type them all in one line.

To execute wadm commands, enter the password when wadm prompts you. Alternatively, you can set up a password file and pass it as an argument to the --password-file option, as described below. You need the password file to execute wadm commands directly on your command shell or automate them from your scripts. This article uses the password-file approach.

To set up a password file, choose any file name (say, admin.passwd) and add the following line to the file:

wadm_password= admin_password

Before you can run wadm commands, except for --help, you must first start the Administration Server. To do so, type:

% cd WS7_INSTALL_ROOT /admin-server/bin

% ./startserv

Assumptions, Terminology, and Prerequisites

This article assumes that you have installed Web Server 7.0 and Tomcat. Here are their download sites: Web Server and Tomcat. Following are the conventions for this article along with a few hints and tips:

  • WS7_INSTALL_ROOT refers to the installation root directory of Web Server 7.0.
  • CATALINA_HOME refers to the installation directory of Tomcat.
  • The forward slash ( /) is the UNIX file separator. If you run Windows, use the reverse slash ( \) instead.
  • This article assumes a configuration named config1 and a virtual server, also named config1, on the config1 configuration. Therefore, for wadm commands, config1 is the argument for both the --config and --vs (virtual server) options. You must replace config1 with the appropriate values.

    For a list of the existing configurations, type:

    % ./wadm list-configs --user= admin_user --password-file= admin_passwd_file --host= admin_host --port= admin_ssl_port --config= config1

    For a list of the existing virtual servers on config1, type:

    % ./wadm list-virtual-servers --user= admin_user --password-file= admin_passwd_file --host= admin_host --port= admin_ssl_port --config= config1

    Note: Be sure to type in an existing configuration for config1, the value for the --config option.

    In the above command, admin_host is the host on which Administration Server runs. admin_ssl_port is the Administration Server's SSL port number. Henceforth in this article, for wadm commands, we omit these two options on the assumption that admin_host is localhost and admin_ssl_port is 8989 (default). You must supply these options appropriately if the values are different.
  • In this article, https- config1 refers to the instance name. When you type the command, replace config1 with its value, as appropriate. For a local installation, where the Administration Server and instance are on the same host, the directory https- config1 is under WS7_INSTALL_ROOT.
  • The wadm command lines in this article are for illustration only. Be sure to customize them according to your requirements. You might want to review all the options for the commands. The wadm --help command outputs a list of all the wadm commands. To get help on a specific command, type:

    % ./wadm command_name --help

    For example:

    % ./wadm list-configs --help

    If the output scrolls up too fast, pipe it to more:

    % wadm command_name --help | more
Servlet Examples

A Web application called servlets-examples resides in CATALINA_HOME /webapps. This section explains the Tomcat configuration for that Web application and describes the procedures for ensuring that the application also works on Web Server 7.0.

 

web.xml


Let's first look at a snippet of the web.xml file that relates to security constraint. Note, in particular, the role names used by this application.

<security-constraint>
    <display-name>Example Security Constraint</display-name>
    <web-resource-collection>
        <web-resource-name>Protected Area</web-resource-name>
        <!-- Define the context-relative URL(s) to be protected -->
        <url-pattern>/jsp/security/protected/*</url-pattern>
        <!-- If you list http methods, only those methods are protected -->
        <http-method>DELETE</http-method>
        <http-method>GET</http-method>
        <http-method>POST</http-method>
        <http-method>PUT</http-method>
    </web-resource-collection>
    <auth-constraint>
        <!-- Anyone with one of the listed roles may access this area -->
        <role-name>tomcat</role-name>
        <role-name>role1</role-name>
    </auth-constraint>
</security-constraint>

<!-- Security roles referenced by this web application -->
<security-role>
    <role-name>role1</role-name>
</security-role>
<security-role>
    <role-name>tomcat</role-name>
</security-role>

From the above snippet, you can see that this application refers to the roles mentioned under <auth-constraint> and requires that users or groups be created for those roles. This configuration is hosting server-specific. See the sections that follow for details.

Note: During migration to Web Server 7.0, web.xml remains unchanged. This rule is true for any Web application.

 

Tomcat Configuration


Look at the tomcat-users.xml file, which resides in CATALINA_HOME /conf. The file reads as follows.

<tomcat-users>
    <user name="tomcat" password="tomcat" roles="tomcat" />
    <user name="role1" password="tomcat" roles="role1" />
    <user name="both" password="tomcat" roles="tomcat,role1" />
</tomcat-users>

This file maintains the authentication information. As you can see, users are defined for each of the roles. Web Server 7.0 takes a different approach. See the next section.

 

Web Server 7.0-Specific Configuration


In Web Server 7.0, you must specify a mapping for the security roles in the Web application's sun-web.xml file and then configure Web Server 7.0, as explained below.

sun-web.xml

The sun-web.xml file is the runtime descriptor associated with a Web application. Following is how the file reads for servlets-examples. As you can see, the principal names are associated with the roles.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server
8.1 Servlet 2.4//EN"
    "http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_4-1.dtd">
<sun-web-app>
    <security-role-mapping>
        <role-name>tomcat</role-name>
        <principal-name>tomcat</principal-name>
    </security-role-mapping>
    <security-role-mapping>
        <role-name>role1</role-name>
        <principal-name>role1</principal-name>
    </security-role-mapping>
</sun-web-app>

Create the file as above and place it in your Web application's WEB-INF directory ( CATALINA_HOME /webapps/servlets-examples/WEB-INF).

Web Server 7.0 Configuration

In Web Server 7.0, you create users mentioned under <principal-name> in sun-web.xml and then deploy the Web application. Follow these steps:

  1. Set up wadm (see the section, Setup for Administration Server CLI).
  2. Add the Web application. Do the following:

    % cd WS7_INSTALL_ROOT /bin

    % ./wadm add-webapp --user= admin_user --password-file= admin_passwd_file --config= config1 --vs= config1 --uri=/servlets-examples --file-on-server CATALINA_HOME /webapps/servlets-examples
  3. Create the users for this Web application. First, edit admin_passwd_file and add this entry as a new line:

    wadm_user_password=tomcat

    In the tomcat-users.xml file, the password for all users is tomcat. With this new entry in admin_passwd_file, you are specifying the same password, tomcat. While creating a user, wadm reads this password and encrypts it before storing it in the authentication database.

    Note: Delete users before creating them. If wadm fails for the delete command, just ignore the error message. Type the following:

    % ./wadm delete-user --user= admin_user --password-file= admin_passwd --config= config1 --authdb=default tomcat

    % ./wadm create-user --user= admin_user --password-file= admin_passwd_file --config= config1 --authdb=default tomcat

    % ./wadm delete-user --user= admin_user --password-file= admin_passwd_file --config= config1 --authdb=default role1

    % ./wadm create-user --user= admin_user --password-file= admin_passwd_file --config= config1 --authdb=default role1
  4. Deploy the changes to config1. Type:

    % ./wadm deploy-config --user= admin_user --password-file= admin_passwd_file config1
  5. Start the https- config1 instance. Type:

    % cd WS7_INSTALL_ROOT /https- config1 /bin

    % ./startserv

The output before the line successful server startup shows the host name and the port number that are ready to accept requests. Use those values to access http:// hostname : portnumber /servlets-examples/ to verify that the Web application works.

JSP Examples

Another Web application, called jsp-examples, resides in CATALINA_HOME /webapps/jsp-examples. This section explains the Tomcat configuration for that Web application and describes the procedures for ensuring that the application also works on Web Server 7.0.

 

web.xml


Let's first look at a snippet of the web.xml file that relates to security constraint. The <security-constraint> tag is identical to that in the web.xml file for servlets-examples. Note, in particular, the role names used by this application. Since the role names for this application and servlets-examples are the same, the Tomcat configuration for servlets-examples also applies to this application.

<security-constraint>
    <display-name>Example Security Constraint</display-name>
    <web-resource-collection>
        <web-resource-name>Protected Area</web-resource-name>
        <!-- Define the context-relative URL(s) to be protected -->
        <url-pattern>/security/protected/*</url-pattern>
        <!-- If you list http methods, only those methods are protected -->
        <http-method>DELETE</http-method>
        <http-method>GET</http-method>
        <http-method>POST</http-method>
        <http-method>PUT</http-method>
    </web-resource-collection>
    <auth-constraint>
        <!-- Anyone with one of the listed roles may access this area -->
        <role-name>tomcat</role-name>
        <role-name>role1</role-name>
    </auth-constraint>
</security-constraint>

<!-- Security roles referenced by this web application -->
<security-role>
    <role-name>role1</role-name>
</security-role>
<security-role>
    <role-name>tomcat</role-name>
</security-role>

 

Web Server 7.0-Specific Configuration


As in servlets-examples, the Web application's sun-web.xml file and the Web Server 7.0 configuration apply.

sun-web.xml

Here is how the sun-web.xml file reads. Again, the principle names are associated with the roles.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server
8.1 Servlet 2.4//EN"
    "http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_4-1.dtd">
<sun-web-app>
    <security-role-mapping>
        <role-name>tomcat</role-name>
        <principal-name>tomcat</principal-name>
    </security-role-mapping>
    <security-role-mapping>
        <role-name>role1</role-name>
        <principal-name>role1</principal-name>
    </security-role-mapping>
</sun-web-app>

As in servlets-examples, you create the file as above and place it in your Web application's WEB-INF directory ( CATALINA_HOME /webapps/jsp-examples/WEB-INF).

Web Server 7.0 Configuration

If you have already configured Web Server 7.0 for servlets-examples, all you need to do is add the Web application and deploy the configuration changes to the instance that runs config1, as follows:

% ./wadm add-webapp --user= admin_user --password-file= admin_passwd_file --config= config1 --vs= config1 --uri=/jsp-examples --file-on-server CATALINA_HOME /webapps/jsp-examples

% ./wadm deploy-config --user= admin_user --password-file= admin_passwd_file config1

Otherwise, repeat the steps in the previous section on the Web Server 7.0 configuration, except that, to add the Web application (step 2), type this command line instead:

% ./wadm add-webapp --user= admin_user --password-file= admin_passwd_file --config= config1 --vs= config1 --uri=/jsp-examples --file-on-server CATALINA_HOME /webapps/jsp-examples

Go to http:// hostname : portnumber /jsp-examples/ to verify that the Web application works.

Example of JNDI With JDBC Datasource

In Web Server 7.0, the jdbc-simple.war application resides in WS7_INSTALL_ROOT /samples/java/webapps/jdbc/simple/jdbc-simple.war. This section explains the Tomcat configuration for that Web application and describes the procedures for ensuring that the application works on Web Server 7.0.

 

web.xml


Here is how the web.xml file snippet reads.

<web-app xmlns="http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/j2ee/index.html"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.oracle.com/webfolder/technetwork/jsc/xml/ns/j2ee/index.html
    http://bit.ly/7KcNwH" version="2.4">
    <description>JDBC Simple App</description>
    <resource-ref>
        <description>Datasource example</description>
        <res-ref-name>jdbc/jdbc-simple</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>
</web-app>

 

Tomcat Configuration


Here is Tomcat's server.xml file snippet that contains the resource definition.

<Context attribute_list ... >
    <Resource name="jdbc/jdbc-simple" auth="Container"
        type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver"
        url="jdbc:oracle:thin:@127.0.0.1:1521:mysid"
        username="scott" password="tiger" maxActive="20" maxIdle="10"
        maxWait="-1"/>

</Context>

For the <resource-ref> tag in the web.xml file in the previous section, the Resource element in the server.xml file defines the actual Oracle user name, password, URL, and driverClassName attributes for the resource named jdbc/jdbc-simple. The other attributes, such as maxActive and so forth, are ignored in this article.

You must set up similar configurations for Web Server 7.0, as explained in the next section. This article does not detail the one-to-one mapping for each of the attributes of the server.xml elements. For details, see the Apache Tomcat 5.5 documentation.

 

Web Server 7.0-Specific Configuration


The Web application's sun-web.xml file and the Web Server 7.0 configuration apply.

sun-web.xml

Here is how the sun-web.xml file reads.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server
8.1 Servlet 2.4//EN"
"http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_4-1.dtd">
<sun-web-app>
    <resource-ref>
        <res-ref-name>jdbc/jdbc-simple</res-ref-name>
        <jndi-name>jdbc/jdbc-simple</jndi-name>
    </resource-ref>
</sun-web-app>

Normally, you place sun-web.xml under the Web application's WEB-INF directory. For this example, sun-web.xml has been added to jdbc-simple.war.

Web Server 7.0 Configuration

To configure the JDBC Datasource with JNDI in Web Server 7.0, do the following:

  1. Set up wadm (see the section, Setup for Administration Server CLI).
  2. Create the JDBC resource. Do the following:

    % cd WS7_INSTALL_ROOT /bin

    % ./wadm create-jdbc-resource --user= admin_user --password-file= admin_passwd_file --min-connections=2 --config= config1 --datasource-class=oracle.jdbc.pool.OracleDataSource jdbc/jdbc-simple
  3. Create the JDBC resource user properties: the user name, password, and URL. Type:

    % ./wadm create-jdbc-resource-userprop --user= admin_user --password-file= admin_passwd_file --config= config1 --jndi-name=jdbc/jdbc-simple url=jdbc:oracle:thin:@127.0.0.1:1521:mysid user=scott password=tiger
  4. Set class-path-suffix to the JAR or ZIP file that contains the datasource class. Type:

    % ./wadm set-jvm-prop --user= admin_user --password-file= admin_passwd_file --config= config1 class-path-suffix= path_to_Oracle_classes /classes12.zip

    Next time, to edit class-path-suffix, type:

    % ./wadm get-jvm-prop --user= admin_user --password-file= admin_passwd_file --config= config1 class-path-suffix

    The output shows you the existing class-path-suffix. You must suffix your new value to this existing value before setting class-path-suffix.
  5. Add the jdbc-simple Web application. Type:

    % ./wadm add-webapp --user= admin_user --password-file= admin_passwd_file --config= config1 --vs= config1 --uri=/jdbc-simple --file-on-server WS7_INSTALL_ROOT /samples/java/webapps/jdbc/simple/jdbc-simple.war
  6. Deploy the changes to config1. Type:

    % ./wadm deploy-config --user= admin_user --password-file= admin_passwd_file config1
  7. Stop and start the https- config1 instance. Type:

    % cd WS7_INSTALL_ROOT /https- config1 /bin

    % ./stopserv

    % ./startserv

Go to http:// hostname : portnumber /jdbc-simple/ to verify that it works.

SSL Configuration in Web Server 7.0

Unlike Tomcat, Web Server 7.0 supports SSL with Network Security Services (NSS) libraries. Two wadm commands, create-cert-request and install-cert, enable you to request a certificate from a Certificate Authority and install it on Web Server 7.0.

For development purpose, you can create a self-signed certificate in the Web Server 7.0 certificate database with the wadm command create-selfsigned-cert. Type, for example:

% ./wadm create-selfsigned-cert --user= admin_user --password-file= admin_passwd_file --token=internal --locality="Santa Clara" --state=CA --validity=12 --org="Sun Microsystems Inc." --country=US --key-type=rsa --key-size=1024 --config= config1 --server-name=Server --nickname=cert-Server

Be sure to modify the argument values for --locality, --state, --org, and --country, as appropriate. Also review the other options for this command line and revise them as appropriate.

You can then enable SSL for one of the existing HTTP listeners. Alternatively, you can create a new HTTP listener for which to enable SSL. Do the following:

  1. Create an HTTP listener. Type, for example:

    % ./wadm create-http-listener --user= admin_user --password-file= admin_passwd_file --listener-port=8095 --config= config1 --server-name=krishna2 --default-virtual-server-name= config1 http-listener-3

    Be sure that port 8095 is free before assigning it as the listener port.
  2. Enable SSL for http-listener-3 and set the server certificate, as identified by the nickname cert-Server. Type:

    % ./wadm set-ssl-prop --user= admin_user --password-file= admin_passwd_file --config= config1 --http-listener=http-listener-3 server-cert-nickname=cert-Server enabled=true
  3. Deploy the changes to config1. Type:

    % ./wadm deploy-config --user= admin_user --password-file= admin_passwd_file config1

Now test that SSL is working. If your default settings are on localhost, go to https://localhost:8095.

References
Rate and Review
Tell us what you think of the content of this page.
Excellent   Good   Fair   Poor  
Comments:
Your email address (no reply is possible without an address):
Sun Privacy Policy

Note: We are not able to respond to all submitted comments.
Left Curve
Java SDKs and Tools
Right Curve
Left Curve
Java Resources
Right Curve
JavaOne Banner
Java 8 banner (182)