Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Application Server 7 Migrating and Redeploying Server Applications Guide

Chapter 2
Migration Considerations and Strategies

This chapter describes the considerations and strategies that are needed when moving J2EE applications from Sun™ ONE Application Server 6.0 and 6.5 to Sun ONE Application Server 7.

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

The following topics are addressed:

About Sun ONE Application Server 6.0/6.5

Sun ONE Application Server version 6.0 is a multi-platform application server based entirely on the J2EE 1.2 specification. Supported platforms include Windows NT and 2000, Solaris, AIX, and HP-UX.

In addition, Sun ONE Application Server 6.0 integrates with many Web servers through specific Web connector plug-ins that it ships with. These connectors enable it to be coupled with Sun ONE Web Server, Microsoft IIS, or Apache.

The Sun ONE Application Server 6.0/6.5 architecture is shown in the following figure.

Figure 2-1  

Figure showing 4 internal servers of Sun ONE Application Server 6.0/6.5

Sun ONE Application Server 6.0/6.5 Architecture

As shown in the figure Sun ONE Application Server 6.0/6.5 Architecture, there are four internal servers, which are often called engines or processes. These processes are responsible for all the processing in the Sun ONE Application Server. The four internal servers of the Sun ONE Application Server 6.0/6.5 are:

Executive Server - provides most system services (some services are managed by the Administrative Server).

Administrative Server - provides system services for Sun ONE Application Server Administration and failure recovery.

Java Server - provides services to java applications.

C++ Server - components written in C++ are hosted in C++ server.

When a web server forwards requests to Sun ONE Application Server 6.0/6.5, the requests are first received by the Executive Server process (KXS). The KXS process forwards the request either to a Java Server process (KJS) or to a C++ Server process (KCS). A KJS process runs Java programming logic, whereas a KCS process runs C++ programming logic. Each KJS and KCS process maintains a specified number of threads and runs the programming logic to completion on those threads. The results are returned to the web server and sent on to the client browser.

Migration Issues From Sun ONE Application Server 6.x to 7

This section describes the issues that will arise while migrating the main components of a typical J2EE application from Sun ONE Application Server 6.0 and 6.5 to Sun ONE Application Server 7.

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.0 and 6.5 to Sun ONE Application Server 7. 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.

The following migration processes are described:

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.0/6.5 to Sun ONE Application Server 7, as long as Sun ONE 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 Sun ONE Application Server 7, you should:

The figure Using the JVM Settings to Set the Classpath Suffix shows adding the path of the driver in the classpath suffix through GUI.

Figure 2-2  

Figure shows the JVM path settings used to add the CLASSPATH suffix.

Using the JVM Settings to Set the Classpath Suffix

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 Sun ONE Application Server installation root directory.

In Sun ONE Application Server 7, 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 asadmin.bat in windows and asadmin file in Solaris kept at Sun ONE Application Server 7 installation’s bin directory. Then on the asadmin prompt, following commands would create connection pool and JNDI resource.

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

For example:

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:

For example:

Here jdbc resource is created for the connection pool created above with the JNDI name ‘jdbc/IBANK’.

Here is the procedure to follow when registering a data source in Sun ONE Application Server 7 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 Sun ONE Application Server 7 installation directory.
    2. Modify the CLASSPATH by setting the path for the driver through the GUI of the admin server. 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 Sun ONE Application Server 7, 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 Sun ONE 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.

Figure 2-3  

Figure shows how to configure Connection Pools in Sun ONE Application Server.

Configuring Connection Pool through GUI

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

Sun ONE Application Server 7 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 would have 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:

Sun ONE Application Server 6.0/6.5 and 7 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.0/6.5 complies with the JSP 1.1 specification and Sun ONE Application Server 7 complies with the JSP 1.2 specification.

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

The most significant changes are

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

The implementation of JSP custom tag libraries in Sun ONE Application Server 6.0 and 6.5 complies with the J2EE specification. Consequently, migration of JSP custom tag libraries to Sun ONE Application Server 7 does not pose any particular problem, nor require any modifications to be made.

Migrating Servlets

Sun ONE Application Server 6.0 and 6.5 support the Servlet 2.2 API whereas Sun ONE Application Server 7, supports the Servlet 2.3 API.

Servlet API 2.3 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.3.

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 Sun ONE Application Server 7 as it uses new class loader hierarchy as compared to Sun ONE Application Server 6.0/6.5. 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 Appendix C.

EJB Migration

As mentioned in About Sun ONE Application Server 7, while Sun ONE Application Server 6.0 and 6.5 support the EJB 1.1 specification, Sun ONE Application Server 7 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 Sun ONE Application Server 7, the use of the EJB 2.0 architecture is recommended to leverage its enhanced capabilities.

To migrate EJB 1.1 to EJB 2.0, please refer to Appendix C.

EJB Changes Specific to Sun ONE Application Server 7

Migrating EJB’s from Sun ONE Application server 6.0/6.5 to Sun ONE Application Server 7 would not require any changes in the EJB code. The following DTD changes are required.

Session Beans:

Entity Beans:

Migrating Web Applications

Sun ONE Application Server 6.0 and 6.5 support servlets (Servlet API 2.2), and JSPs (JSP 1.1). Sun ONE Application Server 7 on the other hand supports servlets (Servlet API 2.3) and JSPs (JSP 1.2).

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 1.3 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.0/6.5 to Sun ONE Application Server 7 would not require any changes in the Java/JSP code. The following changes are, however, still required.

Once the web.xml and ias-web.xml are migrated in the above-mentioned fashion, the Web application (.WAR archive) can be deployed from the Sun ONE Application Server 7’s GUI interface of the admin server or from the command line utility asadmin, where the deployment command should mention the type of application as web.

The command line utility asadmin can be invoked by running asadmin.bat file kept at Sun ONE Application Server 7 installation’s bin directory.

The command at asadmin prompt would be:

Deployment can also be done from the Sun ONE Studio development environment as explained in section Deploying an application in Sun ONE Application Server 7.

Particular setbacks when migrating servlets and JSPs

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

In case if the web-application is using a server resource, for example, a DataSource, then Sun ONE Application Server 7 requires that this resource be declared inside the web.xml and correspondingly inside sun-web.xml. For declaring a DataSource called jdbc/iBank, the <resource-ref> tag as declared inside the web.xml would look like this:

    <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 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.0 and 6.5 support the EJB 1.1 API whereas Sun ONE Application Server 7 supports the EJB 2.0 API. Thereby, both can support:

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

J2EE 1.3 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.0 or 6.5 and Sun ONE Application Server 7 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.0/6.5 and 7 primarily supports 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, extension .jar) for EJBs and web archives (WAR, extension .war) for servlets and JSPs.

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

Note: Sun ONE Application Server 7 uses a new class loader hierarchy as compared to Sun ONE Application Server 6.0/6.5. In the new scheme of things, 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. Hence all classes loaded by the JAR class loader are available/ accessible to the WAR module but the reverse is not true. Hence, suppose there is a certain class which is required by the JAR as well as the WAR, then it should be packaged inside the JAR module only. If this guideline is not followed it would lead to class conflicts hence ClassCastException.

Application root context and access URL

There is one particular difference between Sun ONE Application Server 6.0/6.5 and Sun ONE Application Server 7, 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, then the access URL for this application will differ depending on the application server used:

The TCP port used as default by Sun ONE Application Server 7 is port 80.

Although the difference in access URLs between Sun ONE Application Server 6.0/6.5 and Sun ONE Application Server 7 may appear minor, it can however be problematical 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.0/6.5.

