Skip to ContentSun and Oracle Channel Sun How to Buy Log In

Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Upgrade and Migration Guide

Contidos dentro

Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Update 2 - Standalone Installer
Sun Java System Application Server Enterprise Edition 8.1 2005Q2

Localizar Mais Documentação

Destaques de Recursos de Suporte

Fazer download desta apostila em PDF (952 KB)

Chapter 6 Migrating from Application Server 6.x/7.x to Application Server 8.1

This chapter describes the considerations and strategies that are needed when moving J2EE applications from Application Server 6.x and Application Server 7 to the Application Server Platform Edition 8.1product line. However, Application Server 8.1 provides backward compatibility standard, with Application Server 7 as the baseline. That is, applications developed in Application Server 7 can be deployable directly to Application Server 8.1 with minimum or no changes.

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

This chapter contains the following sections:

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

The following areas of the J2EE specification are covered by the iBank application:

Servlets, especially with redirection to JSP pages (model-view-controller architecture)
JSP pages, especially with static and dynamic inclusion of pages
JSP custom tag libraries
Creation and management of HTTP sessions
Database access through the JDBC API
Enterprise JavaBeans: Stateful and Stateless session beans, CMP and BMP entity beans.
Assembly and deployment in line with the standard packaging methods of the J2EE application

The iBank application is described in detail in Chapter 9, iBank Application Specification.

Migrating Deployment Descriptors

There are two types of deployment descriptors, namely, Standard Deployment Descriptors and Runtime Deployment Descriptors. Standard deployment descriptors are portable across J2EE platform versions and vendors and does not require any modifications. Currently, there are exceptions due to standards interpretation. The following table lists such deployment descriptors.

