Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Application Server Platform Edition 8 Migrating and Redeploying Server Applications Guide 

Chapter 3
Migrating from Sun ONE Application Server 6.x/7.x to Sun Java System Application Server Platform Edition 8

This chapter describes the considerations and strategies that are needed when moving J2EE applications from Sun ONE Application Server 6.x and Sun Java System Application Server 7 to the Sun Java System Application Server Platform Edition 8 product line.

The sections that follow describe issues that arise while migrating the main components of a typical J2EE application from Sun ONE Application Server 6.x/7.x to Sun Java System Application Server Platform Edition 8.

The migration issues described in this section are based on an actual migration that was performed for a J2EE application called iBank, a simulated online banking service, from Sun ONE Application Server 6.x to Sun Java System Application Server Platform Edition 8. This application reflects all aspects that comprise a traditional J2EE application.

The following sensitive points of the J2EE specification covered by the iBank application include:

The iBank application is presented in detail in Appendix A - iBank Application Specification

This section also describes specific migration tasks at the component level.

The following topics are addressed:

Migrating Deployment Descriptors

The following table summarizes the deployment descriptor migration mapping.

Source Deployment Descriptor

Target Deployment Descriptor

ejb-jar.xml - 1.1

ejb-jar.xml - 2.0

ias-ejb-jar.xml

sun-ejb-jar.xml

<bean-name>-ias-cmp.xml

sun-cmp-mappings.xml

web.xml

web.xml

ias-web.xml

sun-web.xml

application.xml

application.xml

The J2EE standard deployment descriptors ejb-jar.xml, web.xml and application.xml are not modified significantly. However, the ejb-jar.xml deployment descriptor is modified to make it compliant with EJB 2.0 specification in order to make the application deployable onSun Java System Application Server Platform Edition 8.

Majority of the information required for creating sun-ejb-jar.xml and sun-web.xml comes from ias-ejb-jar.xml and ias-web.xml respectively. However, there is some information that is required and extracted from the home interface (java file) of the CMP entity bean, in case the sun-ejb-jar.xml being migrated declares one. This is required to build the <query-filter> construct inside the sun-ejb-jar.xml, which requires information from inside the home interface of that CMP entity bean. If this source file is not present during the migration time, the <query-filter> construct will get created, but with lots of missing information (which will manifest itself in the form of "REPLACE ME" phrases in the migrated sun-ejb-jar.xml).

Additionally, if the ias-ejb-jar.xml contains a <message-driven> element, then information from inside this element is picked up and used to fill up information inside both ejb-jar.xml and sun-ejb-jar.xml. Also, inside the <message-driven> element of ias-ejb-jar.xml, there is an element <destination-name>, which holds the JNDI name of the topic or queue to which the MDB should listen to. In Sun ONE Application Server 6.5, the naming convention for this jndi name is "cn=<SOME_NAME>". Since a JMS Topic or Queue with this name is not deployable on Sun Java System Application Server Platform Edition 8, changes this to "<SOME_NAME>", and insert this information in the sun-ejb-jar.xml. This change must be reflected for all valid input files, namely, all .java, .jsp and .xml files. Hence, this change of JNDI name is affected globally across the application, and in case of non availability of some source files that contain reference to this jndi-name, you need to make the change manually in them so that the application becomes deployable.

Migrating J2EE Components

The following migration processes are described in this section:

Migrating JDBC Code

With the JDBC API, there are two methods of database access:

Establishing Connections Through the DriverManager Interface

Although this means of accessing a database is not recommended, as it is obsolete and is not very effective, there may be some applications that still use this approach.

In this case, the access code will be similar to the following:

public static final String driver = "oracle.jdbc.driver.OracleDriver";
public static final String url = "jdbc:oracle:thin:tmb_user/tmb_user@iben:1521:tmbank";
Class.forName(driver).newInstance();
Properties props = new Properties();
props.setProperty("user", "tmb_user");
props.setProperty("password", "tmb_user");
Connection conn = DriverManager.getConnection(url, props);

