![]() |
iPlanet Application Server Migration Guide |
Chapter 4 Running NAS 4.0 Applications on iAS 6.0
This chapter describes the basic steps to migrate your Netscape Application Server 4.0 application to run on iPlanet Application Server 6.0.This chapter contains the following:
Differences between NAS 4.0 and iAS 6.0
Overview
iAS 6.0 is certified compliant with Java 2 Platform, Enterprise Edition specification version 1.2 (J2EE 1.2). While the architecture of iAS 6.0 is the same as NAS 4.0, the 100% J2EE standard means that your applications must conform to J2EE 1.2 in order to run. The migration effort will depend on how much your applications depend on deprecated J2EE and NAS proprietary methods. Deployment and Java Server Pages require conversion procedures. Tools are provided for this. In general your effort will be to replace deprecated methods, convert and redeploy. One way to check if your applications have deprecated methods is to recompile them.Follow the steps below to begin the migration of your application.
You may find it helpful to work through the "Bank" migration example which is available online at the iPlanet web site. Go to http://www.iPlanet.com/support for further information. There is a step by step migration of a NAS 4.0 application to run on iAS 6.0 available.
Differences between NAS 4.0 and iAS 6.0
The following table highlights the main differences between NAS 4.0 and iAS 6.0 components. Each of these component differences and the procedure to migrate, follows the table.
Migrating components Step by Step
The basic migration steps are:
Look for deprecated/modified methods in your code
Replace deprecated methods as shown in this chapter.
Convert Java Server Pages with supplied tool.
Convert descriptors for servlets and EJBs with the supplied tool
Redeploy your application using the iAS deployment tool as described in Chapter 2 of the Administration & Deployment Guide
JDK Migration
iAS 6.0 uses the Java 2 Development Toolkit version 1.2.2 (JDK 1.2.2).An important difference for iAS is that if a native interface is used such as NMI, this needs to be replaced with JNI.
To better understand the changes from JDK 1.1.7 to JDK 1.2.2 go to
http://java.sun.com/products/jdk/1.2/docs/relnotes/features.htmlFor more information on JDK 1.2.2 go to
http://java.sun.com/products/jdk/1.2/docs/index.html
JDK Migration Steps
To migrate NAS 4.0 applications from JDK 1.1.7 to JDK 1.2.2:
Get the list of deprecated methods and their replacements at
http://java.sun.com/j2ee/j2sdkee/techdocs/api/deprecated-list.html and specific incompatibilities at http://java.sun.com/products/jdk/1.2/compatibility.html
Replace the deprecated methods and recompile your application.
Overview
iAS 6.0 uses version 2.2 of the Java Servlet Specification. For detailed information on the Specification go to http://java.sun.com/products/servlet/
To find out what is new in Java Servlet API 2.2 go to
http:/developer.java.sun.com/developer/technicalArticles/Servlets/servletapi/Servlets from NAS 4.0 will run as is on iAS 6.0 if they use interfaces from version 2.1 only and do not use any deprecated classes.
The following major changes have been made to the specification since version 2.1;
Java Class, Configured in XML
Servlet is always part of an application
Servlets are archived in .war files
Security features have been added
The introduction of the web application concept
The introduction of the web application archive files
The introduction of response buffering
The introduction of distributable servlets
The ability to get a RequestDispatcher by name
The ability to get a RequestDispatcher using a relative path
Internationalization improvements
Many clarifications of distributed servlet engine semantics
Behaviour of Servlet parameter validation has changed. See the programmers guide for more information.
Servlet API Changes
\x7f The getLocale method was added to the ServletRequest interface to aid in determining what locale the client is in.\x7f isSecure method was added to the ServletRequest interface. This indicates whether or not the request was transmitted via a secure transport such as HTTPS.
\x7f getInitParameter and getInitParameterNames method were added to the ServletContext interface. Initialization parameters can now be set at the application level to be shared by all servlets that are part of that application.
-The construction methods of UnavailableException have been replaced as existing constructor signatures. These constructors have been replaced by simpler signatures.
\x7f The getServletName method was added to the ServletConfig interface. This allows a servlet to obtain the name by which it is known to the system, if any.
\x7f Added the getHeaders method to the HttpServletRequest interface to allow all the headers associated with a particular name to be retrieved from the request.
\x7f Added the isUserInRole and getUserPrinciple methods to the HttpServletRequest method to allow servlets to use an abstract role based authentication.
\x7f Added the addHeader, addIntHeader, and addDateHeader methods to the HttpServletResponse interface to allow multiple headers to be created with the same header name.
\x7f Added the getAttribute, getAttributeNames, setAttribute, and removeAttribute methods to the HttpSession interface to improve the naming conventions of the API. The getValue, getValueNames, setValue, and removeValue methods are deprecated.
\x7f Added the getContextPath method to the HttpServletRequest interface so that the part of the request path associated with a web application can be obtained.
Servlet Migration Steps
There are two paths to migration.
Replace both NAS 4.0 deprecated methods and J2EE deprecated methods to make your application 100% J2EE compliant
To migrate your servlets from NAS 4.0 to a 100% J2EE complliant application, you will need to replace NAS 4.0 propietary methods and J2EE deprecated methods. Follow the Optional Step 1 to do this.Replace NAS 4.0 deprecated methods only. Your application will run on iAS 6.0 even if it uses J2EE deprecated methods. However, it is advisable to plan to migrate to J2EE 1.2, as the deprecated methods may not be available in the future.
OPTIONAL Step 1. Replace Servlet 2.2 deprecated methods.
For a list of deprecated methods go to http://java.sun.com/products/servlet/2.2/javadoc/deprecated-list.htmlStep 2. Replace Access Control List based logic with declarative security model.
Use the new declarative based security procedure described in the servlet specification instead of Access Control Lists (ACL). Security is implemented as part of deployment in XML files instead of at the application level.
Remove the following deprecated HTTPSession2 security methods:
Step 3. Replace URI naming that uses the AppPath as the root for absolute references to JSPs or other servlets.
boolean loginSession(String user, String paswd);
void logoutSession();
boolean isAuthorized(String target, String permission);Use the auth method tag in XML files to set the authentication method to either Basic, Certificate or Form based
In the .xml file, use the <security constraint> to specify the roles that can execute the servlets. Create roles using <role-name> or reference a logical role by using <role-link> tags.
In iAS 6.0 the application context root is the root for absolute references. A servlet would forward to another JSP in the same application as itself, in the following manner.RequestDispatcher rd = req.getRequestDispatcher("/foo.jsp");
rd.forward(req,res);Here foo.jsp is in the same application as the servlet that is including it. You will find the JSP under AppPath/ApplicationName rather than AppPath, which would have been the case in NAS 4.0.
Servlet Deployment
Servlet 2.2 has introduced the use of XML files to replace the deployment descriptor used in NAS 4.0. The NTV descriptor files in your NAS 4.0 application must be converted to XML files and added to the web application archive file that the deployment tool creates.
Step 1: Convert NTV descriptor files to XML files
Use the following tool to convert the NTV files to XML:.
convertNtv2Xml $path/appInfo.ntv $newpath/myApp.xml
$path points to the location of the appInfo.ntv (which internally provides the location of the serlvet info NTV files).
The conversion tool creates 2 new files, myApp.xml, and ias-myApp.xml, in $newpath. These represent the J2EE and the ias-specific XML respectively.
Step 2: Convert NTV decriptor files and add them to the EJB JAR archive file.
Create a new web application as described in Chapter 2 of the Administration & Deployment Guide.
Step 3: Deploy your application as described in Chapter 2 "Running NAS 2.1 Applications on iAS 6.0.On the Servlet menu, select "Import from 4.0".
Navigate to the appInfo.ntv file that you want to convert and choose OK. The appInfo.ntv file and servlet files that it points to will be converted into a .xml files, which willbe added to yourweb application.
Continue adding servlet files and other files to your web application.
Save and deploy your web application as described in Chapter 2 of the Administration & Deployment Guide.
JSP Migration
iAS 6.0 employs version 1.1 of the Java Server Pages Specification. The JSP 1.1 specification is integrated with the J2EE, particularly for security, transaction, and session state concepts.
For detailed information on the Specification go to http://java.sun.com/products/jsp/The specification includes the following primary changes from JSP 0.92 to JSP 1.1:
n Using Servlet 2.2 as the foundations for its semantics.
n Enabling the delivery of translated JSP pages into JSP containers.
n Providing a portable Tag Extension mechanism.
In addition iAS 6.0 provides caching and load balancing for JSP 1.1.
Deprecated
GX tags have been deprecated. Migrate any NAS 4.0 JSP templates with GX tags in them. iAS uses JSP extension tags instead.
JSP Migration Steps
Step 1. Replace URI naming that uses the AppPath as the root for absolute references to servlets or other JSPs.
Step 2. Convert Java Server Pages from specification 0.92 to 1.1
Java Server Pages must be migrated. Follow the instructions below
Converting JSP 0.92 Pages to JSP 1.1
Use the supplied conversion tool to convert already existing JSP 0.92 files. The tool can be used to convert individual files, or it can recurse through an entire tree of directories, converting all JSP files found.
Caution
Be sure to create backup copies of your existing files before converting!The conversion tool converts all the 0.92 JSP files to their 1.1 equivalent, keeping the same name. The 0.92 versions of the files are copied to a file of the same name, with the extension .0.92. For example, if you convert a file myApp.jsp, that file becomes the new JSP 1.1 version, and the older version is copied to a file called myApp.jsp.0.92.
If any of the 0.92 JSP files in a given conversion contain an error, then the conversion for that file fails, creating an empty output file. In this event, re-copy the corresponding filename.0.92 version back to filename, correct the error, and run the conversion script again for that file.
convert2jsp11 [-r] -ap appPath file/directory
Examples
convert2jsp11 -r -ap c:\netscape\server4\nas\APPS myApplication
convert2jsp11 -r -ap /export/nas4/nas/APPS myApplication
To convert a single JSP file called myJSP.jsp in a directory called myApplication
which is rooted in your appPath:
convert2jsp11 -ap c:\netscape\server4\nas\APPS myApplication\myJSP.jsp
Solaris:
convert2jsp11 -ap /export/nas4/nas/APPS myApplication/myJSP.jsp
Overview
iAS 6.0 employs version 1.1 of the Enterprise Java Beans (EJB) Specification. For detailed information on the Specification go to http://java.sun.com/products/ejb/The specification includes the following primary changes from EJB 1.0 to EJB 1.1:
The Entity bean specification has been tightened, and support for Entity beans is mandatory for Container providers.
The modifications affect mainly Support for transactions, Enterprise Bean Environments, Security and Deployment Descriptors. There is very little impact for EJB 1.0 applications in runtime. The only change to the runtime API of the EJB Container is the replacement of the java.security.Identity class with the java.security.Principal interface.
The other changes in the EJB 1.1 specification were made to improve the support for the development, application assembly, and deployment of iAS 6.0 applications.\x7f Support is enhanced for the enterprise bean's environment. The Bean Provider must specify all the bean's environmental dependencies using entries in a JNDI naming context.
\x7f Support for Application Assembly in the deployment descriptor.
\x7f Bean Provider and Application Assembler responsibilities have been clearly divided.
EJB Migration Steps
Step 1. Replace Access Control List based logic with declarative security model.
As with servlets, Access Control Lists on EJBs must be removed. Use the <method-permission> tag to specify the rules that can execute EJB methods.Step 2. Convert deployment descriptors
See section on EJB DeploymentStep 3. Modify Code and descriptors to exclude deprecated classes and replace with new methods
EJB 1.0 enterprise bean code does not have to be changed or re-compiled to run in an EJB 1.1 Container, except in the exceptions detailed below. The mandatory migration is for the deployment descriptors to be converted to the EJB 1.1 XML.
Instances where EJB code must be changed or re-compiled
\x7f The bean uses the javax.jts.UserTransaction interface. The package name of the javax.jts interface has changed to javax.transaction, and there have been minor changes to the exceptions thrown by the methods of this interface. An enterprise bean that uses the javax.jts.UserTransaction interface needs to be modified to use the new name javax.transaction.UserTransaction.\x7f The bean uses the getCallerIdentity() or isCallerInRole(Identity identity) methods of the javax.ejb.EJBContext interface. These methods were deprecated in EJB 1.1 because the class java.security.Identity is deprecated in Java 2 platform. An enterprise bean written to the EJB 1.0 specification needs to be modified to use the new methods to work in all EJB 1.1. Containers.
\x7f The bean is an entity bean that uses the UserTransaction interface. In EJB 1.1, an entity bean must not use the UserTransaction interface.
\x7f The bean uses the UserTransaction interface and implements the SessionSynchronizationinterface at the same time. This is disallowed in EJB 1.1.
\x7f The bean violates any of the additional semantic restrictions defined in EJB 1.1 but which were not defined in EJB 1.0.
-For every EJB Create there must be a matching EJBPostCreate. EJBPostCreate was optional in EJB 1.0 and is now Mandatory
Exception Handling Changes
-The EJB 1.1 specification of exception handling preserved the rules defined in the EJB 1.0 specification, with the following exceptions:\x7f EJB 1.0 specified that the enterprise bean business methods and container-invoked callbacks use the java.rmi.RemoteException to report non-application exceptions. This practice is deprecated in EJB 1.1the enterprise bean methods should use the javax.ejb.EJBException, or other suitable RuntimeException to report non-application exceptions.
\x7f In EJB 1.1, all non-application exceptions thrown by the instance result in the rollback of the transaction in which the instance executed, and in discarding the instance. In EJB 1.0, the Container would not rollback a transaction and discard the instance if the instance threw the java.rmi.RemoteException.
\x7f In EJB 1.1, an application exception does not cause the Container to automatically rollback a transaction. In EJB 1.0, the Container was required to rollback a transaction when an application exception was passed through a transaction boundary started by the Container. In EJB 1.1, the Container performs the rollback only if the instance have invoked the setRollback-Only() method on its EJBContext object.javax.ejb.ejbex.
EJB Deployment
EJB 1.1 has introduced the use of XML files to replace the deployment descriptor used in NAS 4.0. The Property descriptor files in your NAS 4.0 application must be converted to XML files. In addition to registering the application you must run ejbReg.To convert the Property files to XML use the supplied tool convertPropsXML.
Step 1: Convert property files to XML files
Use the following tool to convert the .props files to XML:.
convertProps2Xml $path/foobar.props $newpath/myAppEjb.xml
$path points to the location of .props file and the tool results in the generation of two XMLs myAppEJB.xml and ias-myAppEjb.xml files. These represent the J2EE and the iAS-Specific XML respectively.
Step 2: Convert NTV decriptor files and add them to the EJB JAR archive file.
Create a new EJB JAR module as described in Chapter 2 of the Administration & Deployment Guide.
Step 3: Modify you application code to handle exceptions and transactions.On the EBJ menu, select "Import from 4.0".
Navigate to the .properties file that you want to convert and choose OK. The .properties file will be converted into a .xml files, which willbe added to your EBJ JAR module.
Continue adding .class files and other files to your EBJ JAR module.
Save and deploy your EBJ JAR module as described in Chapter 2 of the Administration & Deployment Guide.
If you are using Transactions or Exceptions you may need to make some code changes. See the section "Exception Handling Changes".Step 4: Deploy your application as described in the Deployment manual.
JNDI Migration
iAS 6.0 uses version 1.2 of the Java Naming and Directory Interface extension. JNDI is provided as part of the Java Enterprise API set.NAS 4.0 applications that use JNDI 1.1 must be migrated to JNDI 1.2.
The specific incompatibilities can be seen at
http://java.sun.com/products/jndi/1.2/compat.html#incompatIn J2EE every application defines its own naming environment which is specified via the component's deployment descriptor. A component's descriptor should also contain information about all EJBs and data sources that it is looking up via ejb-ref and resource-ref elements. Migrating NAS4.0 applications to iAS6.0 involves the following steps
Identifying usage of beans/resources that are being looked up by the application.
Setting up appropriate deployment descriptor entries for resource-refs and ejb-refs.
Ensure that environment lookup happens via java:comp/env/<envionmentEntryName> pattern as specified by the J2EE specification.
Rich Client
The ISecurity interface needs to be implemented when using RichClient ). ISecurity sets the user name and password in Rich Client.
Java Extensions
Migration of Java NAS 4.0 extensions to iAS 6.0 is as follows:
Load IDL code in iPlanet Extension Builder 6.0 and create new generated code
Merge any changes which have been made to the previous extensions into the new generated code
Convert any references to NMI to JNI (if applicable)
Perform all other Java code changes for JDK 1.2.2
C++ Extensions
Recompile and link NAS 4.0 C++ Extensions against iAS 6.0 libraries
Security Features
iAS 6.0 implements security constraints at deployment time. Standard declarative access control rules are defined by the developer when the application is deployed. The developer will, for example, specify several levels of security such as administrator, guest, member etc. Then she will write code to check the current user's permission level when accessing secure procedures. At deployment time, groups of users are assigned the correct security level allowing the application to easily verify permission level before accessing the restricted procedure.
In NAS 4.0, security was implemented at the application level by setting up access control lists that define permissions granted to specific users and groups. NAS 4.0 implemented security at the code level, iAS 6.0 implements security independent of the code at the deployment of the application.For tips on security go to http://www.java.sun.com/security/seccodeguide.html
For EJB related security go to http://www.java.sun.com/j2ee/j2sdkee/techdocs/guides/ejb/html/Security.fm.html
Migration Example "The Bank"
Use this example to walk through the migration process. You can also modify the NAS 4.0 nsOnline Bank source and migrate the sample to iAS 6.0 prior to migrating your own applications, as an example. Refer to the source online at http://www.iPlanet.com/support/.This describes the guide lines for porting a bank sample application from NAS 4.0 to iAS 6.0
Features of the iAS 6.0 Bank Sample Application
Bank sample application is using new Form based login (J2EE style)
Proprietary methods like HttpSession2, loginSession, NASRowSet are replaced with the J2EE equivalent
EJB deployment descriptors are described in xml files
EJB lookup is URL based like "java:comp/env/"lookupname"
Servlet deployment is described in xml file instead of proprietary "ntv" file
Comparison of iAS 6.0 Bank Application & NAS 4.0 nsOnlineBank
General Porting Guide Lines for Bank Sample Application (from NAS 4.0 to iAS 6.0)
LDAP
LDAP code (.java file) should reflect the LDAP server port number which is supplied at installation time
DataBase
DataSource should be passed through the <resource ref > tag instead of <env entry> tag.Servlet
If a servlet is doing a look up for an EJB, the corresponding J2EE Servlet XML should have <ejb-ref> tag.For Form based mechanism,J2EE Servlet XML should have the <login-config> tag.
The login Page should be a .jsp file for Form Based Login mechanism.
Text Fields for Form Based Login page - username should be "j_username" password should be "j_password"
Login pages (like login, jsp & loginerror.jsp) should be kept under <install-location>/<app-name>
If DataSource is passed through <resource ref > tag, the corresponding iAS EJB XML should have <jndi-name> like "jdbc/LocalDS". LocalDS is the datasource
EJB XML files are generated using PropToEJB tool (There may be additional manual steps after the conversion)
Further Reading
JavaTM 2 Platform, Enterprise Edition Specification Version 1.2 Copyright 1999, Sun Microsystems, Inc. Available at http://java.sun.com/j2ee/docs.htmlJavaTM 2 Platform, Enterprise Edition Technical Overview (J2EE Overview).Copyright 1998, 1999, Sun Microsystems, Inc. Available at http://java.sun.com/j2ee/white.html
JavaTM 2 Platform, Standard Edition, v1.2.2 API Specification (J2SE specification). Copyright 1993-99, Sun Microsystems, Inc. Available at http://java.sun.com/products/jdk/1.2/docs/api/index.html
Enterprise JavaBeansTM Specification, Version 1.1 (EJB specification). Copyright1998, 1999, Sun Microsystems, Inc. Available at http://java.sun.com/products/ejb
Enterprise JavaBeansTM to CORBA Mapping, Version 1.1 (EJB-CORBA mapping).Copyright 1998, 1999, Sun Microsystems, Inc. Available at http://java.sun.com/products/ejb
JavaServer PagesTM Specification, Version 1.1 (JSP specification). Copyright 1998, 1999, Sun Microsystems, Inc. Available at http://java.sun.com/products/jsp
JavaTM Servlet Specification, Version 2.2 (Servlet specification). Copyright 1998,1999, Sun Microsystems, Inc. Available at http://java.sun.com/products/servlet
JDBCTM 2.0 API (JDBC specification). Copyright 1998, 1999, Sun Microsystems, Inc. Available at http://java.sun.com/products/jdbc
JDBCTM 2.0 Standard Extension API (JDBC extension specification). Copyright 1998, 1999, Sun Microsystems, Inc. Available at http://java.sun.com/ products/jdbc
JavaTM Naming and Directory Interface 1.2 Specification (JNDI specification). Copyright 1998, 1999, Sun Microsystems, Inc. Available at http:// java.sun.com/products/jndi
JavaTM Message Service, Version 1.0.2 (JMS specification). Copyright 1998, Sun Microsystems, Inc. Available at http://java.sun.com/products/jms.
JavaTM Transaction API, Version 1.0.1 (JTA specification). Copyright 1998, 1999, Sun Microsystems, Inc. Available at http://java.sun.com/products/jta
JavaTM Transaction Service, Version 0.95 (JTS specification). Copyright 1997-1999, Sun Microsystems, Inc. Available at http://java.sun.com/products/jts
JavaMailTM API Specification Version 1.1 (JavaMail specification). Copyright 1998, Sun Microsystems, Inc. Available at http://java.sun.com/products/javamail
JavaBeansTM Activation Framework Specification Version 1.0.1 (JAF specification). Copyright 1998, Sun Microsystems, Inc. Available at http://java.sun.com/ beans/glasgow/jaf.html
The JavaTM 2 Platform, Enterprise Edition Application Programming Model, Copyright 1999, Sun Microsystems, Inc. Available at http://java.sun.com/j2ee/apm.
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated April 25, 2000