This tutorial walks through the steps by which a sample EJB application deployed on WebLogic Server 5.1 migrates and is deployed on WebLogic Server 6.0.
Prerequisites for the migration tutorial
Description of sample application
The main steps of the migration are:
Deploying the banking application on WebLogic Server 5.1Set up the file structure, configure the server, build the application, and run the application.
Migrating the banking application to WebLogic Server 6.0Use the conversion tool, set environment variables, copy application files to new domain, and create the web.xml file.
Improving performanceRecompile EJB with WebLogic 6.0, recompile server classes, and deploy the application as an .ear package.
Prerequisites for the migration tutorialDescription of sample application
The sample application is a banking application that shows, incidentally to the purposes of this tutorial, how EJB, JSP, servlet, RMI, and ACL security work together. The application focuses largely on the container managed Account EJB.
A process flow for the sample application follows:
1. From the login.html page, the user specifies an account by entering an account number.2. The BankAppServlet handles the request by looking up the account. If the account is found, the BankAppServlet passes the Account remote stub to AccountDetail.jsp.
3. AccountDetail.jsp displays the account data. The user can alter the account by depositing or withdrawing money.
4. Control is sent back to BankAppServlet, which handles the request by interacting with the EJB to record and validate the deposit or withdrawal.
5. RMI Logging logs the processing in the BankAppServlet. This is in addition to the Account EJB logging.
6. Exceptions are redirected to the Error.jsp.
[PLACEHOLDER DOCUMENT REQUIRING UPDATES--TO BE CONVERTED INTO "BANKING APPLICATION ARCHITECTURE"]]
The purpose of this example is to demonstrate how different technologies work together in WebLogic 5.1. In the future, this example will be migrated to WebLogic 6.0, and its process of migration will be documented in a tutorial.
In deciding what type of application that customers are familiar with and can easily understand, we choose to design a bank account example. The bank account example will built around an already existing example EJB, the container managed AccountBean EJB.
The bank account example will utilize these technology: servlet, JSP, RMI startup class, security, and EJB. The example will follow the Model-View-Controller design pattern. The model will be the Account EJB. The view will be the JSP that will display information about a banking account. And the controller will be the BankAppServlet that handles all requests from the view.
The startup class will be an RMI class, RMILoggerImpl, that will be available via the RMI registry. Logging will be performed by making remote calls to this class.
For security, an Acl (access control list) will guard the BankAppServlet.
Access to the bank account example can be done via a browser or a Java client. When you access the example from a browser, you will attempt to access the BankAppServlet via the following address, http://localhost:7001/BankAppServlet. The Java client will be the same examples.ejb.basic.containerManaged.Client in the examples.ejb.basic.containerManaged package.
The AccountBean EJB can be found in the examples.ejb.basic.containerManaged package. http://www.weblogic.com/docs51/examples/ejb/basic/containerManaged/index.html. The home interface will have one additional method to return all accounts, findAllAccounts.
public Enumeration findAllAccounts()
throws FinderException, RemoteException;
The weblogic-cmp-rdbms-jar.xml file will have a corresponding finder-query stanza for this new method. It's search criteria will be an empty WLQL string to return all the EJBs in the table.
The BankAppServlet will make the life-cycle method calls on the AccountBean Home interface. Calling findAllAccounts on the Home interface will return an enumeration of Account EJBs back. This enumeration will then be mapped to a vector of Java objects, AccountListVector, and set on the HttpSession. Control will then be redirected to AccountList.JSP.
If a request to either deposit or withdraw is received, the BankAppServlet will call the corresponding methods on the remote interface to perform the necessary transaction.
AccountList.JSP will extract the AccountListVector from the HttpSession. It will build a table of Accounts, one row for each item from the AccountListVector. There will be 3 columns: account id, accounty type, and balance. There will a form field to enter a value for depositing or withdrawing. A deposit or a withdraw click will call the BankAppServlet to handle that request.
The LoggerImpl will be registered as a startup class in weblogic.properties. Its remote interface should be accessible via the JNDI tree. The log method in AccountBean will be replaced by a call to the Logger interface ancomd passing in the message to log rather than to output to the console. The Logger will be responsible for outputting to the console or a file.
Security will be provided by Acls (Access Control Lists). Inserting a line in weblogic.properties will protect BankAppServlet.
weblogic.allow.execute.weblogic.servlet.BankAppServlet=system
Deploying the banking application on WebLogic Server 5.1To deploy the banking application on WebLogic Server 5.1, use the following steps.
Build the sample applicationConfigure the server
Run the application
Build the sample application
To build the application, first set up your development shell as described in Setting up your environment.
1. Create an installation directory for the sample application, "migrationserver," under your WebLogic 5.1 root directory.2. In the "migrationserver"directory, create the following subdirectories: "clientclasses," "public_html\images," "serverclasses," and "servletclasses."
3. Copy Account.html and all of the .jsp files in the sample application package to the migrationserver\public_html subdirectory.
4. In a command console, navigate to the sample application's directory and run the build script.
Note: The sample application includes separate build scripts for Windows NT and UNIX:
build.cmd for Windows NT
build.sh for UNIX
These scripts will build the example application and place its files in the correct locations in your WebLogic Server distribution:
Servlet files: in /myserver/servletclasses
Server files: in /myserver/serverclasses
EJBean: in /myserver/app_banking.jar
Configure the server
Configure the WebLogic 5.1 server to run the sample application using the following steps.
Add users to the user pool using an ACL
Set the database persistenceEach instance of an EJBean is written to a row in a table (ejbAccounts), which must be created and exist in the database before the example is run. This table has already been created in the Cloudbase "demo" database.
You'll need to uncomment the following line from weblogic.properties:
# Add a TXDataSource for the connection pool:weblogic.jdbc.TXDataSource.weblogic.jdbc.jts.demoPool=demoPool
Set up a connection pool
Set up a connection pool in the weblogic.properties file. For your convenience, a template is included in the file; search for "weblogic.jdbc.connectionPool.demoPool", and uncomment and edit the appropriate lines:
# You can use this connection pool with any of the EJBean examples.# Uncomment to use:
weblogic.jdbc.connectionPool.demoPool=\
url=jdbc:cloudscape:demo,\
driver=COM.cloudscape.core.JDBCDriver,\
initialCapacity=1,\
maxCapacity=2,\
capacityIncrement=1,\
props=user=none;password=none;server=none
NOTE: For databases other than Cloudscape, you would need to set an appropriate url and driver, such as the following for Oracle:
url=jdbc:weblogic:oracle,\
driver=weblogic.jdbc.oci.Driver,\
Add users to the user pool using an ACL
To add an access control list (ACL) for users of the pool, edit the weblogic.properties file by uncommented as follows:
#Add an ACL for the connection pool:weblogic.allow.reserve.weblogic.jdbc.connectionPool.demoPool=everyone
If you need more information about how to use connection pools, read Using WebLogic JDBC: Using connection pools.
Deploy the EJBeanTo deploy the EJBean, add the path to the .jar file to the "weblogic.ejb.deploy" property by uncommenting the line in the weblogic.properties that begins with "weblogic.ejb.deploy." You'll need to adjust the property if the location of the files differs from the installed location. In this case, we'll be deploying the app_banking.jar.
Note: If you're running under the Microsoft SDK for Java, you'll also need to add the path to the .jar to the CLASSPATH for your WebLogic Server.Register the banking servlet
Register the Banking Servlet by uncommenting the following line in the weblogic.properties file:
weblogic.httpd.register.banking=examples.apps.banking.BankAppServletFor more help with registering servlets, see the WebLogic Administrators Guide document, Setting WebLogic properties.
Register RMILoggerImplRegister RMILoggerImpl as a startup class by uncommenting the following line in the weblogic.properties:
weblogic.system.startupClass.rmilogger=examples.apps.banking.RMILoggerImplRun the application
To run the banking application, you'll need to
Start the WebLogic 5.1 ServerIf you're starting the Server from the command line, you'll need to add an entry such as c:/weblogic/eval/cloudscape/lib/cloudscape.jar to the Java system classpath before starting the server, as described in the Administrators Guide Setting up and starting the WebLogic Server.
You can check that the EJBean has been deployed correctly either by checking the server command line window, or by opening the Console and examining "EJB" under the "Distributed objects"; you should see beanManaged.AccountHome deployed, and can monitor its activity.
Start the banking applicationUse a web browser to load the following URL:
http://localhost:7001/AccountLogin.htmlMigrating the banking application to WebLogic Server 6.0
Some of the tasks involved in migrating the application are performed by a conversion utility. This section shows how to use the conversion utility, and then describes the migration tasks that have not been automated. Main steps in the migration are:
Install WebLogic Server 6.0 (see Installation Guide for WebLogic Server 6.0)
Specify files to be converted by the conversion utility
View results of conversion utility
Set the environment variables for the new domain
Copy the application, graphics and class files to the new domain
Create the web.xml file for the application
Run the application on WebLogic Server 6.0
Start the Examples server1. Open a command console by navigating to to \bea\wlserver6.0sp1\config\examples and entering the command:
startexamplesserver
2. In a web browser, navigate to
http://localhost:7001/console/
Access the conversion utility
When you have opened the console, click the Convert weblogic.properties link under the Getting Started heading to navigate to the conversion tool interface.
[illustration of conversion tool interface TK]
Specify files to be converted by the conversion utilityThe conversion tool interface consists of two successive pages which contain graphical directory structures in which you can the WebLogic 5.1 root directory and the subdirectories that contain the weblogic.properties files of the servers or clusters to be migrated.
1. In the first page of the conversion utility, select the location of the directory from your 5.1 installation that contains the file weblogic.properties.2. In the second page of the conversion utility, in the select the location of the folder from your 5.1 installation that contains the file "weblogic.properties."
View results of conversion utility
If you correctly select the folders on the two successive pages, the conversion tool will perform the conversion and display a message on a third page, reporting on the conversion.
New Domain name is MyDomain-2*************************************
Server Name is migrationserver
This server doesn't belong to any cluster
*************************************
Converting Server properties
Warning--- File democert.pem not found has to be copied under config/MyDomain-2/migrationserver directory
Warning-- File ca.pem not found has to be copied under config/MyDomain-2/migrationserver directory
Warning-- File demokey.pem not found has to be copied under config/MyDomain-2/migrationserver directory
Converting Server Debug Properties
Converting WebServer properties
Converting WebApp Component Properties
Converting JDBC Specific properties
Converting CORBA IIOP properties
Converting EJB Specific Properties
Converting StartupClass properties
Converting Shutdown Class properties
Converting MailSession Properties
Converting FileT3 properties
Converting JMS properties
Converting Security Properties
Converting the PasswordPolicy properties
Converting User Group and ACL properties
Creating webApp for the servlets registerd in the properties file
Startup Scripts for the Server are created in the ResultDir config/MyDomain-2
Conversion successful.
Set the environment variables for the new domain
1. Make sure that JAVA_HOME=c:\bea\jdk130.
2. Create serverclasses and clientclasses subdirectories of C:\bea\wlserver6.0\config\migrationdomain
3. Add SERVERCLASSES to classpath of the startMigrationDomain script.
4. Add CLIENTCLASSES to classpath of the setMigrationEnv script.
5. Add %BANKING_WEBAPP_CLASSES% to setMigrationEnv script.
6. Add .\samples\eval\cloudscape\lib\cloudscape.jar to the classpath in the startMigrationDomain script.
7. Add -Dcloudscape.system.home=./samples/eval/cloudscape/data to java run command in the startMigrationDomain script.
8. Make sure that -Dbea.home=c:\bea, in the startMigrationDomain script.
Copy the application, graphics and class files to the new domain
It is necessary to copy these files manually from the old WebLogic Server 5.1 installation to the new WebLogic Server 6.0 installation.
Application files1. Create a directory wlserver6.0\config\migrationdomain\applications\BankingApp.
2. To this new directory, copy Login.html, AccountDetail.jsp, and Error.jsp from weblogic\migrationserver\public_html.
Graphics file
1. Create a directory \bea\wlserver6.0sp1\config\migrationdomain\applications\BankingWebApp\images.
2. To this new directory, copy BEA_Button_Final_web.gif from weblogic\migrationserver\public_html\images.
Classfiles
1. Create a directory \bea\wlserver6.0sp1\config\migrationdomain\applications\BankingWebApp\WEB-INF\classes.
2. To this new directory, copy the directory and contents of \weblogic\migrationserver\servletclasses\examples.
1. Create a directory \bea\wlserver6.0sp1\config\migrationdomain\serverclasses.
2. To this new directory, copy the directory and contents of \weblogic\migrationserver\servletclasses\examples.
1. Create a directory \bea\wlserver6.0sp1\config\migrationdomain\clientclasses.
2. To this new directory, copy the directory and contents of \weblogic\migrationserver\clientclasses\examples.
Configure config.xml
It may be necessary to add the JDBCConnectionPool tag for demopool in config.xml.
Create the web.xml file for the applicationThe web.xml file for BankingWebApp\ should read as follows:
<web-app><servlet>
<servlet-name>
banking
</servlet-name>
<servlet-class>
examples.apps.banking.BankAppServlet
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>
banking
</servlet-name>
<url-pattern>
/banking/*
</url-pattern>
</servlet-mapping>
</web-app>
Run the application
Run the sample application by starting the server and entering the following URL in your browser's address field:
http://localhost:7001/BankingWebApp/login.htm
Improving performance
This section will contain instructions for improving the performance of the sample application on the WebLogic 6.0 server.
Recompile EJB with 6.0 ejbcMake a copy of app_banking.jar.
Strip the jar of the generated container class files.
Recompile a copy of the app_banking.jar for 6.0.
java weblogic.ejbc -compiler javac app_banking.jar %APPLICATIONS%\app_banking6.jar
Recompile server classesDeploy the application as an .ear package