Migrating Proprietary Extensions

A number of classes proprietary to the Sun ONE Application Server 6.0/ 6.5 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 Sun ONE Application Server 7. Applications using any classes belonging to the above package will have to be re written such that the applications use standard J2EE APIs. Applications using Custom JSP tags and UIF framework also needs to be rewritten to use standard J2EE API.

Migrating Example: iBank

In this section we describe the process for migrating the main components of a typical J2EE application from Sun ONE Application Server 6.0 and 6.5 to Sun ONE Application Server 7. For each aspect we highlight any problems posed by migration, and suggest practical solutions to overcome these.

For this migration process, the J2EE application presented is called ‘iBank’ and is based on the actual migration of the iBank application from the Sun ONE Application Server 6.0 and 6.5 versions to Sun ONE Application Server 7. iBank simulates an online banking service and covers all of the aspects traditionally associated with a J2EE application.

The sensitive points of the J2EE specification covered by the iBank application are summarized below:

The iBank application is presented in detail in Appendix A - iBank Application specification.

The iBank Application can be migrated to Sun ONE Application Server 7 by manually changing the deployment descriptors or using Sun ONE Studio or using Sun ONE Migration Tool. The recommended process among the above three is the Sun ONE Migration Tool. If the migration has to be carried out without converting CMP’s to 2.0, then follow the section "Manual Migration of iBank Application" or use Sun ONE Migration Tool.

In this guide the Manual Migration process and the migration using Sun ONE Studio are discussed. The Automatic migration procedure, using Sun ONE Migration Tool for iBank example, is discussed in the documentation provided with the Migration Tool itself.

Manual Migration of iBank Application

The manual migration does not require any major changes in the source code as Sun ONE Application Server 7 supports CMP 1.1. However manual migration of the application would require a few changes to be made in the following aspects:

Web application changes

Migrating iBank from Sun ONE Application server 6.0/6.5 to Sun ONE Application Server 7 would not require any changes in the web application part of the iBank application. Delete the ias-web.xml file from the source directory, as there is no information in this file that can go inside its counterpart in the Sun ONE Application Server 7 Deployment descriptor, the sun-web.xml file. The web.xml requires no changes.

However, generically speaking, if there is some information inside the web.xml that needs to be mapped to the Server specific resources, then a declaration in sun-web.xml would have been required in that case. For example, if the web.xml file had declared a javax.sql.Datasource type resource reference, it would be mandatory to map it to the JNDI name of the actual DataSource on the Sever, inside the sun-web.xml.