This code can be fully ported from Sun ONE Application Server 6.x to Sun Java System Application Server Platform Edition 8, as long as the Application Server is able to locate the classes needed to load the right JDBC driver. In order to make the required classes accessible to the application deployed in the Application Server, you should place the archive (JAR or ZIP) for the driver implementation in the /lib directory of the Application Server installation directory.

Modify the CLASSPATH by setting the path for the driver through the Admin Console GUI. Click the server instance “server1” and then click the tab “JVM Settings” from the right pane. Now click the option Path Settings and add the path in the classpath suffix text entry box. Once you make the changes, click “Save” and then apply the new settings. Restart the server to modify the configuration file, server.xml.

Using JDBC 2.0 Data Sources

Using JDBC 2.0 data sources to access a database provides performance advantages such as transparent connection pooling, enhances productivity by simplifying code and implementation, and provides code portability.

Using a data source in an application requires an initial configuration phase followed by a registration of the data source in the JNDI naming context of the application server. Once the data source is registered, the application will easily be able to obtain a connection to the database by retrieving the corresponding DataSource object from the JNDI context. The actions are described in the following topics:

Configuring a Data Source

In Sun ONE Application Server 6.0 data sources and their corresponding JDBC drivers are configured from the server's graphic administration console. Connection pools are managed automatically by the application server, and the administration tool can be used to configure their properties. With integrated type 2 JDBC drivers, the connection pooling properties are defined on a per-driver basis, and common to all data sources using a given driver.

On the other hand, for third-party JDBC drivers, connection pool properties are defined on a per-data source basis. Third-party JDBC drivers can be configured either from the administration tool, or from a separate utility (db_setup.sh in Sun Solaris, and jdbcsetup in Windows NT/2000). Moreover, the command line utility iasdeploy can be used to configure a data source from an XML file describing its properties. These utilities are all located in the /bin/ sub-directory of the Application Server installation root directory.

In Application Server, data sources can be configured from the server's graphic administration console or through the command line utility asadmin. The command line utility asadmin can be invoked by executing the asadmin script in Solaris, available in Application Server installation’s bin directory. At the asadmin prompt, use the following commands to create connection pool and JNDI resource.

The syntax for calling the asadmin utility to create a connection pool is as follows:

asadmin>create-jdbc-connection-pool -u username -w password -H hostname -p adminport [-s] --datasourceclassname classname [--steadypoolsize=8] [--maxpoolsize=32] [--maxwait=60000] [--poolresize=2] [--idletimeout=300] [--isconnectvalidatereq=false] [--validationmethod=auto-commit] [--validationtable tablename] [--failconnection=false] [--description text] [--property (name=value)[:name=value]*] connectionpoolid

For example:

asadmin>create-jdbc-connection-pool -u admin -w password -H cl1 -p 4848 --datasourceclassname oracle.jdbc.pool.OracleConnectionPoolDataSource --property (user-name=ibank_user):(password=ibank_user) oraclepool

Here JDBC connection pool ‘oraclepool’ for oracle database is created using database schema having the username ‘ibank_user’ and password ‘ibank_user’.

The syntax to create a JDBC resource is as follows:

asadmin>create-jdbc-resource -u username -w password -H hostname -p adminport [-s] --connectionpoolid id [--enabled=true] [--description text] [--property (name=value)[:name=value]*] jndiname

For example:

asadmin>create-jdbc-resource -u admin -w password -H cl1 -p 4848 --connectionpoolid oraclepool jdbc/IBANK

Here a JDBC resourcewith the JNDI name jdbc/IBANK is created for the connection pool created above.

Here is the procedure to follow when registering a data source in Application Server through graphical interface.

  1. Register the data source classname
    1. Place the archive (JAR or ZIP) for the data source class implementation in the /lib directory of the Application Server installation directory.
    2. Modify the CLASSPATH by setting the path for the driver through the Admin Console GUI. Click at the server instance “server1” and then click at tab “JVM Settings”, now click at path settings and add the path at the classpath suffix column. Once you make the changes save it and then apply these new settings. Restart the server, which would modify the configuration file, server.xml.
  2. Register the data source

In Application Server, data sources and their corresponding JDBC drivers are configured from the server's graphic administration interface.