Source Deployment Descriptor	Target Deployment Descriptor
`ejb-jar.xml` - 1.1	`ejb-jar.xml` - 2.0
`web.xml`	`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 on Sun Java System Application Server 8.1.

Runtime deployment descriptors are vendor and product specific and are not portable across application servers due to difference in their format. Hence, deployment descriptors require migration. This section describes how you can manually create the runtime deployment descriptors and migrate relevant information.

The following table summarizes the deployment descriptor migration mapping.

Source Deployment Descriptor	Target Deployment Descriptor
`ias-ejb-jar.xml`	`sun-ejb-jar.xml`
`<bean-name>-ias-cmp.xml`	`sun-cmp-mappings.xml`
`ias-web.xml`	`sun-web.xml`

The standard deployment descriptors of Application Server 6.x needs modification when moving to Application Server 8.1 because of non-conformance with the DTDs.

A 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 the source file is not present during the migration time, the <query-filter> construct is created, but with missing information (which manifests 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 listens. In 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 Application Server, the application server changes this to <SOME_NAME>, and inserts 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 JNDI name change is propagated across the application, and if some source files that contain reference to this jndi-name are unavailable, the administrator must make the changes manually so that the application becomes deployable.

Migrating Web Applications

Application Server 6.x support servlets (Servlet API 2.2), and JSPs (JSP 1.1). Sun Java System Application Server 8.1 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) deploying it on the application server.

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

A root directory containing the HTML pages, JSP, images and other static resources of the application.
A META-INF/ directory containing the archive manifest file MANIFEST.MF containing the version information for the SDK used and, optionally, a list of the files contained in the archive.
A WEB-INF/ directory containing the application deployment descriptor (web.xml file) and all the Java classes and libraries used by the application, organized as follows:
- A classes/ sub-directory containing the tree-structure of the compiled classes of the application (servlets, auxiliary classes), organized into packages
  - A lib/ directory containing any Java libraries (JAR files) used by the application

Migrating Java Server Pages and JSP Custom Tag Libraries

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

JSP 2.0 specification contains many new features, as well as updates to the JSP 1.1 specification.

These changes are enhancements and are not required to migrate to JSP pages from JSP 1.1 to 2.0.

The implementation of JSP custom tag libraries in Application Server 6.x complies with the J2EE specification. Consequently, migrating JSP custom tag libraries to the Application Server Platform Edition 8.1does not pose any particular problem, nor require any modifications.

Migrating Servlets

Application Server 6.x supports the Servlet 2.2 API. Sun Java System Application Server 8.1 supports the Servlet 2.4 API.

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

The most significant features are:

Servlets now require JDK 1.2 or later
Filter mechanisms have been created
Application lifecycle events have been added
Internationalization support has been added
Error and security attributes have been expanded
HttpUtils class has been deprecated
Several DTD behaviors have been expanded and clarified

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

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

These modifications are explained in detail in the following sections:

One last scenario might require modifications to the servlet code. Naming conflicts can occur with Application Server 6.x if a JSP page has the same name as an existing Java class. In this case, the conflict must be resolved by modifying the name of the JSP page in question. This in turn can mean editing the code of the servlets that call this JSP page. This issue is resolved in Application Server as it uses a new class loader hierarchy. In the new version of the application server, 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 is 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 is then be cast as a DataSource type object:

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

For detailed information, refer to section “Migrating JDBC Code.”

Declaring EJBs in the JNDI Context

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

Potential Servlets and JSP Migration Problems

The actual migration of the components of a Servlet / JSP application from Application Server 6.x to Application Server 8.1does not require any modifications to the component code.

If the Web application is using a server resource, a DataSource for example, 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 is 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>

The corresponding declaration inside the sun-web.xml file looks 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 Web Application Modules

Migrating applications from Application Server 6.x to Sun Java System Application Server 8.1 does not require any changes to the Java code or Java Server Pages. However, you must change the following files:

web.xml
ias-web.xml

The Application Server adheres to J2EE 1.4 standards, according to which, the web.xml file inside a WAR file must comply with the revised DTD at http://java.sun.com/dtd/web-app_2_3.dtd. This DTD is a superset of the previous versions’ DTD, hence only the <! DOCTYPE definition needs to be changed inside the web.xml file, which is to be migrated. The modified <! DOCTYPE declaration looks like:

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
"http://java.sun.com/dtd/web-app_2_3.dtd">

In Application Server Platform Edition 8.1, the name of this file is changed to sun-web.xml.

This XML file must declare the Application Server-specific properties and resources that are required by the Web application.

See Potential Servlets and JSP Migration Problems for information about important inclusions to this file.

If the ias-web.xml of the Application Server 6.5 application is present and does declare Application Server 6.5 specific properties, then this file needs to be migrated to Application Server standards. The DTD file name has to be changed to sun-web.xml. For more details, see URL http://wwws.sun.com/software/dtd/appserver/sun-web-app_2_4-1.dtd

Once you have made these changes to the web.xml and ias-web.xml files, the Web application (WAR file) can be deployed from the Application Server’s deploytool GUI interface or from the command line utility asadmin. The deployment command must specific 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 is:

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

Migrating Enterprise EJB Modules

Application Server 6.x supports EJB 1.1, and the Application Server supports EJB 2.0. Therefore, both can support:

Stateful or stateless session beans
Entity beans with bean-managed persistence (BMP), or container-managed persistence (CMP)

EJB 2.0, however, introduces a new type of enterprise bean, called a message-driven bean (MDB).

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

META-INF/ directory with an XML deployment descriptor named ejb-jar.xml
The .class files corresponding to the home interface, remote interface, the implementation class, and the auxiliary classes of the bean with their package

Application Server 6.x use this archive structure. However, the EJB 1.1 specification leaves each EJB container vendor to implement certain aspects as they see fit:

Database persistence of CMP EJBs (particularly the configuration of mapping between the bean’s CMP fields and columns in a database table).
Implementation of the custom finder method logic for CMP beans.
Application Server 6.x andApplication Server 8.1do not handle migrations in the same way, which means that some XML files must be modified:
The <!DOCTYPE definition must be modified to point to the latest DTD url (in the case of J2EE standard DDs, like ejb-jar.xml).
Replace the ias-ejb-jar.xml file with the modified version of this file (for example, file sun-ejb-jar.xml, which is created manually according to the DTDs). For more information, see http://wwws.sun.com/software/dtd/appserver/sun-ejb-jar_2_1-1.dtd
Replace all the <ejb-name>-ias-cmp.xml files with one sun-cmp-mappings.xml file, which is created manually. For more information, see http://wwws.sun.com/software/dtd/appserver/sun-cmp-mapping_1_2.dtd
Optionally, for CMP entity beans, use the capture-schema utility in the Application Server’s bin directory to generate the dbschema. Then place it above the META-INF directory for the entity beans.

EJB Migration

As mentioned in Chapter 4, Understanding Migration, while 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:

Message Driven Beans (MDBs)
Improvements in Container-Managed Persistence (CMP)
Container-managed relationships for entity beans with CMP
Local interfaces
EJB Query Language (EJB QL)

Although the EJB 1.1 specification continues 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 5, Migrating from EJB 1.1 to EJB 2.0

EJB Changes Specific to Application Server Platform Edition 8.1

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

Session Beans

The <!DOCTYPE> definition must be modified to point to the latest DTDs with J2EE standard DDs, such as ejb-jar.xml.
Replace ias-ejb-jar.xml file with the modified version of this file, named sun-ejb-jar.xml,created manually according to the DDs. For more details, see hhttp://ttp://wwws.sun.com/software/dtd/appserver/sun-ejb-jar_2_1-1.dtd
In the sun-ejb-jar.xml file, the JNDI name for all the EJBs must be added before ”ejb/’ in all the JNDI names. This is required because, in Application Server 6.5, the JNDI name of the EJB can only be ejb/<ejb-name> where <ejb-name> is the name of the EJB as declared inside the ejb-jar.xml file.

In the Application Server, a new tag has been introduced in the sun-ejb-jar.xml. This is where the JNDI name of the EJB is declared.

Note –

To avoid changing JNDI names throughout the application, declare the JNDI name of the EJB as ejb/<ejb-name> inside the <jndi-name> tag.

Migrating EJB Applications that Support SFSB Failover (Enterprise Edition)

Sun ONE Application Server 6.5 supports failover of stateful session beans. To take advantage of the SFSB failover in 6.5, the session bean need to be configured with failover and DSync. The DSync (Distributed Store) mechanism is used to save the session beans’s conversational state during runtime.

Note –

Sun ONE Application Server 6.5 does not support failover of stateful session beans for rich clients on the RMI/IIOP path. Such applications can take advantage of SFSB failover on the RMI/IIOP path in Sun Java System Application Server 8.1. For more information on SFSB failover configuration, see Stateful Session Bean Failover in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

Sun Java System Application Server 8.1, Enterprise Edition supports failover of stateful session beans. Application Server 8.1 uses the High Availability Database (HADB) for storing session data. The principle followed in supporting SFSB failover in saving the conversational state of an SFSB at predefined points in its lifecycle to a persistent store. This mechanism is referred to as checkpointing. In case of a server crash, the checkpointed state of an SFSB can be retrieved from the persistent store. In order to use HADB for storing session data, you must configure HADB as the persistent store. The underlying store for the HTTP sessions and stateful session beans is same and the configuration of persistent store is exactly similar to configuration of session store.

For information on configuring HADB for session failover, see Chapter 8, Configuring High Availability Session Persistence and Failover, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

Migration of stateful session beans deployed in Sun ONE Application Server 6.5 to Sun Java System Application Server 8.1 does not require any changes in the EJB code. However, the following steps must be performed:

Modify the <!DOCTYPE definition to point to the latest DTD url in case of J2EE standard DDs, like ejb-jar.xml.
Replace ias-ejb-jar.xml with the modified version of this file, i.e., sun-ejb-jar.xml, which is created manually according to the DTDs.
Replace all the <ejb-name>-ias-cmp.xml files with one sun-cmp-mappings.xml file, which is created manually.
No changes are required in the application source code for taking advantage of the SFSB state failover support. All configuration needed for checkpointing SFSBs will be applied at the Application Server specific deployment descriptor (sun-ejb-jar.xml), or in the domain configuration file (domain.xml).

However, if you are accessing theEJBs through servlets then you need to store the EJB home and remote references in the session. The following is the code example to store ejbHome and ejbRemote interfaces in the session:
```
session.setAttribute("ejbhome", ejbHome);
session.setAttribute("ejbremote", ejbRemote);
```
The following code example demonstrates how to retrieve the ejbHome and ejbRemote from the session:
```
ejbHome = session.getAttribute("ejbhome");
ejbRemote = session.getAttribute("ejbremote");
```
In the domain.xml, make sure that the availability-enabled attribute of availability-service element is set to TRUE. If availability-enabled attribute is set to TRUE indicates that failover is enabled at the server instance level. That is, if a server instance fails to process a request, the request is routed to the next available server instance.

SFSB checkpointing adds performance overhead on the EJB container, you may want to restrict checkpointing to a list of SFSBs whose state failover is critical to the application.

You can enable/disable the checkpointing at the method level in sun-ejb-jar.xml. For more details seeSpecifying Methods to Be Checkpointed in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

If, in the deployment descriptor for the SFSB ejb module in 6.5 (ias-ejb-jar.xml), the failoverrequired attribute of the session element is set to TRUE, you might want to enable availability-service for such ejb modules in the Application Server 8.1 environment.

Entity Beans

The <!DOCTYPE> definition must be modified to point to the latest DTDs containing J2EE standard DDs, such as ejb-jar.xml.
Update the <cmp-version> tag with the value 1.1, for all CMPs in the ejb-jar.xml file.
Replace all the <ejb-name>-ias-cmp.xml files with the manually created sun-cmp-mappings.xml file. For more information, see http://wwws.sun.com/software/dtd/appserver/sun-cmp-mapping_1_2.dtd
Generate dbschema by using the capture-schema utility in the Application Server installation’s bin directory and place it above META-INF folder for Entity beans.
Replace the ias-ejb-jar.xml with the sun-ejb.jar.xml in Application Server.
In Application Server 6.5, the finder's SQL was directly embedded into the <ejb-name>-ias-cmp.xml. In Application Server, mathematical expressions are used to declare the <query-filter> for the various finder methods.

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 elements required to configure Message Driven Beans in Application Server are now 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 Beans see Using Message-Driven Beans in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer’s Guide.

Migrating Enterprise Applications

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

A META-INF/ directory containing the XML deployment descriptor of the J2EE application called application.xml
The JAR and WAR archive files for the EJB modules and Web module of the enterprise application, respectively

In the application deployment descriptor, the modules that make up the enterprise application and the Web application’s context root are defined.

Application server 6.x and the Application Server 8.1support 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) and 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:

To Build an EAR File

Package EJBs in one or more EJB modules.

Package the components of the Web application in a Web module.

Assemble the EJB modules and Web modules in an enterprise application module.

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 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 must be packaged inside the JAR module only. If this guideline is not followed it can lead to class conflicts.

Application Root Context and Access URL

There is a major ”difference between 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:

With Application Server 6.x, which is always used jointly with a Web front-end, the access URL for the application takes the following form (assuming the Web server is configured on the standard HTTP port, 80):
```
http://<hostname>/NASApp/AppName/
```
With the Application Server, the URL takes the form:
```
http://<hostname>:<portnumber>/AppName/
```

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

Although the difference in access URLs between Application Server 6.x and the Application Server might appear minor, it can be problematic when migrating applications that make use of absolute URL references. In such cases, it is 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 Application Server 6.x.

Applications With Form-based Authentication

Applications developed on Application Server 6.5 that use form-based authentication can pass the request parameters to the Authentication Form or the Login page. The Login page could be customized to display the authentication parameters based on the input parameters.

For example:

http://gatekeeper.uk.sun.com:8690/NASApp/test/secured/page.jsp?arg1=test&arg2=m

Application Server 8.1 does not support the passing of request parameters while displaying the Login page. The applications that uses form-based authentication, which passes the request parameters can not be migrated to Application Server 8.1. Porting such applications to Application Server 8.1 requires significant changes in the code. Instead, you can store the request parameter information in the session, which can be retrieved while displaying the Login page.

The following code example demonstrates the workaround:

Before changing the code in 6.5:

---------index-65.jsp -----------
<%@page contentType="text/html"%>
<html>
<head><title>JSP Page</title></head>
<body>
go to the <a href="secured/page.htm">secured a rea</a>
</body>
</html>
----------login-65.jsp--------------
<%@page contentType="text/html"%>
<html>
<head> </head>
<body>
<!-- Print login form -->
<h3>Parameters</h3><br>
out.println("arg1 is " + request.getParameter("arg1"));
out.println("arg2 is " + request.getParameter("arg2"));
</body>
</html>

After changing the code in Application Server 8.1:

---------index-81.jsp -----------
<%@page contentType="text/html"%>
<html>
<head><title>JSP Page</title></head>
<body>
<%session.setAttribute("arg1","test"); %>
<%session.setAttribute("arg2","me"); %>
go to the <a href="secured/page.htm">secured area</a>
</body>
</html>

The index-81.jsp shows how you can store the request parameters in a session.

----------login-81.jsp--------------
<%@page contentType="text/html"%>
<html>
<head> </head>
<body>
<!-- Print login form -->
<h3>Parameters</h3><br>
<!--retrieving the parameters from the session -->
out.println("arg1 is"+(String)session.getAttribute("arg1"));
out.println("arg2 is” + (String)session.getAttribute("arg2"));
</body>
</html>

Migrating Proprietary Extensions

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

com.iplanet.server.servlet.extension
com.kivasoft.dlm
com.iplanetiplanet.server.jdbc
com.kivasoft.util
com.netscape.server.servlet.extension
com.kivasoft
com.netscape.server

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

For a sample migration walkthrough using the iBank application, see Chapter 7, 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 Application Server 6.5 use the UIF. In order to deploy such applications to the Application Server, migrate the UIF to the J2EE Connector Architecture. This section discusses the prerequisites and steps to migrate the applications using UIF to Application Server.

Before migrating the applications, ensure that the UIF is installed on Application Server 6.5. To check for the installation, follow either of the following approaches:

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:

Extension DataObjectExt-cDataObject
Extension RepositoryExt-cLDAPRepository
Extension MetadataService-cMetadataService
Extension RepoValidator-cRepoValidator
Extension BSPRuntime-cBSPRuntime
Extension BSPErrorLogExt-cErrorLogMgr
Extension BSPUserMap-cBSPUserMap

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

AS_HOME/AS/registry/reg.dat

Checking for UIF Binaries in Installation Directories

UIF installers copy specific binary files in to the application server installation. Successfully finding the files listed below, indicates 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:

libcBSPRlop.so
libcBSPRuntime.so
libcBSPUserMap.so
libcDataObject.so
libcErrorLogMgr.so
libcLDAPRepository.so
libcMetadataService.so
libcRepoValidator.so
libjx2cBSPRuntime.so
libjx2cDataObject.so
libjx2cLDAPRepository.so
libjx2cMetadataService.so

List of files to be searched on Windows:

cBSPRlop.dll
cBSPRuntime.dll
cBSPUserMap.dll
cDataObject.dll
ErrorLogMgr.dll
cLDAPRepository.dll
cMetadataService.dll
cRepoValidator.dll
jx2cBSPRuntime.dll
jx2cDataObject.dll
jx2cLDAPRepository.dll
jx2cMetadataService.dll

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

Check for the usage of netscape.bsp package name in the Java sources
Check for the usage of access_cBSPRuntime.getcBSPRuntime method in the sources. You must call this method to acquire the UIF runtime.

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

Migrating JDBC Code

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

Establishing Connections Through the DriverManager Interface

(JDBC 1.0 API), by loading a specific driver and providing a connection URL. This method is used by other Application Servers, such as IBM’s WebSphere 4.0
Using JDBC 2.0 Data Sources

The DataSource interface (JDBC 2.0 API) can be used via a configurable connection pool. According to J2EE 1.2, a data source is accessed through the JNDI naming service

Note –

Application Server does not support the Native Type 2 JDBC drivers bundled with Application Server 6.x. Code that uses the Type 2 drivers to access third party JDBC drivers, must be manually migrated.

Establishing Connections Through the DriverManager Interface

Although this database access method is not recommended, as it is obsolete and is not very effective, there can be some applications that still use this approach.

In this case, the access code is 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 Application Server 6.x to Application Server, 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, 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.”
Click the tab “JVM Settings” from the right pane.
Click the option Path Settings and add the path in the classpath suffix text entry box.
Once the changes are made, click “Save.”
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, enhanced productivity by simplifying code and implementation, and code portability.

If there is a datasource by the name ”xyz’ on Application Server 6.x application and you do not want any impact on your JNDI lookup code, make sure that the datasource you create for Application Server 8.1 is prefixed with jdbc. For example: jdbc/xyz.

For information on configuring JDBC Datasources, see Chapter 3, JDBC Resources, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

Looking Up the Data Source Via JNDI To Obtain a Connection

To obtain a connection from a data source, do the following:

To Connect to a Data Source

Obtain the initial JNDI context.

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

InitialContext ctx = new InitialContext();

Use a JNDI lookup to obtain a data source reference.

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 is cast as a DataSource type object:

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

Use the data source reference to obtain the connection.

This operation requires the following line of code:

conn = ds.getConnection();

Application Server 6.x and Application Server both follow these technique to obtain a connection from the data source.

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 Application Server 6.x

Application Server 6.x 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 8.1

The authentication is done based on JAAS (Java Authorization and Authentication System API). If a client does not provide a CallbackHandler, then the default CallbackHandler, called the LoginModule, is used by the ACC to obtain the authentication data.

For detailed instructions on using JAAS for authentication, see Chapter 9, Configuring Security, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

Using ACC in Application Server 6.x and Sun Java System Application Server 8.1

In 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 Application Server 6.x applications, a stand-alone client uses the absolute name of the EJB in the JNDI lookup. That is, outside an ACC, the following approach is used to lookup the JNDI:

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

If your application was developed using 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 8.1, 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 8.1. 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 8.1, 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 the administrator with a list of host:port combinations to round robin the ORBs. These host names can also map to multiple IP addresses. If this property is used 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, a host name and port number are provided in your code, in the environment object, that value overrides any other system property settings.

The Provider URL to which the client is connected in 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 8.1, 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 8.1.

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

Load-balancing and Failover Features in ACC Clients (Enterprise Edition)

Load balancing is handled implicitly by the CXS engine in SunONE Application Server 6.5 upon number of Java engines registered. In Application Server 8.1 Enterprise Edition, this feature requires explicit configuration details from the clients.

After migrating the deployment descriptors from 6.x to 8.1, provide the configuration details in the sun-acc.xml file to enable failover capabilities in your ACC client. See Migrating Deployment Descriptors for information on migrating deployment descriptors.

Define the load balancing properties in the sun-acc.xml file to provide a highly available ACC client. The properties are defined as property elements in the sun-acc.xml file.

com.sun.appserv.iiop.endpoints

This property defines the list of one or more IIOP endpoints. An endpoint is specified as host:port where host is the name or IP address of the system where Application Server 8.1 is running. Port is the IIOP port at which the server is listening for IIOP requests.
com.sun.appserv.iiop.loadbalancingpolicy

If the endpoint property is specified, then, this property is used to specify the load balancing policy. The value for this property must be InitialContext-based.

For example:

<client-container>
   <target-server name="qasol-e1" address="qasol-e1" port="3700">
   <property name="com.sun.appserv.iiop.loadbalancingpolicy" value="ic-based" />
   <property name="com.sun.appserv.iiop.endpoints" value="qasol-e1:3700,qasol-e1:3800" />
</client-container>

To failover an ACC client on the RMI/IIOP path, information about all the endpoints in a cluster to which the RMI/ IIOP requests can be failed over must be available. You must have defined the IIOP endpoints in the domain.xml file. The iiop-cluster element under the availability-service element defines the IIOP endpoints.

For more information, see Chapter 4, Configuring Load Balancing and Failover, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

Migrating Applications to Support HTTP Failover (Enterprise Edition)

Application Server, Enterprise Edition 8.1 supports load balancing and HTTP session persistence. The primary goal of load-balancing is to distribute the work load between multiple server instances, thereby increasing overall throughput of the system.

For information on configuring HTTP session failover, see HTTP Session Failover in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

To migrate 6.x HTTP applications to Application Server 8.1 EE environment and enable load-balancing capabilities, perform the following steps. Note that, no code changes will be required in the application.

To Migrate and Enable Load-Balancing

Make sure that at least two application server instances are created and configured.

Rename the ias-web-app.xml to sun-web.xml.

For more information on migrating the deployment descriptors, see the Migrating Deployment Descriptors.

Update the <DOCTYPE definition with the following code:

<!DOCTYPE web-app PUBLIC 
’-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN’ 
’http://java.sun.com/j2ee/dtds/web-app_2_3-1.dtd’>

In Sun ONE Application Server 6.5, the failover of HTTP applications was based on Dsync mechanism. The configuration for HTTP failover was done in the ias-web-app.xml file.

The <server-info> element defined under the <servlet-info> element, specifies whether the server on which the servlet will be served from is enabled.

The <session-info> element defines the following:
- dsync-type: This can take the value dsync-distributed or dsync-local.
  
  dsync-distributed implies that the session is distributed and thus available on all configured servers.
  
  dsync-local implies that the session is available on available only on the server on which the session was created.
  - impl: This can take the values distributed or lite.
    
    distributed implies that the session on distributed.
    
    lite implies that the session is local to the Java engine where the session was created. If this value is set, the dsync-type setting is ignored. I
    
    In Sun Java System Application Server 8.1, to enable failover of applications on the HTTP route, you define the following properties in the sun-specific web application deployment descriptor file: sun-web.xml.
  - persistence-store - This can take the values memory, file, or ha. In 6.5, however, only memory based persistence store was supported.
  - persistence-scope - define the scope of persistence.
    - session - For every session, the session information will be saved.
    - modified-session - Only the modified session data will be stored.
    - modified-attribute - Only the modified attribute data will be stored. In 6.5, only modified-attribute sope was supported.
    persistenceFrequency - The frequecy can be for every web method or time based. In 6.5, only web-method was supported.
    - web-method - The session state is stored at the end of each web request prior to sending a response back to the client. This mode provides the best guarantee that the session state is fully updated in case of failure.
    - time-based - The session state is stored in the background at the specified frequency. This mode provides less of a guarantee that the session state is fully updated. However, it can provide a significant performance improvement because the state is not stored after each request.
      
      A sample of the sun-web.xml file is given below:
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE 
sun-web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7.1 Servlet 2.3//EN' 
"http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_3-1.dtd'>
  <sun-web-app>
    <session-config>
      <seession-manager>
        <manager-properties>
          <property name="persistence-type" value "ha'>
          <property name="persistenceFrequency" value ="web-based">
        </manager-properties>
        <store-properties>
          <property name="persistenceScope" value="session">
        </store-properties>
      </session-manager>
    </session-config>
</sun-web-app> 
```
      For more information on the sun-web.xml configuration file, see The sun-web.xml File in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer’s Guide.