The migrator needs to create the new sun-web.xml. The creation process is outlined below:

  1. Create a new XML file which has the following DOCTYPE definition on top:

    2. <!DOCTYPE sun-web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7 Servlet 2.3//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_3-0.dtd'>

    Save this file as “sun-web.xml”.

  2. The root tag of this XML file, as evident from the DOCTYPE definition, is sun-web. In the DTD, this element is defined as

    3. <!ELEMENT sun-web-app (security-role-mapping*, servlet*, session-config?, resource-env-ref*, resource-ref*, ejb-ref*, cache?, class-loader?, jsp-config?, locale-charset-info?, property*)>

    From the above declaration it is clear that all tags are optional so a default sun-web.xml would look something like:

    <!DOCTYPE sun-web-app SYSTEM "http://www.sun.com/software/sunone/appserver/dtds/sun-web-app_2_3-0.dtd">

    </sun-web-app>

  3. For declaring any resource references, the element declaration would be:

    4. <!ELEMENT resource-ref (res-ref-name, jndi-name, default-resource-principal?)> where the sub elements are:

    <!ELEMENT res-ref-name (#PCDATA)>

    <!ELEMENT default-resource-principal (name, password)>

    <!ELEMENT jndi-name (#PCDATA)>

EJB Changes

Migrating iBank from Sun ONE Application server 6.5 to Sun ONE Application Server 7 would not require any changes in the EJB code.

Session Beans:

In ejb-jar.xml: The <!DOCTYPE definition should be modified to point to the latest DTD url in case of ejb-jar.xml. This new definition should look like this:

<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>

In ias-ejb-jar.xml: The ias-ejb-jar.xml in Sun ONE Application server 6.5 has been replaced by sun-ejb-jar.xml in Sun ONE Application server 7. Since the DTDs for these two XML files are radically different, the migrator needs to create the new sun-ejb-jar.xml by extracting relevant information from the ejb-jar.xml and ias-ejb-jar.xml. The creation process is outlined below:

  1. Create a new XML file which has the following DOCTYPE definition on top:

    2. <!DOCTYPE sun-ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7 EJB 2.0//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-ejb-jar_2_0-0.dtd'>

    Save this file as “sun-ejb-jar.xml”, along with the modified ejb-jar.xml.

  2. The root tag of this XML file, as evident from the DOCTYPE definition, is sun-ejb-jar. In the DTD, this element is defined as

    3. <!ELEMENT sun-ejb-jar (security-role-mapping*,enterprise-beans)>

    The security-role-mapping tag is meant for mapping the security roles declared in the ejb-jar.xml. As in the iBank application, there is no security declared in the ejb-jar.xml file, we will skip the security-role-mapping optional tag and focus on the enterprise-beans tag. Right now, the sun-ejb-jar.xml file should look like.

    <sun-ejb-jar>

        <enterprise-beans>

        </enterprise-beans>

    </sun-ejb-jar>

    NOTE: We have not included the header part of the document, namely the XML declaration and DOCTYPE definition, here for brevity.

  3. The enterprise-beans element is defined in the DTD as

    4. <!ELEMENT enterprise-beans (name?, unique-id?, ejb*, pm-descriptors?, cmp-resource?)>

    The optional name element should contain the canonical name of the enterprise-beans. You may give it some name. We will skip this tag.

    The unique-id element is used by the Sun ONE Application Server and is inserted by the Application Server automatically at the time of application deployment. We will skip this tag.

    The EJB element is the tag in which we are interested. This is the element describing runtime bindings for a single EJB. It is defined in the DTD as

    <!ELEMENT ejb (ejb-name, jndi-name?, ejb-ref*, resource-ref*, resource-env-ref*, pass-by-reference?, cmp?, principal?, mdb-connection-factory?, jms-durable-subscription-name?, jms-max-messages-load?, ior-security-config?, is-read-only-bean?, refresh-period-in-seconds?, commit-option?, gen-classes?, bean-pool?, bean-cache?)>

    In our case, the ejb element will contain the ejb-name element. The ejb-name element will contain the canonical name of the EJB. This name should be the same as declared inside the ejb-name element of the ejb-jar.xml for that EJB. It will also contain the jndi-name of the EJB. One of the differences between Sun ONE Application Server 6.5 and 7 is the flexibility of the latter in providing freedom to the bean developer to have different ejb-name and jndi-name of an EJB. In Sun ONE Application Server 6.5, the jndi name of an EJB by default was ejb/<ejb-name>.

    To allow for smooth migration, we need to keep the jndi-names of the EJB and all other resources to be same as they were on Sun ONE Application Server 6.5. Hence, we declare the ejb-name of all the EJBs’ to be ejb/<ejb-name>.

    Using the logic described above, the sun-ejb-jar.xml now should look like

    <sun-ejb-jar>

        <enterprise-beans>

            <ejb>

                <ejb-name>BankTeller</ejb-name>

                <jndi-name>ejb/BankTeller</jndi-name>

            </ejb>

            <ejb>

                <ejb-name>InterestCalculator</ejb-name>

                <jndi-name>ejb/InterestCalculator</jndi-name>

            </ejb>

        </enterprise-beans>

    </sun-ejb-jar>

  4. For each <ejb-ref> element inside the ejb-jar.xml, there should be a corresponding <ejb-ref> element inside the sun-ejb-jar.xml. The <ejb-ref> element inside the ejb-jar.xml is used to declare all the EJBs referenced from inside the bean class of that EJB. While the bean class code will reference the EJB by using its <ejb-ref-name>, this <ejb-ref-name> has to be mapped to the actual <jndi-name> of the bean on the Application Server. Hence, this serves as a mechanism to add a layer of abstraction between the name referenced by the EJB implementation and the actual JNDI name of the bean.

    5. Using the logic explained above, let us examine the BankTeller EJB. In the ejb-jar.xml, there are two <ejb-ref> declarations inside this EJB. The first one is for the Customer EJB (an entity bean in the Entity Bean module). As we have explained in point #3 above, the JNDI names of all EJBs will be kept as ejb/<ejb-name>, we will add this declaration inside the sun-ejb-jar.xml

    <sun-ejb-jar>

        <enterprise-beans>

            <ejb>

                <ejb-name>BankTeller</ejb-name>

                <jndi-name>ejb/BankTeller</jndi-name>

                <ejb-ref>

                    <ejb-ref-name>Customer</ejb-ref-name>

                    <jndi-name>ejb/Customer</jndi-name>

            </ejb-ref>

        </ejb>

        <ejb>

            <ejb-name>InterestCalculator</ejb-name>

            <jndi-name>ejb/InterestCalculator</jndi-name>

        </ejb>

    </enterprise-beans>

    </sun-ejb-jar>

    Similarly, we will add a similar <ejb-ref> tag for Account EJB. Since the InterestCalculator bean does not have a <ejb-ref> tag inside the ejb-jar.xml, it is not required inside the sun-ejb-jar.xml also. By now, the sun-ejb-jar.xml should look like this

    <sun-ejb-jar>

        <enterprise-beans>

            <ejb>

                <ejb-name>BankTeller</ejb-name>

                <jndi-name>ejb/BankTeller</jndi-name>

                <ejb-ref>

                    <ejb-ref-name>Customer</ejb-ref-name>

                    <jndi-name>ejb/Customer</jndi-name>

                </ejb-ref>

                <ejb-ref>

                    <ejb-ref-name>Account</ejb-ref-name>

                    <jndi-name>ejb/Account</jndi-name>

                </ejb-ref>

            </ejb>

            <ejb>

                <ejb-name>InterestCalculator</ejb-name>

                <jndi-name>ejb/InterestCalculator</jndi-name>

            </ejb>

        </enterprise-beans>

    </sun-ejb-jar>

  5. The ejb element would contain element pass-by-reference <!ELEMENT pass-by-reference (#PCData).

    6. pass-by-reference elements controls use of Pass by Reference semantics. The EJB specification requires pass by value, which will be the default mode of operation. This can be set to true for non-compliant operation and possibly higher performance. It can apply to all the enclosed EJB modules. Allowed values are true and false. Default will be false.

  6. The ejb element would also have element bean-cache.

    7. <!ELEMENT bean-cache (max-cache-size?, is-cache-overflow-allowed?, cache-idle-timeout-in-seconds?, removal-timeout-in-seconds?, victim-selection-policy?)>

    This element is used only for stateful session beans and entity beans. In iBank, only BankTeller session bean would have this entry.

    In this tag, max-cache-size defines the maximum number of beans in the cache. cache-idle-timeout-in-seconds specifies the maximum time that a stateful session bean or entity bean is allowed to be idle in the cache. After this time, the bean is passivated to backup store. This is a hint to server. Default value for cache-idle-timeout-in-seconds is 10 minutes.

    The amount of time that the bean remains passivated (i.e. idle in the backup store) is controlled by removal-timeout-in-seconds parameter. Note that if a bean was not accessed beyond removal-timeout-in-seconds, then it will be removed from the backup store and hence will not be accessible to the client. The Default value for removal-timeout-in-seconds is 60min.

    With the above entries, sun-ejb-jar.xml should look like this:

    <sun-ejb-jar>

        <enterprise-beans>

            <ejb>

                <ejb-name>BankTeller</ejb-name>

                <jndi-name>ejb/BankTeller</jndi-name>

                <ejb-ref>

                    <ejb-ref-name>Customer</ejb-ref-name>

                    <jndi-name>ejb/Customer</jndi-name>

                </ejb-ref>

                <ejb-ref>

                    <ejb-ref-name>Account</ejb-ref-name>

                    <jndi-name>ejb/Account</jndi-name>

                </ejb-ref>

                <pass-by-reference>false</pass-by-reference>

                <bean-cache>

                    <cache-idle-timeout-in-seconds>

                        0

                    </cache-idle-timeout-in-seconds>

                    <removal-timeout-in-seconds>

                        0

                    /removal-timeout-in-seconds>

                </bean-cache>

            </ejb>

            <ejb>

                <ejb-name>InterestCalculator</ejb-name>

                <jndi-name>ejb/InterestCalculator</jndi-name>

                <pass-by-reference>false</pass-by-reference>

            </ejb>

        </enterprise-beans>

    </sun-ejb-jar>

  7. The element used only for Stateless session bean and message-driven bean pools is bean-pool.

    8. <!ELEMENT bean-pool (steady-pool-size?, resize-quantity?, max-pool-size?, pool-idle-timeout-in-seconds?, max-wait-time-in-millis?)>

    steady-pool-size specified the initial and minimum number of beans that must be maintained in the pool.

    resize-quantity specifies the number of beans to be created or deleted when the pool is being serviced by the pool manager.

    max-pool-size specifies the maximum pool size. Valid values are from 0 to MAX_INTEGER.

    max-pool-size spiffiest the maximum pool size.

    pool-idle-timeout-in-seconds specifies the maximum time that a stateless session bean or message-driven bean is allowed to be idle in the pool.

    Finally the sun-ejb-jar.xml would having following shape:

    <sun-ejb-jar>

        <enterprise-beans>

            <ejb>

                <ejb-name>BankTeller</ejb-name>

                <jndi-name>ejb/BankTeller</jndi-name>

                <ejb-ref>

                    <ejb-ref-name>Customer</ejb-ref-name>

                    <jndi-name>ejb/Customer</jndi-name>

                </ejb-ref>

                <ejb-ref>

                    <ejb-ref-name>Account</ejb-ref-name>

                    <jndi-name>ejb/Account</jndi-name>

                </ejb-ref>

                <pass-by-reference>false</pass-by-reference>

                <bean-cache>

                    <cache-idle-timeout-in-seconds>

                        0

                    </cache-idle-timeout-in-seconds>

                    <removal-timeout-in-seconds>

                        0

                    </removal-timeout-in-seconds>

                </bean-cache>

            </ejb>

            <ejb>

                <ejb-name>InterestCalculator</ejb-name>

                <jndi-name>ejb/InterestCalculator</jndi-name>

                <pass-by-reference>false</pass-by-reference>

                <bean-pool>

                    <pool-idle-timeout-in-seconds>

                        0

                    </pool-idle-timeout-in-seconds>

                </bean-pool>

            </ejb>

        </enterprise-beans>

    </sun-ejb-jar>

Entity Beans:

In ejb-jar.xml: The <!DOCTYPE definition should be modified to point to the latest DTD url in case of ejb-jar.xml. This new definition should look like this:

<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>

Insert <cmp-version> tag with value 1.1 for all CMPs beans in ejb-jar.xml.

Entry for entity bean would look like:

<entity>

    <description>Account CMP entity bean</description>

    <ejb-name>Account</ejb-name>

    <home>com.sun.bank.ejb.entity.AccountHome</home>

    <remote>com.sun.bank.ejb.entity.Account</remote>

    <ejb-class>com.sun.bank.ejb.entity.AccountEJB</ejb-class>

    <persistence-type>Container</persistence-type>

    <prim-key-class>com.sun.bank.ejb.entity.AccountPK</prim-key-class>

    <reentrant>False</reentrant>

    <cmp-version>1.x</cmp-version>

<cmp-field>

        <field-name>branchCode</field-name></cmp-field>

<cmp-field>

        <field-name>accTypeId</field-name></cmp-field>

<cmp-field>

        <field-name>accBalance</field-name></cmp-field>

<cmp-field>

        <field-name>custNo</field-name></cmp-field>

<cmp-field>

        <field-name>accNo</field-name></cmp-field>

</entity>

similarly all the CMP beans would have this entry.

Similar to Session Beans, the ias-ejb-jar.xml in Sun ONE Application server 6.5 has been replaced by sun-ejb-jar.xml in Sun ONE Application server 7. Since the DTDs for this two XML files are radically different, the migrator needs to create the new sun-ejb-jar.xml by extracting relevant information from the ejb-jar.xml and ias-ejb-jar.xml. The creation process is outlined below:

  1. Create a new XML file which has the following DOCTYPE definition on top:

    2. <!DOCTYPE sun-ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7 EJB 2.0//EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-ejb-jar_2_0-0.dtd'>

    Save this file as “sun-ejb-jar.xml”, along with the modified ejb-jar.xml.

  2. The root tag of this XML file, as evident from the DOCTYPE definition, is sun-ejb-jar. In the DTD, this element is defined as

    3. <!ELEMENT sun-ejb-jar (security-role-mapping*, enterprise-beans) >

    The security-role-mapping tag is meant for mapping the security roles declared in the ejb-jar.xml. As in the iBank application, there is no security declared in the ejb-jar.xml file, we will skip the security-role-mapping optional tag and focus on the enterprise-beans tag. Right now, the sun-ejb-jar.xml file should look like.

    <sun-ejb-jar>

        <enterprise-beans>

        </enterprise-beans>

    </sun-ejb-jar>

    NOTE: We have not included the header part of the document, namely the XML declaration and DOCTYPE definition, here for brevity.

  3. The enterprise-beans element is defined in the DTD as

    4. <!ELEMENT enterprise-beans (name?, unique-id?, ejb*, pm-descriptors?, cmp-resource?)>

    The optional name element should contain the canonical name of the enterprise-beans. You may give it some name. We will skip this tag.

    The unique-id element is used by the Sun ONE Application Server and is inserted by the Application Server automatically at the time of application deployment. We will skip this tag.

    The ejb element is the tag in which we are interested. This is the element describing runtime bindings for a single EJB. It is defined in the DTD as

    <!ELEMENT ejb (ejb-name, jndi-name?, ejb-ref*, resource-ref*, resource-env-ref*, pass-by-reference?, cmp?, principal?, mdb-connection-factory?, jms-durable-subscription-name?, jms-max-messages-load?, ior-security-config?, is-read-only-bean?, refresh-period-in-seconds?, commit-option?, gen-classes?, bean-pool?, bean-cache?)>

    In our case, the ejb element will contain the ejb-name element. The ejb-name element will contain the canonical name of the EJB. This name should be the same as declared inside the ejb-name element of the ejb-jar.xml for that EJB. It will also contain the jndi-name of the EJB. One of the differences between Sun ONE Application Server 6.5 and 7 is the flexibility of the latter in providing freedom to the bean developer to have different ejb-name and jndi-name of an EJB. In Sun ONE Application Server 6.5, the JNDI name of an EJB by default was ejb/<ejb-name>.

    To allow for smooth migration, we need to keep the jndi-names of the EJB and all other resources to be same as they were on Sun ONE Application Server 6.5. Hence, we declare the ejb-name of all the ejbs’ to be ejb/<ejb-name>.

    Using the logic described above, the sun-ejb-jar.xml now should look like

    <sun-ejb-jar>

        <enterprise-beans>

            <ejb>

                <ejb-name> Account</ejb-name>

                <jndi-name> ejb/Account</jndi-name>

            </ejb>

            <ejb> --- </ejb>    

            <ejb> --- </ejb>

                    other ejb’s

            <ejb> --- </ejb>

            <ejb> --- </ejb>

        </enterprise-beans>

    </sun-ejb-jar>

  4. The ejb element would contain element pass-by-reference <!ELEMENT pass-by-reference (#PCData).

    5. pass-by-reference elements control use of Pass by Reference semantics. EJB spec requires pass by value, which will be the default mode of operation. This can be set to true for non-compliant operation and possibly higher performance. It can apply to all the enclosedEJBmodules. Allowed values are true and false. Default will be false.

  5. In case of CMP entity beans, element cmp is declared, which describes runtime information for a CMP EntityBean object for EJB1.1 and EJB2.0 beans.

    6. <!ELEMENT cmp (mapping-properties?, is-one-one-cmp?, one-one-finders?)>

    In this mapping-properties contains the location of the persistence vendor specific O/R mapping file. is-one-one-cmp field is used to identify CMP 1.1 with old descriptors. This contains the boolean true if it is CMP 1.1. one-one-finders contains the finders for CMP 1.1.

    This root element finder contains the finder for CMP 1.1 with a method-name and query parameters.

    <!ELEMENT finder (method-name, query-params?, query-filter?, query-variables?)>

    Element method-name contains the method name for the query field. Element query-params contains the query parameters for CMP 1.1 finder.

    query-filter is an optional element which contains the query filter for CMP 1.1 finder.

    After making the above entries in iBank, sun-ejb-jar would look like:

    <sun-ejb-jar>

        <enterprise-beans>

            <ejb>

                <ejb-name> Account</ejb-name>

                <jndi-name> ejb/Account</jndi-name>

                <pass-by-reference>false</pass-by-reference>

                <cmp>

                    <mapping-properties>

                    META-INF/sun-cmp-mappings.xml

                    </mapping-properties>

                    <is-one-one-cmp>true</is-one-one-cmp>

                    <one-one-finders>

                      <finder>

                     <method-name>

                        findOrderedAccountsForCustomer

                     </method-name>

                     <query-params>int custNo</query-params>

                     <query-filter>

                        custNo == custNo

                     </query-filter>

                      </finder>

                    </one-one-finders>

                </cmp>

            </ejb>

            <ejb> --- </ejb>    

            <ejb> --- </ejb>

                        other ejb’s

            <ejb> --- </ejb>

            <ejb> --- </ejb>

        </enterprise-beans>

    </sun-ejb-jar>

    Account is the only entity bean having a finder other than primary key. So the finder entry shown above would only be in the case of Account bean.

  6. The <!ELEMENT commit-option (#PCDATA)> specifies option for committing.
  7. The ejb element would also have an element bean-cache.

    8. <!ELEMENT bean-cache (max-cache-size?, is-cache-overflow-allowed?, cache-idle-timeout-in-seconds?, removal-timeout-in-seconds?, victim-selection-policy?)>

    This element is used only for stateful session beans and entity beans. In this tag, max-cache-size defines the maximum number of beans in the cache. cache-idle-timeout-in-seconds specifies the maximum time that a stateful session bean or an entity bean is allowed to be idle in the cache. After this time, the bean is passivated to backup store. This is a hint to server. Default value for cache-idle-timeout-in-seconds is 10 minutes.

    The amount of time that the bean remains passivated (i.e. idle in the backup store) is controlled by removal-timeout-in-seconds parameter. Note that if a bean was not accessed beyond removal-timeout-in-seconds, then it will be removed from the backup store and hence will not be accessible to the client. The Default value for removal-timeout-in-seconds is 60min.

    With the above entries, sun-ejb-jar.xml should look like this:

    <sun-ejb-jar>

        <enterprise-beans>

            <ejb>

                <ejb-name> Account</ejb-name>

                <jndi-name> ejb/Account</jndi-name>

                <pass-by-reference>false</pass-by-reference>

                <cmp>

                    <mapping-properties>

                     META-INF/sun-cmp-mappings.xml

                    </mapping-properties>

                    <is-one-one-cmp>true</is-one-one-cmp>

                    <one-one-finders>

                      <finder>

                     <method-name>

                        findOrderedAccountsForCustomer

                     </method-name>

                     <query-params>int custNo</query-params>

                     <query-filter>

                        custNo == custNo

                     </query-filter>

                      </finder>

                    </one-one-finders>

                </cmp>

                <commit-option>C</commit-option>

                <bean-cache>

                        <max-cache-size>60</max-cache-size>

                    <cache-idle-timeout-in-seconds>

                      0

                    </cache-idle-timeout-in-seconds>

                </bean-cache>

            </ejb>

            <ejb> --- </ejb>    

            <ejb> --- </ejb>

                        other ejb’s

            <ejb> --- </ejb>

            <ejb> --- </ejb>

        </enterprise-beans>

    </sun-ejb-jar>

  8. In <!ELEMENT enterprise-beans (name?, unique-id?, ejb*, pm-descriptors?, cmp-resource?)>

    9. Element pm-descriptors would be <!ELEMENT pm-descriptors (pm-descriptor+, pm-inuse)> Persistence Manager descriptors contain one or more pm descriptors, but only of them must be in use at any given time.

    pm-descriptor describes the properties for the persistence manager associated with entity bean. pm-identifier element describes the vendor who provided the PM implementation. pm-version further specifies which version of PM vendor product to be used. pm-config specifies the vendor specific config file to be used. pm-class-generator specifies the vendor specific concrete class generator. This is the name of the class specific to a vendor. pm-mapping-factory specifies the vendor specific mapping factory. This is the name of the class specific to a vendor. pm-insue specifies whether this particular PM must be used or not.

    Element cmp-resource contains the database to be used for storing CMP beans in an ejb-jar. <!ELEMENT cmp-resource (jndi-name, default-resource-principal?)>

    Element jndi-name Specifies the JNDI name string. Element default-resource-principal has element name and password to be used when none are specified while accessing a resource.

    <!ELEMENT default-resource-principal ( name, password)>

    Finally sun-ejb-jar.xml would look like:

<sun-ejb-jar>

    <enterprise-beans>

        <ejb>

            <ejb-name> Account</ejb-name>

            <jndi-name> ejb/Account</jndi-name>

            <pass-by-reference>false</pass-by-reference>

            <cmp>

                <mapping-properties>

                 META-INF/sun-cmp-mappings.xml

                </mapping-properties>

                <is-one-one-cmp>true</is-one-one-cmp>

                <one-one-finders>

                  <finder>

                 <method-name>

                    findOrderedAccountsForCustomer

                 </method-name>

                 <query-params>int custNo</query-params>

                 <query-filter>

                    custNo == custNo

                 </query-filter>

                  </finder>

                </one-one-finders>

            </cmp>

            <commit-option>C</commit-option>

            <bean-cache>

                    <max-cache-size>60</max-cache-size>

                <cache-idle-timeout-in-seconds>

                    0

                </cache-idle-timeout-in-seconds>

            </bean-cache>

        </ejb>

        <ejb> --- </ejb>

        <ejb> --- </ejb>

                    other ejb’s

        <ejb> --- </ejb>

        <ejb> --- </ejb>

        <pm-descriptors>

            <pm-descriptor>

            <pm-identifier>IPLANET</pm-identifier>

            <pm-version>1.0</pm-version>

            <pm-class-generator>

                com.iplanet.ias.persistence.

                internal.ejb.ejbc.JDOCodeGenerator

            </pm-class-generator>

            <pm-mapping-factory>

            com.iplanet.ias.cmp.NullFactory

            </pm-mapping-factory>

            </pm-descriptor>

            <pm-inuse>

            <pm-identifier>IPLANET</pm-identifier>

            <pm-version>1.0</pm-version></pm-inuse>

        </pm-descriptors>

        <cmp-resource>

        <jndi-name>jdo/pmf</jndi-name>

        </cmp-resource>

    </enterprise-beans>

</sun-ejb-jar>

Generate dbschema by using the capture-schema utility in the Sun ONE Application Server 7 installation’s bin directory. Execute capture-schema.bat file kept in bin directory and specify the valid inputs for the database URL, username, password and specify the tables for which schema has to be generated. By default, schema has to be generated for all the tables used by the application. In case of iBank, there are five tables for which schema has to be generated. Name this schema file as myschema.dbschema. The tables used in iBank are:

ACCOUNT

ACCOUNT_TYPE

BRANCH

CUSTOMER

TRANSACTION_HISTORY

TRANSACTION_TYPE

Place this file myschema.dbschema above META-INF folder for the Entity beans.

In <ejb-name>-ias-cmp.xml: Replace all the <ejb-name>-ias-cmp.xml files in Sun ONE Application Server 6.0/6.5 with one sun-cmp-mappings.xml file. This file maps (at least one) set of beans to tables and columns in a specific db schema. Since the DTDs for this two XML files are radically different, the migrator has to actually create a new file following the steps given below:

  1. Create a new XML file which has the following DOCTYPE definition on top:

    2. <!DOCTYPE sun-cmp-mappings PUBLIC '-//Sun Microsystems, Inc.//DTD Sun ONE Application Server 7 OR Mapping //EN' 'http://www.sun.com/software/sunone/appserver/dtds/sun-cmp_mapping_1_0.dtd'>

    Save this file as “sun-cmp-mappings.xml”.

  2. The root tag of this XML file, as evident from the DOCTYPE definition, is sun-cmp-mappings. In the DTD, this element is defined as:

    3. <!ELEMENT sun-cmp-mappings ( sun-cmp-mapping+ ) >

    Element sun-cmp-mapping would be :

    <!ELEMENT sun-cmp-mapping ( schema, entity-mapping+) >

    Here element schema is the path name to the schema file.

    A cmp bean has a name, a primary table, one or more fields, zero or more relationships, and zero or more secondary tables, plus flags for consistency checking. Element entity-mapping has following elements

    <!ELEMENT entity-mapping (ejb-name, table-name, cmp-field-mapping+, cmr-field-mapping*, secondary-table*, consistency?)>

    Element ejb-name is the EJB name from standard EJB-jar DTD. Element table-name is the name of the database table. A cmp-field-mapping has a field, one or more columns that it maps to cmr-field mapping. A cmr field has a name and one or more column pairs that define the relationship. Element secondary-table is for secondary table used. In case of iBank, no secondary table is used.

    Right now, the sun-cmp-mappings.xml file with entries for Account entity bean should look like:

The above changes can be referenced in file iBankWithCMP1.1.zip provided with this guide.

Assembling Application for Deployment

Sun ONE Application server 7 primarily supports 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, extension .jar) for EJBs and web archives (WAR, extension .war) for servlets and JSPs.

So all the JSPs and Servlets should be packaged into WAR file, all EJBs into the JAR file and finally the WAR and the JAR file together with the deployment descriptors in to the EAR file. This EAR file is a deployable component.

Deploying iBank application on Sun ONE Application Server 7 using the asadmin utility

The last stage is to deploy the application on an instance of Sun ONE Application Server 7. The process for deploying an application is described below:

The Sun ONE Application Server 7 asadmin includes a help section on deployment that is accessible from the Help menu.

The command line utility asadmin can be invoked by executing asadmin.bat file in windows and asadmin file in solaris kept at Sun ONE Application Server 7 installation's bin directory. i.e., <Install_dir>/AppServer7/appserv/bin.

At asadmin prompt, the command for deployment would be:

asadmin> deploy -u username -w password -H hostname -p adminport [--type application|ejb|web|client|connector] [--contextroot contextroot] [--force=true] [--name component-name] [--upload=true] [--instance instancename] filepath

Restart the server instance and then test the application on the browser by typing the url ‘http://<machine_name>:<port_number>/IBank’. Test by giving one of the available user name and password, say username as 'jatkins' and password as 'Monday'. This should show the main menu page of the ibank application.

Migrating iBank using Sun ONE Studio for Java 4.0

The sample application we defined is called 'iBank' and simulates a basic online banking service with the following functionality:-

The major steps to be followed for migrating the iBank application would be as follows:

Creating a Web application module in Sun ONE Studio for Java

To create a Web application module in Sun ONE Studio for Java, follow the procedure below:

  1. Mount the directory containing the source files i.e, ‘Docroot’ in the Sun ONE Studio for Java “FileSystems Explorer” window by right clicking at the Filesystem and choosing option for mount.
  2. Create an empty directory, say ‘WarContent’ for the web module in the root directory structure containing the source files.
  3. Mount the newly created directory ‘WarContent’ in the Sun ONE Studio for Java “FileSystems Explorer” window by right clicking at the Filesystem and choosing option for mount.
  4. Mount the other directories containing the EJBs in the source file directory structure. i.e., ‘EntityContent’ and ‘SessionContent’.
  5. Convert the FileSystem (WarContent) into a Web Module by right clicking at the folder name and then selecting tools where there is an option for converting it into WebModule.
  6. Copy the source JSP, HTML and image files to the web application root. i.e., to the directory ‘WarContent’ from the directory ‘Docroot’.
  7. Copy servlets and auxiliary class sources to the WEB-INF/classes directory. i.e., copy the sub folder ‘com’ in the ‘Docroot’ directory to the WEB-INF/classes directory of ‘WarContent’ directory.
  8. Copy the tag library present in the WEB-INF of the ‘Docroot’ directory to the WEB-INF of ‘WarContent’ directory.
  9. Edit the source code wherever required to migrate it to Sun ONE Application Server 7 (if it has not been modified through the migration tool), by following the steps below:
    • Figure out the JSPs that have to be changed.
    • Figure out if any custom JSP tags are used in the application.
    • Open the selected JSP code in Sun ONE Studio by right clicking at the file and selecting option to open.
    • Follow the steps given in section Migrating Java Server Pages and JSP Custom Tag Libraries to modify the source.
    • Similarly migrate the servlets by following the details in section, Migrating Servlets.
  10. Assemble the application and fill in the deployment descriptor web.xml (in the WEB-INF/ directory). Click on the web.xml file and edit the properties of it, i.e, During this assembly phase, configure each servlet, JSP page and JSP tag library, as well as the EJB or data source references used in the Web application.

The following screen shots illustrate how this assembly phase is carried out using Sun ONE Studio for Java:

Configuring a Servlet

In the web module, click on web and then view the properties window.

Click at the deployment tab of the properties window of web.xml. Further click on the servlets for configuring servlets.

A property editor is displayed, click at ‘Add’ button to add new servlet.

For each servlet in the Web application, you specify the name of the servlet, the full name of its implementation class by clicking at the ‘Browse’ button, the mapping elements for the servlet by clicking at ‘Mappings’, and any initialization parameters.

Figure 2-4  Configuring Servlet

Figure shows how to configure servlets using Sun ONE Studio.

The list of servlets and their mappings in iBank application are:

Table 2-1  Servlets and Mappings

Servlet Name

Display Name

Mapping

LoginServlet

LoginServlet

/CheckLogin

CheckTransferServlet

CheckTransferServlet

/CheckTransfer

CustomerProfileServlet

CustomerProfileServlet

/CustomerProfile

DataSourceTestServlet

DataSourceTestServlet

/DataSourceTest

HelloWorldServlet

HelloWorldServlet

/HelloWorld

LookUpDataSourceTestServlet

LookUpDataSourceTestServlet

/LookUpDataSourceTest

ProjectEarningsServlet

ProjectEarningsServlet

/ProjectEarnings

ShowAccountSummaryServlet

ShowAccountSummaryServlet

/ShowAccountSummary

TestContextServlet

TestContextServlet

/TestContext

TransferFundsServlet

TransferFundsServlet

/TransferFunds

UpdateCustomerDetailsServlet

UpdateCustomerDetailsServlet

/UpdateCustomerDetails

All the above servlets have to be configured such that web.xml has entries for all of them.

Finally the ‘deployment’ tab should show 11 servlets mappings and 11 servlets.

Configuring a JSP tag library

Click on the Deployment tab of the web.xml properties window. Click at the Tag Libraries to set the Tag lib.

To define a JSP tag library in the Web application deployment descriptor, specify the URI of the library (the identifier which the JSP pages will use to access it), and the path to the library's deployment descriptor (.tld file).

In iBank, there is one JSP Tag library TMBHisto.tld. The deployment descriptor is kept in WEB-INF. Following entries have to be made.

Figure shows Sun ONE Application Server archtiecture.

Figure 2-5  Configuring Tag lib

Add Resource Reference

Click at the references tab of the web.xml Properties window. Click at the Resource Reference to add a new resource. Following screen shot shows adding a new Resource for Data source in iBank i.e., jdbc/iBank

Figure shows a dialog box to configure a JDBC resource for Sun ONE Application Server using Sun ONE Studio.

Figure 2-6  Adding Resource Reference

Click at the Sun ONE App Server tab and set the JNDI name as 'jdbc/IBank' and also set the User name and Password depending on the database schema you are using.

Figure shows a dialog box to add JDBC resource reference for Sun ONE Application Server using Sun ONE Studio.

Figure 2-7  Adding Resource Reference entry for Sun ONE Application Server

Add Context Param

Add entry for context parameter for the JNDI name to lookup iBank data source.

Following screen shot shows the entry for context param, which can be done by clicking at the context param in the Properties window at the Deployment tab of web.xml.

Figure shows a dialog box to add a Context Parameter for Sun ONE Application Server using Sun ONE Studio.

Figure 2-8  Adding Context Parameter

Specify the Welcome File

Specify the welcome file in the properties window by clicking at the Welcome Files.

In case of iBank, index.jsp is the welcome file so that has to be mentioned.

Converting CMP Entity EJBs from 1.1 to 2.0

Referring to the manual process described in section, Migrating CMP Entity EJBs, Here is an example of Account Entity bean being converted from CMP 1.1 to CMP 2.0.

The related files for Account bean are:

Account.java

AccountEJB.java

AccountHome.java

AccountPK.java

The details of the changes done are described below:

Creating an EJB module in Sun ONE Studio for Java

The procedure described below explains how to create an EJB module in Sun ONE Studio for Java, using existing source files:

Creating Module for Session Beans
  1. Directory for Session Beans 'SessionContent' has following in it.

    2. There would be bean class and interfaces for the following Session Beans:

    BankTeller

    InterestCalculater

    In addition to this, it will also contain Exception classes.

  2. Create the new EJBs from existing source files.

    3. In Sun ONE Studio for Java, it is possible to create an EJB from existing source files.

    Select mounted directory 'SessionContent', walk through the sub folders there to finally reach the package 'session', right click here and select option for new J2EE and finally click at 'Session EJB', which shows a new EJB wizard.

    After specifying the main characteristics of the EJB (i.e., session, stateful or stateless), and defining the name and package for the EJB, you match the existing source files and the different components of the EJB: implementation class, home and remote interfaces. In order to make the match with existing source files, use the "Modify" button in the dialog box and select "Select an existing source file."

    All the session beans have to be created in similar fashion.

    Following screen shot shows the creation of Session Bean BankTeller which is a Stateful Session bean. So the State specified should be Stateful whereas InterestCalculator session bean is Stateless, so while creating InterestCalculator bean, the state specified should be stateless. Click at the browse button to specify the package.


    Figure shows how to create a Session Bean using Sun ONE Studio for Sun ONE Application Server 7.

    Figure 2-9  Creation of new Session Bean

    Following screen shot (click ‘Next>’ when you are done) shows specifying the bean class, the home interface and the remote interface. Clicking on the modify button and selecting option for using existing class would show up the existing files, which can be selected.


    Figure shows how to create a Session Bean’s Bean class, Home and Remote Interface using Sun ONE Studio for Sun ONE Application Server 7.

    Figure 2-10  Specifying the Bean class, Home Interface and the Remote Interface

    Create the InterestCalculator session bean in similar fashion.

  3. Edit the properties of the EJBs

    4. By editing the properties of an EJB, you can declare the EJB Resource references; specify an EJB's environment entries.


    Figure shows the properties of a Session Bean.

    Figure 2-11  Properties window of the Session Bean BankTeller

    The following screenshot shows the declaration of an environment entry for the BankTeller session bean. InterestCalculator bean does not require this entry.

    Click at the Environment Entries in the 'References' tab and then click on Add to add new entry for the DSN.


    Figure shows a Dialog Box to add a Environment Entry for a session bean using Sun ONE Studio.

    Figure 2-12  Adding Environment Entry to BankTeller Session Bean

    At the references tab of the Properties window for BankTeller Session bean, click at the Resource Reference to add a new resource. Following screen shot shows adding a new Resource for Data source in iBank i.e., jdbc/iBank.


    Figure shows a Dialog Box to add a Resource to a session bean using Sun ONE Studio.

    Figure 2-13  Adding Resource Reference

    Click at the Sun ONE App Server tab to set the JNDI name as 'jdbc/iBank' and username and password depending on the database schema used.

    InterestCalculator bean does not require this entry.


    Figure shows a Dialog Box to add a Resource to a session bean using Sun ONE Studio.

    Figure 2-14  Adding Resource Reference for Sun ONE Application Server

    At the references tab of the Properties window, click at the Ejb Reference to addEJBreferences. Following screen shot shows adding EJB Reference for the BankTeller session bean. BankTeller session bean has references to Entity bean 'Account' and 'Customer'. So entries have to be made for both the entity beans.

    Home and Remote interfaces have to be specified by clicking at the modify button and then selecting existing source for the beans.


    Figure shows a Dialog Box to create a EJB Reference to a session bean using Sun ONE Studio.

    Figure 2-15  Adding EJB Reference

    Now click at the 'Sun ONE App Server' tab in the EJB Reference, to specify the JNDI name. Following screen shot shows the JNDI entry to be made for the Account entity bean i.e., 'ejb/Account'. Similarly whenEJBreference for 'Customer' bean is added the JNDI name specified at the Sun ONE App Server tab would be 'jndi/Customer'.


    Figure shows a Dialog Box to add a EJB Reference to Sun ONE Application Server using Sun ONE Studio.

    Figure 2-16  Adding EJB Reference entry for Sun ONE Application Server

  4. Compile the source files
  5. Create an EJB module and assemble the EJBs within it.

    6. In accordance with the J2EE 1.2 specification, in Sun ONE Application Server 7 you must group EJBs together in an EJB module. Create new EJB Module i.e., SessionModule at the root directory i.e., 'SessionContent' by right clicking the folder and selecting option for New and then selecting J2EE and then finally selecting New EJB Module. After creation add the Session EJB's into it.

    The screen shot below shows how the BankTeller and InterestCalculator EJBs are added to an EJB module SessionModule.


    Figure shows how to add a EJB to a EJB Module using Sun ONE Studio.

    Figure 2-17  Adding Session Beans to EJB Module

Creating Module for Entity Beans
  1. Directory for Entity Beans would contain following.

    2. Bean class, Remote and Home interface for the following Entity Beans:

    1. Account
    2. AccountType
    3. Branch
    4. Customer
    5. Transaction
    6. TransactionType

      7. Customer entity bean is Bean managed and others are Container managed.

  2. Configure the JDBC driver

    3. In the Runtime view of the Explorer, in Databases / Drivers / Add Driver: specify the driver name, implementation class, and the prefix of the relevant URL. The corresponding JAR or ZIP for the driver must be accessible to Sun ONE Studio for Java, and must therefore be copied into the <SUN ONE STUDIO FOR JAVA_ROOT>/lib/ext directory.

    To place the driver classes in the appropriate Sun ONE Studio for Java directory in Solaris, run the following command from the shell (sh or ksh):

    cp $ORACLE_HOME/jdbc/lib/classes12.zip <SUN ONE STUDIO FOR JAVA_ROOT>/lib/ext

  3. Define the database connection properties

    4. In the Runtime view of the Explorer, in Databases / Add Connection... indicate the driver used, the full connection URL, the user name, the related password, and lastly the appropriate database schema:


    Figure shows a Dialog Box to configure a database connection in Sun ONE Studio.

    Figure 2-18  Configuring a database connection (Oracle) in Sun ONE Studio for Java

  4. Create the new EJBs from existing source files.

    5. In Sun ONE Studio for Java, it is possible to create an EJB from existing source files. Select the mounted directory 'EntityContent', walk through the directory till you reach 'entity' sub-folder. Right click and select option for new J2EE and finally click at 'Entity EJB(CMP/BMP)', which shows a new EJB wizard.

    After specifying the main characteristics of the EJB (entity, BMP or CMP), and defining the name and package for the EJB, you match the existing source files and the different components of the EJB: implementation class, home and remote interfaces. In order to make the match with existing source files, use the "Modify" button in the dialog box and select "Select an existing source file." Entity beans require an extra step of specifying the mappings of the cmp fields with the table. In the Explorer Filesystems view, after selecting the option New CMP Entity Bean, Select option, table from Database connection in order to be able to specify the database table to be used for persistence of the EJB fields:


    Figure shows a wizard to create and configure CMP Entity bean in Sun ONE Studio.

    Figure 2-19  Creation of an Entity bean with container-managed persistence.

    The following screen enables you to select the right connection from the list of database connections defined.

    Once the connection is selected, list of tables accessible from this connection are shown, and select the appropriate table:


    Figure shows a wizard to choose and map a database table to CMP Entity bean fields in Sun ONE Studio.

    Figure 2-20  Choosing a table for mapping CMP bean fields.

    The next screen is used to configure mapping between the columns of the table selected and the CMP fields of the bean. Particular care should be taken to correctly indicate the names of the bean fields and associated Java types.


    Figure shows the mapping between database table fields and CMP Entity bean fields in Sun ONE Studio.

    Figure 2-21  Mapping between table columns and CMP fields of the bean

    The next screen shot shows, specifying the source files for the Entity Bean.


    Figure shows a wizard to specify the source files for the CMP Entity beans in Sun ONE Studio.

    Figure 2-22  Specifying the source files for the Entity Bean

    The next step involves informing Sun ONE Studio for Java that you want to create the EJB from existing source files, which can be specified by clicking at the 'Modify Class' button.

    If you get any error while pointing to the existing source files, it may have caused because you made a mistake in the previous steps or the source is not migrated properly. Such errors should be handled by making changes as and when reported.

    The next screen shot shows selecting existing source file for EJB bean class.


    Figure shows how to create a Bean class by selecting an existing Bean class.

    Figure 2-23  Specifying EJB Bean class by selecting option for Existing Source files

    The next stage involves editing the properties of the new EJB wherever required.

    All the entity beans have to be created in similar fashion.

    (Note: This might give some errors giving option to select the existing class or using another one, click on to 'using same class'. Sun ONE Studio might show some unexpected results, in such condition, exit Sun ONE Studio and then reload it again.)

  5. Edit the properties of the EJBs.

    6. Select the new EJB in the explorer window so that its properties are displayed in the properties inspector.

    In the properties window, select the References tab, click on the text zone to the right of the "Resource References" label, then on the button showing suspension points ("…") on the right hand edge of this text zone.

    Following properties have to be set for the entity bean Customer only.

    Following screen shot shows adding Resource reference for the Entity Bean Customer.

    In the "Standard" tab, give the full name of the data source ("jdbc/DataSourceName"), the resource type (javax.sql.DataSource), and select "Container" from the drop-down list of options for managing access to this resource ("Authorization").


    Figure shows how to add a resource reference to a CMP Entity Bean.

    Figure 2-24  Adding Resource Reference

    Once the declaration has been made, select the "Sun ONE App Server" tab, and specify the JNDI name of the data source "jdbc/iBank" in the JNDI Name column of the entry that corresponds to the resource reference defined previously. Also specify the username and password.


    Figure shows how to add a resource reference to Sun ONE App Server.

    Figure 2-25  Editing Resource Reference

    In the properties window select the 'Sun ONE AS' tab Click on the 'Reference Resource Mapping' and choose the data source i.e, jdbc/IBank on the server instance which has to be used. Following screen shot would dipict the same


    Figure shows the mapping of a resource reference to Sun ONE Application Server.

    Figure 2-26  Resource Reference Mapping for Sun ONE Application Server

  6. Set EJB QL for finders other than findByPrimaryKey method.

    7. EJB QL has to be specified for finders. As per the CMP 2.0 specification, the finders will use EJB QL.

    In iBank application the entity bean that would require this type of editing is Account bean. Select the AccountEJB node in the Sun ONE Studio explorer window and expand the finder methods in it. Click on any finder method other than the findByPrimaryKey to open its properties window:


    Figure shows the properties of a Finder Method.

    Figure 2-27  Properties of Finder Method

    Click at the EJBQL Query to enter the query. Following screen shot shows the query entered:


    Figure shows a Dialog box where you can edit EJB QL script..

    Figure 2-28  Editing EJB QL for the Finder

  7. Create an EJB module and assemble the EJBs within it.

    8. Create new EJB module named EntityModule and add all Entity beans into this module by right clicking on the EJB module and selecting the option to add EJB's. As per the J2EE 1.2 specification, you must group EJBs together in a EJB module.

  8. Create new Database Schema

    9. From the file menu click new and then select new Database Schema. Provide the connection information for the database from which schema has to be captured.

  9. Map the database entries for Sun ONE Application Server 7.

    10. Select a EJB node in the EJB module, right click the node to choose the properties window and select Sun ONE AS tab. Specify the database schema and primary table name for this particular entity bean. Repeat the process for other Entity Beans in the EJB Module.

    Following screen shot shows selection of primary table for the entity bean Account


    Figure shows the mapping between a Bean and the Database.

    Figure 2-29  Database Mapping

    Click on ‘Next >” for specifying the mappings for the cmp fields of bean with the table fields.

    Now select the Sun ONE Mapping Tab from the properties window and re-enter the mappings.

    Following screen shot shows mappings for the Account EJB


    Figure shows Sun ONE Application Server archtiecture.

    Figure 2-30  Properties of entity bean ‘Account’

    Similarly mappings for all the Entity beans have to be set.

    See Appendix A for the details on the mapping of particular Entity bean to corresponding database table field.

  10. Add CMP resource

    11. Select EntityModule and view its properties, click at Sun ONE AS tab, and now click at CMP Resource to configure the Persistence manager factory.

    Following screen shot shows the configuration:


    Figure shows the property editor for a CMP resource.

    Figure 2-31  Adding CMP Resource

Creating an enterprise application in Sun ONE Studio for Java

After creating the Web application and EJB files, the next step is to create an enterprise application, which groups all the modules together. The process for creating an enterprise application is as follows:

  1. Create a new enterprise application module in a new directory say 'IBank' under the same package available for the source.
  2. Add the Web module and EJB modules to the enterprise application module

    3. The following screen shots show an enterprise application called iBank, containing a Web module called WarContent and EJB module called SessionModule and EntityModule.


    Figure shows how to create a application in Sun ONE Studio and add EJB, Session and WEB modules to the application.

    Figure 2-32  Adding Modules to the Application

    Following screen shot shows Application iBank having 3 modules in it.


    Figure shows the iBank application file system having different modules.

    Figure 2-33  File System showing Application ‘iBank’ having different modules

  3. Edit the enterprise application properties.

    4. The property editor allows you to set the different properties of the enterprise application module. In particular, this is where the root context name is defined for the Web module of the enterprise application:


    Figure shows how to specify the Web Context.

    Figure 2-34  Specifying the Web Context

  4. Export EAR file.

    5. Export EAR file by right clicking the Enterprise application and selecting option for exporting EAR file. This EAR file would contain JAR files, WAR file and XML files. This EAR file has all the Sun ONE specific XML files required for the deployment on Sun ONE Application Server 7. This EAR file can now be deployed.

Deploying an application in Sun ONE Application Server 7

The last stage is to deploy the application on an instance of Sun ONE Application Server 7. The process for deploying an application is described below:

  1. Deploying an application on Sun ONE server 7 instance from Sun ONE Studio for Java

    2. Right click on the EAR file and select option ‘Deploy’. This would deploy the application on the default server instance. Restart the server instance and then test the application.

  2. Deploying an application on an Sun ONE Application Server 7 instance using Sun ONE Application Server 7 asadmin utility

    3. An alternative to using Sun ONE Studio for Java to deploy enterprise applications on an Sun ONE server instance is to use the Sun ONE Application Server 7 asadmin utility, after creating and exporting the application EAR archive from Sun ONE Studio for Java.

    For instructions on deploying the iBank application using the asadmin deployment utility, please refer to Deploying iBank application on Sun ONE Application Server 7 using the asadmin utility section under Manual Migration of iBank Application topic.

Migration from BEA WebLogic Server v6.1 and IBM WebSphere v4.0

The detailed J2EE application migration process and the sample application migration for BEA WebLogic v6.1 and IBM WebSphere v4.0 is part of another guide which can be found at the Migration Site.



Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.