The left pane is a tree view of all items you can configure in the Application Server. Click on the item Connection pool at the left pane, the right pane would display the page associated with it where the relevant entries can be made.

Similarly now click at the item Data source, right pane would show the entries required for data source setup.

The Application Server-specific deployment descriptor sun-web.xml has to be modified accordingly.

For example if a new data source is configured for the iBank application, the sun-web.xml file would contain the following entries.

<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN' 'Http://localhost:8000/sun-web-app_2_3.dtd'>
<sun-web-app>
<resource-ref>
<res-ref-name>jdbc/iBank</res-ref-name>
<jndi-name>jdbc/iBank</jndi-name>
<default-resource-principal>
<name>ibank_user</name>
<password>ibank_user</password>
</default-resource-principal>
</resource-ref>
</sun-web-app>

Looking Up the Data Source Via JNDI To Obtain a Connection

To obtain a connection from a data source, the process is as follows:

  1. Obtain the initial JNDI context.

    2. To guarantee portability between different environments, the code used to retrieve an InitialContext object (in a servlet, in a JSP page, or an EJB), should be simply, as follows:

    InitialContext ctx = new InitialContext();

  2. Use a JNDI lookup to obtain a data source reference.

    3. To obtain a reference to a data source bound to the JNDI context, look up the data source's JNDI name from the initial context object. The object retrieved in this way should then be cast as a DataSource type object:

    ds = (DataSource)ctx.lookup(JndiDataSourceName);

  3. Use the data source reference to obtain the connection.

    4. This operation is very simple, and requires the following line of code:

    conn = ds.getConnection();

Sun ONE Application Server 6.x and Application Server both follow the above technique for obtaining a connection form data source. So to summarize migration does not require any modification to be made to the code.

Migrating Java Server Pages and JSP Custom Tag Libraries

Sun ONE Application Server 6.x complies with the JSP 1.1 specification and Application Server complies with the JSP 2.0 specification.

JSP 2.0 specification contains many new features as well as corrections and clarifications of areas that were not quite right in JSP 1.1 specification.

These changes are basically enhancements and are not required to be made, while migrating JSP pages from JSP 1.1 to 2.0.

The implementation of JSP custom tag libraries in Sun ONE Application Server 6.x complies with the J2EE specification. Consequently, migration of JSP custom tag libraries to the Sun Java System Application Server Platform Edition 8 does not pose any particular problem, nor require any modifications to be made.

Migrating Servlets

Sun ONE Application Server 6.x supports the Servlet 2.2 API. Sun Java System Application Server Platform Edition 8 supports the Servlet 2.4 API.

Servlet API 2.4 actually leaves the core of servlets relatively untouched; most changes are concerned with adding new features outside the core.

The most significant features are:

These changes are basically enhancements and are not required to be made while migrating servlets from Servlet API 2.2 to 2.4.

However, if the servlets in the application use JNDI to access resources of the J2EE application (such as data sources, EJBs, and so forth), some modifications may be needed in the source files or in the deployment descriptor.

These modifications are explained in detail in the following sections:

One last scenario may mean modifications are required in the servlet code, naming conflicts may occur with Sun ONE Application Server if a JSP page has the same name as an existing Java class. In this case, the conflict should be resolved by modifying the name of the JSP page in question, which may then mean editing the code of the servlets that call this JSP page. This issue is resolved in Application Server as it uses new class loader hierarchy as compared to Sun ONE Application Server 6.x. In this new scheme, for a given application, one class loader loads all EJB modules and another class loader loads web module. As these two loaders do not talk with each other, there would be no naming conflict.

Obtaining a Data Source from the JNDI Context

To obtain a reference to a data source bound to the JNDI context, look up the data source's JNDI name from the initial context object. The object retrieved in this way should then be cast as a DataSource type object:

ds = (DataSource)ctx.lookup(JndiDataSourceName);

For detailed information, refer to section “Migrating JDBC Code” in the previous pages.

Declaring EJBs in the JNDI Context

Please refer to section Declaring EJBs in the JNDI Context from "Migrating from EJB 1.1 to EJB 2.0".”

EJB Migration