Sun Java System Application Server 8.1 requires the load balancer plug-in to be installed and configured, in order to load-balance the HTTP request and failover the requests to available server instances in a cluster when there is a failure.

For more information about the load balancer, see Chapter 4, Configuring Load Balancing and Failover, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

In the load-balancer.xml file, make sure that the web-module enabled element is set to true.
```
<loadbalancer>
  <cluster name=cluster1>
  ...
    <web-module context-root="abc" enabled=true>
  </cluster>
  <property name="https-routing" value="true"/>
</loadbalancer> 
```
enabled=true specifies that the web module is active (enabled) for requests to be load balanced to it.

Define the https-routing property and set its value to true.

For more information on editing the load-balancer.xml file, see Chapter 4, Configuring Load Balancing and Failover, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.

Deploy the applications on all server instances that is participating in load balancing.

Migrating Applications from Application Server 7 to Application Server 8.1

Migrating Rich Clients From 7 PE/SE to 8.1 EE

Migrating rich clients that are deployed in Application Server 7 PE/SE to Application Server 8.1 is rather simple. The deployment descriptors used in Application Server 7 can be used as is in Application Server 8.1. However, if you wish to enable load-balancing and failover features in your client applications, you will need to configure the load-balancing and failover capabilities in the deployment descriptors.

