Previous Contents Index DocHome Next |
iPlanet Application Server Migration Guide |
Chapter 4 Running NAS 4.0 Applications
This chapter describes the basic steps to migrate your Netscape Application Server 4.0 applications to run on iPlanet Application Server 6.0.This chapter contains the following sections:
Overview
iPlanet Application Server 6.0 is certified compliant with Java 2 Platform, Enterprise Edition specification version 1.2 (J2EE 1.2). While the architecture of iPlanet Application Server 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 depends on how much your applications depend on deprecated J2EE and NAS proprietary methods. Deployment and JavaServer Pages require conversion procedures. Tools are provided for these procedures. 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 outlined in this chapter 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 iPlanet Application Server 6.0 available.
Differences Between NAS 4.0 and iPlanet Application Server 6.0
The following table highlights the main differences between NAS 4.0 and iPlanet Application Server 6.0 components. Each of these component differences and the procedure to migrate, follows the table.
Component
NAS 4.0
Migration Tactic
Effort
iPlanet Application Server 6.0
Migrating NAS 4.0 Components
This section outlines the requirements for migrating various NAS 4.0 components to iPlanet Application Server 6.0. The following topics are included here:
Basic Migration Steps
Basic Migration Steps
The basic steps you need to consider for migrating NAS 4.0 components to iPlanet Application Server are as follows:
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 iPlanet Application Server Deployment Tool as described in Chapter 2, of the Administration & Deployment Guide.
JDK Migration
iPlanet Application Server 6.0 uses the Java 2 Development Toolkit version 1.2.2 (JDK 1.2.2).An important difference for iPlanet Application Server is that if a native interface is used such as NMI, you need to replace it with JNI.
For more information regarding 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.html
For 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, perform the following steps:
Get the list of deprecated methods and their replacements at:
Replace the deprecated methods and recompile your application.
- http://java.sun.com/j2ee/j2sdkee/techdocs/api/deprecated-list.html
- For specific incompatibilities, see:
- http://java.sun.com/products/jdk/1.2/compatibility.html
Servlet Migration
iPlanet Application Server 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 iPlanet Application Server 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 Java Servlet 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 distributable servlets
RequestDispatcher can be acquired by name
RequestDispatcher can be acquired using a relative path
Internationalization improvements
Many clarifications of distributed servlet engine semantics
Behaviour of servlet parameter validation has changed (for more information, see the Programmer's Guide)
Servlet API Changes
The following servlet API changes have been implemented:
The getLocale method was added to the ServletRequest interface to aid in determining what client locale.
isSecure method was added to the ServletRequest interface. This indicates whether or not the request was transmitted via a secure transport such as HTTPS.
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.
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.
Added the getHeaders method to the HttpServletRequest interface to allow all the headers associated with a particular name to be retrieved from the request.
Added the isUserInRole and getUserPrinciple methods to the HttpServletRequest method to allow servlets to use an abstract role based authentication.
Added the addHeader, addIntHeader, and addDateHeader methods to the HttpServletResponse interface to allow multiple headers to be created with the same header name.
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.
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:
Note that some methods have been deprecated in HTTPSession2.
Replace both NAS 4.0 deprecated methods and J2EE deprecated methods to make your application 100% J2EE compliant
Replace NAS 4.0 deprecated methods only. Your application will run on iPlanet Application Server 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.
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 accomplish this replacement.
(Optional) Replace Servlet 2.2 deprecated methods.
Here sample.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.
Replace Access Control List based logic with declarative security model.
- For a list of deprecated methods go to http://java.sun.com/products/servlet/2.2/javadoc/deprecated-list.html
- 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:
Replace URI naming that uses the AppPath as the root for absolute references to JSPs or other servlets.
Use the auth method tag in XML files to set the authentication method to either Basic, Certificate, or Form based.
- boolean loginSession(String user, String paswd);
void logoutSession();
boolean isAuthorized(String target, String permission);
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.
Remove the ACL entries .gxr files.
- In iPlanet Application Server 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("/sample.jsp");
rd.forward(req,res);
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.
Convert NTV descriptor files to XML files
Convert NTV decriptor files and add them to the EJB JAR archive file. To perform this procedure, use the following steps:
- 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 files represent the J2EE and the iPlanet Application Server-specific XML respectively.
Create a new web application as described in Chapter 2 of the Administration & Deployment Guide.
Deploy your application as described in Chapter 2 "Running NAS 2.1 Applications.On the Servlet menu, select "Import from 4.0."
Navigate to the appInfo.ntv file that you want to convert and choose OK.
Continue adding servlet files and other files to your web application.
- The appInfo.ntv file and servlet files that it points to will be converted into a .xml files, which willbe added to your web application.
Save and deploy your web application as described in Chapter 2 of the Administration & Deployment Guide.
JSP Migration
iPlanet Application Server 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 JSP 1.1 specification extends JSP 0.92 to JSP 1.1 by incorporating the following enhancements:
Using Servlet 2.2 as the foundations for its semantics.
In addition, iPlanet Application Server 6.0 provides caching and load balancing for JSPs and provides custom tag extensions.Enabling the delivery of translated JSP pages into JSP containers.
GX Tags Deprecated
GX tags have been deprecated. Migrate any NAS 4.0 JSP templates with GX tags in them. iPlanet Application Server uses JSP extension tags instead.
JSP Migration Steps
To migrate your NAS 4.0 JavaServer Pages, perform the following steps:
Replace URI naming that uses the AppPath as the root for absolute references to servlets or other JSPs.3.
Convert JavaServer Pages from specification 0.92 to 1.1. JavaServer Pages must be migrated. You can use the convert2jsp11 tool to convert JSP 0.92 to JSP 1.1, outlined in the section, Converting JSP 0.92 to JSP 1.1.
Converting JSP 0.92 to JSP 1.1
Use the supplied conversion tool (convert2jsp11) 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.NOTE: Remember to create back up copies of your files prior to conversion.
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
Note that in these examples, appPath is C:\Netscape\Server4\NAS\APPS on Windows NT and /export/nas4/nas/APPS on Solaris.The following first example converts all of the JSP files in a directory called myApplication which is rooted in your appPath:
Windows NT:
convert2jsp11 -r -ap c:\netscape\server4\nas\APPS myApplication
Solaris:
convert2jsp11 -r -ap /export/nas4/nas/APPS myApplication
The second example, converts a single JSP file called myJSP.jsp in a directory called myApplication which is rooted in your appPath:
Windows NT:
convert2jsp11 -ap c:\netscape\server4\nas\APPS myApplication\myJSP.jsp
Solaris:
convert2jsp11 -ap /export/nas4/nas/APPS myApplication/myJSP.jsp
EJB Migration
iPlanet Application Server 6.0 employs version 1.1 of the Enterprise Java Bean (EJB) Specification. For detailed information on the EJB specification go to:
The EJB specification includes the following primary changes from EJB 1.0 to EJB 1.1:
- http://java.sun.com/products/ejb/
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 following changes in the EJB 1.1 specification were made to improve the support for the development, application assembly, and deployment of iPlanet Application Server 6.0 applications.
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.
Support for Application Assembly in the deployment descriptor.
Bean Provider and Application Assembler responsibilities have been clearly divided.
EJB Migration Steps
To migrate your NAS 4.0 Enterprise Java Beans, perform the following steps:
Replace Access Control List based logic with declarative security model.
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.
Convert deployment descriptors.
- 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.
Modify code and descriptors to exclude deprecated classes and replace with new methods.
- For more information, see "EJB Deployment.
Instances Where EJB Code Must Be Changed or Re-compiled
You must change or re-compile EJB code in the following instances:
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.
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.
The bean is an entity bean that uses the UserTransaction interface. In EJB 1.1, an entity bean must not use the UserTransaction interface.
The bean uses the UserTransaction interface and implements the SessionSynchronization interface at the same time. This behavior is disallowed in EJB 1.1.
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:
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.
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.
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. The following steps outlines its use:
Convert property files to XML files.
Convert NTV decriptor files and add them to the EJB JAR archive file.
- 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 files represent the J2EE and the iPlanet Application Server-specific XML respectively.
Create a new EJB JAR module, as described in Chapter 2 of the Administration & Deployment Guide.
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 will be 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.
Deploy your application as described in 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."
JNDI Migration
iPlanet Application Server 6.0 uses version 1.2 of the Java Naming and Directory Interface (JNDI) 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:
In 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 iPlanet Application Server 6.0 involves the following requirements:
- http://java.sun.com/products/jndi/1.2/compat.html#incompat
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.
Java Extensions
To migrate NAS 4.0 Java extensions to iPlanet Application Server 6.0, perform the following steps:
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).
C++ Extensions
To migrate NAS 4.0 C++ extensions to iPlanet Application Server 6.0, recompile and link NAS 4.0 C++ extensions against iPlanet Application Server 6.0 libraries.
Using Rich Client (ISecurity Interface)
The ISecurity interface needs to be implemented when using Rich Client. ISecurity sets the user name and password in Rich Client.
Security Features
iPlanet Application Server 6.0 implements security constraints at deployment time. Standard declarative access control rules are defined by the developer when the application is deployed. Developers will, for example, specify several levels of security such as administrator, guest, member etc. Then they 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, iPlanet Application Server 6.0 implements security independent of the code at the deployment of the application.
For EJB related security go to:
- http://www.java.sun.com/security/seccodeguide.html.
- 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 iPlanet Application Server 6.0 prior to migrating your own applications, as an example. Refer to the code source online at http://www.iPlanet.com/support/.This section describes the guidelines for porting a bank sample application from NAS 4.0 to iPlanet Application Server 6.0.
The iPlanet Application Server 6.0 Bank Sample application includes the following features:
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 an .xml file instead of proprietary .ntv file.
Comparison of iPlanet Application Server 6.0 Bank Application & NAS 4.0 nsOnlineBank
This section compares NAS 4.0 and iPlanet Application Server 6.0 components.
General Porting Guidelines
This section outlines some general porting guidelines for migrating NAS 4.0 application components to iPlanet Application Server 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.
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, and loginerror.jsp) should be kept under <install-location>/<app-name>.
EJBs: if DataSource is passed through <resource ref> tag, the corresponding iPlanet Application Server EJB XML should have <jndi-name>, similiar to the datasource "jdbc/LocalDS". LocalDS.
- EJB XML files are generated using PropToEJB tool (note that 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.
Previous Contents Index DocHome Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated February 05, 2001