|
| Sun ONE Application Server 7 Migrating and Redeploying Server Applications Guide |
Migration Considerations and StrategiesThis module 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
- Migration Issues From Sun ONE Application Server 6.x to 7
- Migrating Example: iBank
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.
Sun ONE Application Server 6.0/6.5 ArchitectureAs 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:
- 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 presented in detail in Module A - iBank Application Specification.
The following migration processes are described:
- Migrating JDBC Code
- Migrating Servlets
- Migrating Java Server Pages and JSP Custom Tag Libraries
- Obtaining a Data Source from the JNDI Context
- EJB Migration
- EJB Changes Specific to Sun ONE Application Server 7
- Migrating Web Applications
- Migrating Enterprise EJB Modules
- Migrating Enterprise Applications
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 Data Source 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
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:
- Place the archive (JAR or ZIP) for the driver implementation in the /lib directory of the Sun ONE Application Server 7 installation directory.
- Modify the CLASSPATH by setting the path for the driver through the GUI of the admin server. Click the server instance "server1" and then click the tab "JVM Settings" from the right pane. Now click the option Path Settings and add the path in the classpath suffix text entry box. Once you make the changes, click "Save" and then apply the new settings. Restart the server to modify the configuration file, server.xml.
The figure "Using the JVM Settings to Set the Classpath Suffix" shows adding the path of the driver in the classpath suffix through GUI.
Using the JVM Settings to Set the Classpath SuffixUsing 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:
asadmin>create-jdbc-connection-pool -u username -w password -H hostname -p adminport [-s] [--instance instancename] --datasourceclassname classname [--steadypoolsize=8] [--maxpoolsize=32] [--maxwait=60000] [--poolresize=2] [--idletimeout=300] [--isconnectvalidatereq=false] [--validationmethod=auto-commit] [--validationtable tablename] [--failconnection=false] [--description text] [--property (name=value)[:name=value]*] connectionpoolid
For example:
asadmin>create-jdbc-connection-pool -u admin -w password -H cl1 -p 4848 -instance server1 --datasourceclassname oracle.jdbc.pool.OracleConnectionPoolDataSource --property (user-name=ibank_user):(password=ibank_user) oraclepool
Here JDBC connection pool `oraclepool' for oracle database is created using database schema having the username `ibank_user' and password `ibank_user'.
The syntax to create a JDBC resource is as follows:
asadmin>create-jdbc-resource -u username -w password -H hostname -p adminport [-s] [--instance instancename] --connectionpoolid id [--enabled=true] [--description text] [--property (name=value)[:name=value]*] jndiname
For example:
asadmin>create-jdbc-resource -u admin -w password -H cl1 -p 4848 --instance server1 --connectionpoolid oraclepool jdbc/IBANK
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.
- Register the data source classname
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.
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.
- 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.
Configuring Connection Pool through GUISimilarly 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:
- Obtain an initial JNDI context
- Obtain a reference to the data source by using a JNDI lookup
- Obtain a connection using this referen
- Obtaining 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), should be simply, as follows:
InitialContext ctx = new InitialContext();
- Obtaining 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 should then be cast as a DataSource type object:
ds = (DataSource)ctx.lookup(JndiDataSourceName);
- Obtaining the connection
This operation is very simple, and requires the following line of code:
conn = ds.getConnection();
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
- JSP 1.2 is based on Servlet 2.3 and Java 2. JSP 1.2 applications will not run on platforms that only support JDK 1.1. JSP 1.2 is backward compatible with JSP 1.1, so JSP 1.1 application should run without any tweaking in a JSP 1.2 complaint container.
- The definition of XML syntax for a JSP page has been finalized. So a JSP 1.2 complaint container must accept files in both JSP 1.1 format and the new XML format called as JSP Document.
- Tag libraries can make use of Servlet 2.3 event listeners.
- A new type of validation has been added, for the tag libraries, which validates JSP pages.
- New options for tag library distribution and deployment have been added.
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:
- Servlets now require JDK 1.2 or later
- A filter mechanism has been created
- Application lifecycle events have been added
- New internationalization support has been added
- New error and security attributes have been added
- The HttpUtils class has been deprecated
- Several DTD behaviors have been expanded and clarified
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 Module 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:
- 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 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:
- The <!DOCTYPE definition should be modified to point to the latest DTD url in case of J2EE standard DDs, like ejb-jar.xml.
- Replace the ias-ejb-jar.xml with modified version of this file, named sun-ejb-jar.xml created manually according to the DDs. See url
<!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'>
for details.
- In sun-ejb-jar.xml, the JNDI name for all the EJB's, should prepend `ejb/' in all the JNDI names. This is required as in Sun ONE Application Server 6.5, the JNDI name of the EJB could only be "ejb/<ejb-name>" where <ejb-name> is the name of the EJB as declared inside ejb-jar.xml. In Sun ONE Application Server 7 this has changed as a new tag has been introduced in sun-ejb-jar.xml inside which the JNDI name of the EJB can be declared. Because of this flexibility provided by Sun ONE Application Server 7 we advice that the JNDI name of the EJB should be declared as "ejb/<ejb-name>" inside the <jndi-name> tag to avoid changing JNDI names throughout the application.
Entity Beans:
- The <!DOCTYPE definition should be modified to point to the latest DTD url in case of J2EE standard DDs, like ejb-jar.xml.
- Insert <cmp-version> tag with value 1.1 for all CMPs in ejb-jar.xml.
- Replace all the <ejb-name>-ias-cmp.xml files with one sun-cmp-mappings.xml file, which is created manually. See url
<!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'>
for details.
- Generate dbschema by using the capture-schema utility in the Sun ONE Application Server 7 installation's bin directory and place it above META-INF folder for the Entity beans.
- ias-ejb-jar.xml should be replaced with its new version named sun-ejb.jar.xml in Sun ONE Application Server 7.
- In Sun ONE Application Server 6.5, the finders sql was directly embedded inside the <ejb-name>-ias-cmp.xml, in Sun ONE Application Server 7 this has changed such that now mathematical expressions are used to declare the <query-filter> for the various finder methods.
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:
- a root directory containing the HTML pages, JSP pages, 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:
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.
- web.xml
Sun ONE Application Server 7 adheres to J2EE 1.3 standards, according to which, the web.xml file inside a WAR should adhere to the revised DTD available at http://java.sun.com/dtd/web-app_2_3.dtd. This DTD fortunately, is a superset of the previous versions' DTD, hence only the <! DOCTYPE definition needs to be changed inside the web.xml, which is to be migrated. The modified <! DOCTYPE declaration should look like:
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
- ias-web.xml
In Sun ONE Application Server 7 the name of this file is changed to sun-web.xml.
This XML file is required to declare the Sun ONE Application Server 7 specific properties/resources that will be required by the web application.
Note: See the next section for some important inclusions to this file.
If the ias-web.xml of the Sun ONE Application Server 6.5 application is present and does declare Sun ONE Application Server 6.5 specific properties, then this file needs to be migrated to Sun ONE Application Server 7 standards. The file name has to be changed to sun-web.xml and other details are available at
<!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'>
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:
asadmin> deploy -u username -w password -H hostname -p adminport --type web [--contextroot contextroot] [--force=true] [--name component-name] [--upload=true] [--instance instancename] filepath
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:
- Stateful or Stateless Session Beans.
- Entity beans with bean managed persistence (BMP), or container managed persistence (CMP).
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:
- 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.
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:
- 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.
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:
- The <!DOCTYPE definition should be modified to point to the latest DTD url in case of J2EE standard DDs, like ejb-jar.xml.
- Replace the ias-ejb-jar.xml with modified version of this file, i.e., sun-ejb-jar.xml created manually according to the DTDs. See url
<!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'>
- Replace all the <ejb-name>-ias-cmp.xml files with one sun-cmp-mappings.xml file, which is created manually. See url
<!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'>
- Only for CMP entity beans: Generate dbschema by using the capture-schema utility in the Sun ONE Application Server 7 installation's bin directory and place it above META-INF folder for the Entity beans.
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, 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:
- 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.
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:
- With Sun ONE Application Server 6.0 or 6.5, which is always used jointly with a Web front-end, the access URL for the application will take the following form (assuming the Web server is configured on the standard HTTP port, 80):
http://hostname/NASApp/AppName/
- With Sun ONE Application Server 7, the URL will take the form:
http://hostname:port/AppName/
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:
- 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 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:
- 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 presented in detail in Module 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:
- Create a new XML file which has the following DOCTYPE definition on top:
<!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".
- The root tag of this XML file, as evident from the DOCTYPE definition, is sun-web. In the DTD, this element is defined as
<!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>
- For declaring any resource references, the element declaration would be:
<!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)>
In case of ibank, resource reference details, sun-web.xml would be:
<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>
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:
- Create a new XML file which has the following DOCTYPE definition on top:
<!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.
- 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
<!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.
- The enterprise-beans element is defined in the DTD as
<!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>
- 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.
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>
- The ejb element would contain element pass-by-reference <!ELEMENT pass-by-reference (#PCData).
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.
- The ejb element would also have element bean-cache.
<!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>
- The element used only for Stateless session bean and message-driven bean pools is bean-pool.
<!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:
- Create a new XML file which has the following DOCTYPE definition on top:
<!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.
- 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
<!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.
- The enterprise-beans element is defined in the DTD as
<!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>
- The ejb element would contain element pass-by-reference <!ELEMENT pass-by-reference (#PCData).
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.
- 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.
<!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.
- The <!ELEMENT commit-option (#PCDATA)> specifies option for committing.
- The ejb element would also have an element bean-cache.
<!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>
- In <!ELEMENT enterprise-beans (name?, unique-id?, ejb*, pm-descriptors?, cmp-resource?)>
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:
- Create a new XML file which has the following DOCTYPE definition on top:
<!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".
- 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:
<!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:
<sun-cmp-mapping>
<schema>mySchema</schema>
<entity-mapping>
<ejb-name>Account</ejb-name>
<table-name>ACCOUNT</table-name>
<cmp-field-mapping>
<field-name>custNo</field-name>
<column-name>CUST_NO</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>branchCode</field-name>
<column-name>BRANCH_CODE</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>accTypeId</field-name>
<column-name>ACCTYPE_ID</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>accNo</field-name>
<column-name>ACC_NO</column-name>
</cmp-field-mapping>
<cmp-field-mapping>
<field-name>accBalance</field-name>
<column-name>ACC_BALANCE</column-name>
</cmp-field-mapping>
</entity-mapping>
</sun-cmp-mapping>
NOTE: We have not included the header part of the document, namely the XML declaration and DOCTYPE definition, here for brevity.
Entries for all the CMP entity beans have to be made.
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:-
- log on to the online banking service
- view/edit personal details and branch details
- summary view of accounts showing cleared balances
- facility to drill down by account to view individual transaction history
- money transfer service, allowing online transfer of funds between accounts
- compound interest earnings projection over a number of years for a given principal and annual yield rate.
The major steps to be followed for migrating the iBank application would be as follows:
- The first and the foremost requirement of this migration is to install Sun ONE Application Server 7 and Sun ONE Studio.
- Extract the application, which is in a zip format in a local directory.
The source for the iBank application (iBank65.zip) can be found at the migration site http://www.sun.com/migration/sunonetools.html. Unzipping the file "iBank65.zip" would create following directory structure:
It would have 4 sub directories `Docroot', `SessionContent', `EntityContent' and `Scripts'.
`Docroot' would contain Html, Jsp's and Image files in its root. It would also contain the source files for servlets, EJBs, etc in the sub-folder WEB-INF\classes following the package structure com.sun.bank.*. War file would be generated through the contents of this directory.
`SessionContent' would contain the source code for Session beans following the package structure com.sun.bank.ejb.session. This directory would form the EJB module for session beans.
`EntityContent' would contain the Entity beans following the package structure com.sun.bank.ejb.entity. This directory would form the EJB module for Entity beans.
`Scripts' contain the sql scripts for the database setup.
- Setup the schema for iBank application by executing the sql scripts provided in the `Scripts' folder. These scripts are for oracle database. These scripts would create user, create tables and insert data into the tables. Execute the scripts in the following order
Manual migration would involve following steps:
These steps have to be carried out manually and is explained as and when required in the following sections. If migration tool is used as an option, it has to be carried out at this point itself. If manual approach is followed then changes have to be done as and when specified in following sections.
- Prepare Sun ONE Studio for assembling and deploying sample application `iBank'
Sun ONE Studio can be invoked through the runide.exe file (runide.sh in case of Solaris) kept in the <Sun ONE App Server ROOT>/<AppServ>/<SUN ONE STUDIO FOR JAVA_ROOT>/bin directory.
(Note: Sun ONE Application Server 7 should be up and running before following the steps below)
Choose Sun ONE Application Server.
Setup admin server by right clicking at the Sun ONE Application Server and then selecting `Add Admin Server'
Enter details for host (local machine name), port number (by default its 4848), username and password.
Once the admin server is setup, click on it to get the server instance installed.
Set the server instance as default server by right clicking on the server instance and selecting option for setting it as default.
- Create web module by following the instructions given in "Creating a Web application module in Sun ONE Studio for Java".
- Migrate EJBs manually if migration tool is not used as an option for migrating the application. Follow the section on "EJB Migration", for the manual migration. This step can be carried out by opening the source code for the EJB's in Sun ONE Studio and modifying it.
- Migrate the JDBC code if migration tool is not used as an option to migrate the application by following the section on "Migrating JDBC Code".
- iBank application has Entity Beans with CMP 1.1, so they have to be converted to CMP 2.0 by following the manual procedure explained in the section on "Migrating CMP Entity EJBs" if the application is not migrated using the tool.
If application is migrated through the tool, all the entity beans are migrated except one, i.e., `Account' entity bean as it has Enumeration used in its code. The code for this has to be changed manually following the instructions given in section, "Migrating CMP Entity EJBs". Refer section, "Converting CMP Entity EJBs from 1.1 to 2.0" for an example of changes to be carried out for converting CMPs from 1.1 to 2.0.
- Create separate EJB modules for the Entity Beans and the Session Beans by following the instructions given in section, "Creating an EJB module in Sun ONE Studio for Java".
- Create Enterprise application by following the instructions given in section, "Creating an enterprise application in Sun ONE Studio for Java", which would include the web module as well as the EJB modules. The final output of this step would be .ear file, which can be deployed.
- Deploy .ear file on Sun ONE Application server 7 by following the instructions given in section, "Deploying an application in Sun ONE Application Server 7".
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:
- 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.
- Create an empty directory, say `WarContent' for the web module in the root directory structure containing the source files.
- 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.
- Mount the other directories containing the EJBs in the source file directory structure. i.e., `EntityContent' and `SessionContent'.
- 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.
- Copy the source JSP, HTML and image files to the web application root. i.e., to the directory `WarContent' from the directory `Docroot'.
- 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.
- Copy the tag library present in the WEB-INF of the `Docroot' directory to the WEB-INF of `WarContent' directory.
- 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".
- 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.
Configuring Servlet
The list of servlets and their mappings in iBank application are:
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.
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
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.
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.
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:
- Account.java:
There are no major changes in the code except for commenting out the setters for the primary key. The other setters are kept as it is.
Following is the code before modification:
public String getBranchCode()
throws RemoteException;
public void setBranchCode(String branchCode)
throws RemoteException;
public String getAccNo()
throws RemoteException;
public void setAccNo(String accNo)
throws RemoteException;
------
------
-----other getters and setters----
After commenting the setters for the primary keys, i.e., branchCode and accNo, the same code would be:
public String getBranchCode()
throws RemoteException;
/* public void setBranchCode(String branchCode)
throws RemoteException; */
public String getAccNo()
throws RemoteException;
/* public void setAccNo(String accNo)
throws RemoteException; */
------
------
-----other getters and setters----
- AccountEJB.java :
The changes incorporated in the bean class are as follows:
Prepend the bean class declaration with the key word abstract.
Before modification:
public class AccountEJB implements EntityBean
{
--
--
}
After modification:
public abstract class AccountEJB implements EntityBean
{
--
--
}
Comment all the cmp fields and Prefix the accessor methods with the keyword abstract, thus the line of code in the methods would be commented and postfix the methods with a semicolon. Thus replace the given code below Before modification with the code given below After modification.
Before modification:
public String branchCode;
public String accNo;
public int custNo;
public String accTypeId;
public double accBalance;
public String accTypeDesc;
public double accTypeInterestRate;
private EntityContext context;
public String getBranchCode() {
return(branchCode);
}
public void setBranchCode(String branchCode) {
this.branchCode = branchCode;
}
public String getAccNo() {
return(accNo);
}
public void setAccNo(String accNo) {
this.accNo = accNo;
}
public int getCustNo() {
return(custNo);
}
public void setCustNo(int custNo) {
this.custNo = custNo;
}
public String getAccTypeId() {
return(accTypeId);
}
public void setAccTypeId(String accTypeId) {
this.accTypeId = accTypeId;
}
public BigDecimal getAccBalance() {
return new BigDecimal(accBalance);
}
public void setAccBalance(BigDecimal accBalance) {
this.accBalance = accBalance.doubleValue();
}
After modification:
private EntityContext context;
public abstract void setBranchCode(String branchCode);
public abstract String getBranchCode();
public abstract void setAccNo(String accNo);
public abstract String getAccNo();
public abstract void setCustNo(int custNo);
public abstract int getCustNo();
public abstract void setAccTypeId(String accTypeId);
public abstract String getAccTypeId();
public abstract void setAccBalance(BigDecimal accBalance);
public abstract BigDecimal getAccBalance();
Read up all the ejbCreate() method bodies (there could be more than one ejbCreate). Look for the pattern '<cmp-field>=some value or local variable', and replace it with the expression 'abstract mutator method name(same value or local variable)'. Hence the code changes would be:
Before modification :
public void setEntityContext(EntityContext ec) {
context = ec;
}
public void unsetEntityContext() {
this.context = null;
}
public void ejbActivate() {
this.branchCode = ((com.sun.bank.ejb.entity.AccountPK)
context.getPrimaryKey()).branchCode;
this.accNo = ((com.sun.bank.ejb.entity.AccountPK)
context.getPrimaryKey()).accNo;
}
public void ejbPassivate() {
}
public void ejbLoad() {
}
public void ejbStore() {
}
public AccountPK ejbCreate(String branchCode,
String accNo, int custNo, String accTypeId,
BigDecimal accBalance) {
this.branchCode = branchCode;
this.accNo = accNo;
this.custNo = custNo;
this.accTypeId = accTypeId;
this.accBalance = accBalance.doubleValue();
return null;
}
public void ejbPostCreate(String branchCode,
String accNo, int custNo, String accTypeId,
BigDecimal accBalance) {
}
public void ejbRemove() {
}
After modification:
public void setEntityContext(EntityContext ec) {
context = ec;
}
public void unsetEntityContext() {
this.context = null;
}
public void ejbActivate() {
}
public void ejbPassivate() {
}
public void ejbLoad() {
}
public void ejbStore() {
}
public AccountPK ejbCreate(String branchCode,
String accNo, int custNo, String accTypeId,
BigDecimal accBalance) {
setBranchCode(branchCode);
setAccNo(accNo);
setCustNo(custNo);
setAccTypeId(accTypeId);
setAccBalance(accBalance);
return null;
}
public void ejbPostCreate(String branchCode,
String accNo, int custNo, String accTypeId,
BigDecimal accBalance) {
}
public void ejbRemove() {
}
- AccountPK.java
No changes required in this file.
- AccountHome.java
In the home interface of the bean, changes are required to be made only if the return type of any finder methods is of type java.util.Enumeration.In case of Account bean, the home interface has a finder findOrderedAccountsForCustomer which has a return type as Enumeration. In such cases, the return type has to be changed to Collection and also the code affected by this change, i.e, the code in the session bean which uses this finder method has to be changed such that it has provision to accept the result of this finder method in a Collection.
The changes done in the home interface is shown below:
Before Modification:
public interface AccountHome extends EJBHome
{
public Account findByPrimaryKey(AccountPK key)
throws FinderException, RemoteException;
public Enumeration findOrderedAccountsForCustomer(int custNo)
throws FinderException, RemoteException;
}
After Modification:
public interface AccountHome extends EJBHome
{
public Account findByPrimaryKey(AccountPK key)
throws FinderException, RemoteException;
public Collection findOrderedAccountsForCustomer(int custNo)
throws FinderException, RemoteException;
}
Due to the above changes, Session bean BankTeller which accesses this finder method also needs to incorporate changes to accept the result of the finder method in a Collection.
Following code snippet shows the changes made to the BankTellerEJB.java
Consider method getAccountSummary which uses finder method findOrderedAccountsForCustomer
Before modification:
public AccountSummary getAccountSummary()
throws EJBException
{
int custNo = 0;
Enumeration accEnum = null;
AccountSummary accSum = new AccountSummary();
-----
----
try
{
AccountHome home=(AccountHome) PortableRemoteObject.
narrow(accHomeHandle.getEJBHome(), AccountHome.class);
AccountTypeHome accTypeHome = (AccountTypeHome)
PortableRemoteObject.narrow(accTypeHomeHandle.getEJBHome(),
AccountTypeHome.class);
accEnum = (Enumeration) home.
findOrderedAccountsForCustomer(this.custNo);
AccountTypePK accTypePK = new AccountTypePK();
Account accRef = null;
AccountType accTypeRef = null;
String accTypeDesc = null;
int i = 0;
while(accEnum.hasMoreElements())
{
i++;
accRef = (Account) accEnum.nextElement();
accTypePK.accTypeId = accRef.getAccTypeId();
accTypeRef = (AccountType) PortableRemoteObject.
narrow(accTypeHome.findByPrimaryKey(accTypePK),
AccountType.class);
accTypeDesc = accTypeRef.getAccTypeDesc();
accSum.addElement(
accRef.getBranchCode(),
accRef.getAccNo(),
accRef.getAccBalance(),
accTypeDesc
);
}
}
-----
----
}
After Modification:
public AccountSummary getAccountSummary()
throws EJBException
{
int custNo = 0;
//Enumeration accEnum = null;
Collection accEnum = null;
AccountSummary accSum = new AccountSummary();
---
---
try
{
AccountHome home = (AccountHome) PortableRemoteObject.
narrow(accHomeHandle.getEJBHome(), AccountHome.class);
AccountTypeHome accTypeHome = (AccountTypeHome)
PortableRemoteObject.narrow(accTypeHomeHandle.
GetEJBHome(), AccountTypeHome.class);
// accEnum = (Enumeration) home.
// findOrderedAccountsForCustomer(this.custNo);
accEnum = (Collection) home.
findOrderedAccountsForCustomer(this.custNo);
AccountTypePK accTypePK = new AccountTypePK();
Account accRef = null;
AccountType accTypeRef = null;
String accTypeDesc = null;
int i = 0;
Iterator iterator = accEnum.iterator();
// while(accEnum.hasMoreElements())
while(iterator.hasNext())
{
i++;
// accRef = (Account) accEnum.nextElement();
accRef = (Account) PortableRemoteObject.
narrow(iterator.next(), Account.class);
accTypePK.accTypeId = accRef.getAccTypeId();
accTypeRef = (AccountType) PortableRemoteObject.
narrow(accTypeHome.findByPrimaryKey(accTypePK),
AccountType.class);
accTypeDesc = accTypeRef.getAccTypeDesc();
accSum.addElement(
accRef.getBranchCode(),
accRef.getAccNo(),
accRef.getAccBalance(),
accTypeDesc
);
}
}
----
----
}
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
- Directory for Session Beans 'SessionContent' has following in it.
There would be bean class and interfaces for the following Session Beans:
BankTeller
InterestCalculater
In addition to this, it will also contain Exception classes.
- Create the new EJBs from existing source files.
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.
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.
Specifying the Bean class, Home Interface and the Remote Interface
Create the InterestCalculator session bean in similar fashion.
- Edit the properties of the EJBs
By editing the properties of an EJB, you can declare the EJB Resource references; specify an EJB's environment entries.
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.
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.
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.
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.
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'.
Adding EJB Reference entry for Sun ONE Application Server
- Compile the source files
- Create an EJB module and assemble the EJBs within it.
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.
Adding Session Beans to EJB Module
Creating Module for Entity Beans
- Directory for Entity Beans would contain following.
Bean class, Remote and Home interface for the following Entity Beans:
Customer entity bean is Bean managed and others are Container managed.
- Configure the JDBC driver
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
- Define the database connection properties
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:
Configuring a database connection (Oracle) in Sun ONE Studio for Java
- Create the new EJBs from existing source files.
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:
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:
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.
Mapping between table columns and CMP fields of the bean
The next screen shot shows, specifying the source files for the Entity Bean.
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.
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.)
- Edit the properties of the EJBs.
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").
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.
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
Resource Reference Mapping for Sun ONE Application Server
- Set EJB QL for finders other than findByPrimaryKey method.
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:
Properties of Finder Method
Click at the EJBQL Query to enter the query. Following screen shot shows the query entered:
Editing EJB QL for the Finder
- Create an EJB module and assemble the EJBs within it.
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.
- Create new Database Schema
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.
- Map the database entries for Sun ONE Application Server 7.
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
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
Properties of entity bean `Account'
Similarly mappings for all the Entity beans have to be set.
See Module A for the details on the mapping of particular Entity bean to corresponding database table field.
- Add CMP resource
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:
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:
- Create a new enterprise application module in a new directory say 'IBank' under the same package available for the source.
- Add the Web module and EJB modules to the enterprise application module
The following screen shots show an enterprise application called iBank, containing a Web module called WarContent and EJB module called SessionModule and EntityModule.
Adding Modules to the Application
Following screen shot shows Application iBank having 3 modules in it.
File System showing Application `iBank' having different modules
- Edit the enterprise application properties.
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:
Specifying the Web Context
- Export EAR file.
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:
- Deploying an application on Sun ONE server 7 instance from Sun ONE Studio for Java
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.
- Deploying an application on an Sun ONE Application Server 7 instance using Sun ONE Application Server 7 asadmin utility
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.