The following procedure describes the steps to migrate the applications:

To Migrate Rich Clients

Identify the components which were installed previously.

Find out the server-instances, using asadmin command or through the directory listing.

The asadmin command requires administration instances to be running. However, administration instances need not be running if the directory listing is used to identify the instances.

In the server.xml file, add the following jvm-options under jvm-config element to enable RMI/IIOP failover feature:

<jvm-config java-home=path...server-classpath=path>
  <jvm-option>
    Dorg.omg.PortableInterceptor.ORBInitializerClass.
com.sun.appserv.ee.iiop.EEORBInitializer
  </jvm-option>
  <jvm-option>
    Dorg.omg.PortableInterceptor.ORBInitializerClass.
com.sun.appserv.ee.iiop.EEIORInterceptorInitializer 
  </jvm-option>
  <jvm-option>
    Dcom.sun.CORBA.connection.ORBSocketFactoryClass=
com.sun.appserv.enterprise.iiop.EEIIOPSocketFactory 
  </jvm-option>
</jvm-config>

Update the availability-service element with availability-enabled flag set to True:

<availability-service availability-enabled="true">
  <persistence-store>
    <property-name="store-pool-jndi-name" value="" />
    <property-name="cluster-id" value="cluster1" />
  </persistence-store>
</availability-service>