As mentioned in Understanding Migration, while Sun ONE Application Server 6.x supports the EJB 1.1 specification, Application Server also supports the EJB 2.0 specification. The EJB 2.0 specification introduces the following new features and functions to the architecture:

Although the EJB 1.1 specification will continue to be supported in the Application Server, the use of the EJB 2.0 architecture is recommended to leverage its enhanced capabilities.

For detailed information on migrating from EJB 1.1 to EJB 2.0, please refer to Chapter 2, "Migrating from EJB 1.1 to EJB 2.0."

EJB Changes Specific to Sun Java System Application Server Platform Edition 8

Migrating EJBs from Sun ONE Application Server 6.x to the Application Server is done without making any changes to the EJB code. However, the following DTD changes are required.

Session Beans

Entity Beans

Message Driven Beans

Application Server provides seamless Message Driven Support through the tight integration of Sun Java System Message Queue with the Application Server, providing a native, built-in JMS Service.

This installation provides Application Server with a JMS messaging system that supports any number of Application Server instances. Each server instance, by default, has an associated built-in JMS Service that supports all JMS clients running in the instance.

Both container-managed and bean-managed transactions as defined in the Enterprise JavaBeans Specification, v2.0 are supported.

Message Driven Bean support in iPlanet Application Server was restricted to developers, and used many of the older proprietary APIs. Messaging services were provided by iPlanet Message Queue for Java 2.0. An LDAP directory was also required under iPlanet Application Server to configure the Queue Connection Factory object.

The QueueConnectionFactory, and other particulars required to configure Message Driven Beans in Application Server should be specified in the ejb-jar.xml file.

For more information on the changes to deployment descriptors, see "Migrating Deployment Descriptors." For information on Message Driven Bean implementation in Sun Java System Application Server Platform Edition 8, see Sun Java System Application Server Platform Edition 8, Developer’s Guide to Enterprise Java Bean Technology.

Migrating Web Applications

Sun ONE Application Server 6.x support servlets (Servlet API 2.2), and JSPs (JSP 1.1). Sun Java System Application Server Platform Edition 8 supports Servlet API 2.4 and JSP 2.0.

Within these environments it is essential to group the different components of an application (servlets, JSP and HTML pages and other resources) together within an archive file (J2EE-standard Web application module) before you can deploy it on the application server.

According to the J2EE specification, a Web application is an archive file (WAR file) with the following structure:

Migrating Web Application Modules

Migrating applications from Sun ONE Application Server 6.x to Sun Java System Application Server Platform Edition 8 does not require any changes in the Java/JSP code. The following changes are, however, still required.

Once the web.xml and ias-web.xml files are migrated in the above-mentioned fashion, the Web application (WAR file) can be deployed from the Application Server’s deploytool GUI interfaceor from the command line utility asadmin, where the deployment command should mention the type of application as web.

Invoke the asadmin command line utility by running asadmin.bat file or the asadmin.sh script in the Application Server’s bin directory.

The command at the asadmin prompt would be:

asadmin> deploy -u username -w password -H hostname -p adminport --type web [--contextroot contextroot] [--force=true] [--name component-name] [--upload=true] filepath

Potential Servlets and JSP Migration Problems

The actual migration of the components of a Servlet / JSP application from Sun ONE Application Server 6.x to Application Server will not require any modifications to be made to the component code.

If the Web application is using a server resource, a DataSource for example, then the Application Server requires that this resource to be declared inside the web.xml file and, correspondingly, inside the sun-web.xml file. To declare a DataSource called jdbc/iBank, the <resource-ref> tag in the web.xml file would be as follows:

<resource-ref>
<res-ref-name>jdbc/iBank</res-ref-name>
<res-type>javax.sql.XADataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

Corresponding declaration inside the sun-web.xml file will look like this:

<?xml version="1.0" encoding="UTF-8"?>
<! DOCTYPE FIX ME: need confirmation on the DTD to be used for this file

<sun-web-app>
<resource-ref>
<res-ref-name>jdbc/iBank</res-ref-name>
<jndi-name>jdbc/iBank</jndi-name>
</resource-ref>
</sun-web-app>

Migrating Enterprise EJB Modules

Sun ONE Application Server 6.x supports EJB 1.1; the Application Server supports EJB 2.0. Thereby, both can support:

EJB 2.0, however, introduces a new type of enterprise bean, called a message-driven bean(MDB) in addition to the session and entity beans.

J2EE 1.4 specification dictates that the different components of an EJB must be grouped together in a JAR file with the following structure:

Sun ONE application servers observe this archive structure. However, the EJB 1.1 specification leaves each EJB container vendor to implement certain aspects as they see fit:

As we might expect, Sun ONE Application Server 6.x andApplication Server diverge on certain points, which means that when migrating an application certain aspects require particular attention. Some XML files have to be modified:

Migrating Enterprise Applications

According to the J2EE specifications, an enterprise application is an EAR file, which must have the following structure:

In the application deployment descriptor, we define the modules that make up the enterprise application, and the Web application's context root.

Sun ONE Application server 6.x and the Application Server support the J2EE model wherein applications are packaged in the form of an enterprise archive (EAR) file (extension .ear). The application is further subdivided into a collection of J2EE modules, packaged into Java archives (JAR files, which have a .jar file extension) for EJBs and Web archives (WAR files,which have a .war file extension) for servlets and JSPs.

It is essential to follow the steps listed here before deploying an enterprise application:

  1. Package EJBs in one or more EJB modules.
  2. Package the components of the Web application in a Web module.
  3. Assemble the EJB modules and Web modules in an enterprise application module.
  4. Define the name of the enterprise application's root context, which will determine the URL for accessing the application.

The Application Server uses a newer class loader hierarchy than Sun ONE Application Server 6.x does. In the new scheme, for a given application, one class loader loads all EJB modules and another class loader loads Web modules. These two are related in a parent child hierarchy where the JAR module class loader is the parent module of the WAR module class loader. All classes loaded by the JAR class loader are available/accessible to the WAR module but the reverse is not true. If a certain class is required by the JAR file as well as the WAR file, then the class file should be packaged inside the JAR module only. If this guideline is not followed it could lead to class conflicts.

Application Root Context and Access URL

There is one particular difference between Sun ONE Application Server 6.x and the Application Server, concerning the applications access URL (root context of the application's Web module. If AppName is the name of the root context of an application deployed on a server called hostname, the access URL for this application will differ depending on the application server used:

The TCP port used as default by Application Server is port 8080.

Although the difference in access URLs between Sun ONE Application Server 6.x and the Application Server may appear minor, it can be problematic when migrating applications that make use of absolute URL references. In such cases, it will be necessary to edit the code to update any absolute URL references so that they are no longer prefixed with the specific marker used by the Web Server plug-in for Sun ONE Application Server 6.x.

Migrating Proprietary Extensions

A number of classes proprietary to the Sun ONE Application Server 6.x environment may have been used in applications. Some of the proprietary Sun ONE packages used by Sun ONE Application Server 6.x are listed below:

These APIs are not supported in the Application Server. Applications using any classes belonging to the above package will have to be rewritten to use standard J2EE APIs. Applications using custom JSP tags and UIF framework also needs to be rewritten to use standard J2EE APIs.

For a sample migration walkthrough using the iBank application, see Migrating a Sample Application - an Overview.

Migrating UIF

The Application Server does not support the use of Unified Integration Framework (UIF) API for applications. Instead, it supports the use of J2EE Connector Architecture (JCA) for integrating the applications. However, the applications developed in Sun ONE Application Server 6.5 use the UIF. In order to deploy such applications to the Application Server, you need to migrate the UIF to J2EE Connector Architecture. This section discusses the prerequisites and steps to migrate the applications using UIF to Application Server.

Before migrating the applications, you need to make sure that the UIF is installed on Sun ONE Application Server 6.5. To check for the installation, you can follow any of the following two approaches:

Approach 1: Checking in the registry files

UIF is installed as a set of application server extensions. They are registered in the application server registry during the installation. Search for the following strings in the registry to check whether UIF is installed.

Extension Name Set:

The registry file on Solaris Operating Environment can be found at the following location:

AS_HOME/AS/registry/reg.dat

Approach 2: Checking for UIF binaries in installation directories

UIF installers copy specific binary files in to the application server installation. A successful find of these files below indicate that UIF is installed.

The location of the following files on Solaris and Windows is:

AS_HOME/AS/APPS/bin

List of files to be searched on Solaris:

List of files to be searched on Windows:

Before migrating the UIF to Application Server, make sure that the UIF API is being used in applications. To verify its usage:

Contact appserver-migration@sun.com for information about UIF migration to the Application Server.

Migrating Rich Clients

This section describes the steps for migrating RMI/IIOP and ACC clients developed in Planet Application Server 6.x to the Application Server.

Authenticating a Client in Sun One Application Server 6.x

iPlanet Application Server provides a client-side callback mechanism that enables applications to collect authentication data from the user such as the username and the password.The authentication data collected by the iPlanet CORBA infrastructure is propagated to the Application Server via IIOP.

If ORBIX 2000 is the ORB used for RMI/IIOP, portable interceptors implement security by providing hooks, or interception points, which define stages within the request and reply sequence.

Authenticating a Client in Sun Java System Application Server Platform Edition 8

The authentication is done based on JAAS (Java Authorization and Authentication System API) and the client can that implement a CallBackHandler. If a client does not provide a CallbackHandler, then the default CallbackHandler, called the LoginModule, will be used by the ACC for obtaining the authentication data.

For detailed instructions on using JAAS for authentication, see the Sun Java System Application Server Platform Edition 8 Developer’s Guide to Clients.

Using ACC in Sun ONE Application Server 6.x and Sun Java System Application Server Platform Edition 8

In Sun ONE Application Server 6.x, no separate appclient script is provided. You are required to place the iasacc.jar file in the classpath instead of the iascleint.jar file. The only benefit of using the ACC for packaging application clients in 6.x is that the JNDI names specified in the client application are indirectly mapped to the absolute JNDI names of the EJBs.

In case of Sun ONE Application Server 6.x applications, a stand-alone client would use the absolute name of the EJB in the JNDI lookup. That is, outside an ACC, the following approach would be used to lookup the JNDI:

initial.lookup(“ejb/ejb-name”);
initial.lookup(“ejb/module-name/ejb-name”);

If your application was developed using Sun ONE Application Server 6.5 SP3, you would have used the prefix “java:comp/env/ejb/” when performing lookups via absolute references.

initial.lookup(“java:comp/env/ejb/ejb-name”);

In Sun Java System Application Server Platform Edition 8, the JNDI lookup is done on the jndi-name of the EJB. The absolute name of the ejb must not be used. Also, the prefix, java:comp/env/ejb is not supported in Sun Java System Application Server Platform Edition 8. Replace the iasclient.jar, iasacc.jar, or javax.jar JAR files in the classpath with appserv-ext.jar.

If your application provides load balancing capabilities, in Sun Java System Application Server Platform Edition 8, load balancing capabilities are supported only in the form of S1ASCTXFactory as the context factory on the client side and then specifying the alternate hosts and ports in the cluster by setting the com.sun.appserv.iiop.loadbalancingpolicy system property as follows:

com.sun.appserv.iiop.loadbalancingpolicy=roundrobin,host1:port1,host2:port2,...,

This property provides you with a list of host:port combinations to round robin the ORBs. These host names may also map to multiple IP addresses. If you use this property along with org.omg.CORBA.ORBInitialHost and org.omg.CORBA.ORBInitialPort as system properties, the round robin algorithm will round robin across all the values provided. If, however, you provide a host name and port number in your code, in the environment object, that value will override any such system property settings.

The Provider URL to which the client is connected in Sun ONE Application Server 6.5 is the IIOP host and port of the CORBA Executive Engine (CXS Engine). In case of Sun Java System Application Server Platform Edition 8, the client needs to specify the IIOP listener Host and Port number of the instance. No separate CXS engine exists in Sun Java System Application Server Platform Edition 8.

The default IIOP port is 3700 in Sun Java System Application Server Platform Edition 8; the actual value of the IIOP Port can be found in the server.xml configuration file.



Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.