Modify the server classpath entry under the java-config element to include:

install_dir/SUNWhads/4.2.2-17/lib/hadbjdbc.jar;

install_dir/lib/appserv-rt-ee.jar

Add the following jvm-option under java-config element:
<jvm-option>
Dcom.sun.aas.hadbRoot=install-dir/SUNWhadb/4.2.2-17
</jvm-option>

Update the sun-acc.xml with the following new load-balancing properties:

<property-name="com.sun.appserv.iiop.loadbalancingpolicy" value="ic-based" />
<property name="com.sun.appserv.iiop.endpoints" value=<host>:<port>" />

Migrating Rich Clients From 7 EE to 8.1 EE

To migrate 7 EE applications to 8.1 EE, follow the steps given below:

To Migrate Rich Clients From 7 EE to 8.1 EE

Add the following jvm-options under java-config element for enabling RMI/IIOP failover feature:

<jvm-config java-home=path...server-classpath=path>
  <jvm-option>
    Dorg.omg.PortableInterceptor.ORBInitializerClass.com.sun.appserv.ee.iiop.EEORBInitializer
  </jvm-option>
  <jvm-option>
    Dorg.omg.PortableInterceptor.ORBInitializerClass.com.sun.appserv.ee.iiop.EEIORInterceptorInitializer 
  </jvm-option>
  <jvm-option>
    Dcom.sun.CORBA.connection.ORBSocketFactoryClass=com.sun.appserv.enterprise.iiop.EEIIOPSocketFactory 
  </jvm-option>
</jvm-config>

Add the following entry in server.xml to setup the iiop-cluster.

<iiop-cluster>
     <iiop-server-instance name=<server-name>>
         <iiop-endpoint id=orb-listener-id, host=hostname, port=orb-listener-port/>
    </iiop-server-instance>
</iiop-cluster>

Update sun-acc.xml with the following new entries:

<property-name=Â¨com.sun.appserv.iiop.loadbalancingpolicy" value="ic-based" />
<property name="com.sun.appserv.iiop.endpoints" value="hostname:port" />

The host and port is that of ORB-lister-1 ”s which is defined under iiop-listener element in server.xml.

Migrating 7 2004Q2, SE Applications to Application Server 8.1 EE

To migrate the applications from 7 2004Q2 SE, follow the steps described in the section Migrating Rich Clients From 7 PE/SE to 8.1 EE.

Migrating EJB Applications to Support SFSB Failover

Application Server 7 does not support failover of stateful session beans. Application Server 8.1, Platform Edition supports failover of stateful session beans on the HTTP and RMI/IIOP path. This section describes the procedure to migrate EJB applications from Application Server 7 SE/PE/EE to Application Server 8.1 EE to support SFSB state failover.

Migrating EJB Applications From 7 SE/PE/EE to 8.1 EE

To achieve high availability of EJB applications that use stateful session beans to persist the data, you need to configure a persistent store for each cluster of application servers, where client session information can be maintained across potential failures of individual appserver instances. In addition, the availability-enabled flag must be turned on for each server instance in the cluster.

Application Server 8.1 EE supports the failover of stateful session beans. In order to enable this feature in your EJB applications that were deployed to Application Server 8.1 EE, follow the steps below:

To migrate Entity beans from previous releases of Sun’s Application Server, follow the procedure described in Entity Beans.

SFSB failover is supported when the SFSB is accessed from EJBs, servlets, or Java Server Pages in applications executing in the same application server process. The SFSB can be accessed through either a local or remote interface.

To take advantage of SFSB state failover support, you need not edit the code. However, you need to provide all the configuration parameters needed for checkpointing the SFSBs in the Sun-specific deployment descriptor (sun-ejb-jar.xml) or in the server configuration file.

For detailed information on SFSB Failover, see Stateful Session Bean Failover in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide.