Utility Tools

CHAPTER 14

How to Handle J2EE Versions

This chapter helps you target your application at an appropriate version of J2EE (Java 2 Platform, Enterprise Edition). It is especially useful if you need to know when and how to migrate existing projects to a newer J2EE version. Topics include:

For more information For an overview of J2EE, see the Sun J2EE Web site.

Support for J2EE versions

Choices you make about J2EE versions are largely determined by the J2EE server(s) you deploy to. To begin, find out whether your J2EE server is compatible with J2EE 1.2 or 1.3. Then read the following topics to learn what that means for your application and how you handle it in the Novell exteNd Director development environment:

What J2EE 1.2 servers support

If you develop applications for deployment to J2EE 1.2 servers, you can use J2EE 1.2 archives and J2EE 1.2 technologies. But J2EE 1.2 servers do not support J2EE 1.3 archives and J2EE 1.3 technologies.

J2EE 1.2 archives The J2EE 1.2 archives are:

Name and version	Description
EAR 1.2	Enterprise (application) archive
WAR 2.2	Web archive (for servlets and JSP pages)
EJB JAR 1.1	Enterprise JavaBean (EJB) archive
Client JAR 1.2	Application client archive (CAR)

J2EE 1.2 technologies The J2EE 1.2 technologies include:

Java Servlets 2.2
JavaServer Pages (JSP) 1.1
Enterprise JavaBeans (EJB) 1.1
JDBC Standard Extension 2.0
Java Transaction API (JTA) 1.0
JavaMail 1.1
Java Messaging Service (JMS) 1.0
Java Naming and Directory Interface (JNDI) 1.2
RMI-IIOP

What J2EE 1.3 servers support

If you develop applications for deployment to J2EE 1.3 servers, you can use either of the following:

In other words, J2EE 1.3 servers support J2EE 1.2 applications as well as J2EE 1.3 applications. For further flexibility, you also have the option of mixing J2EE 1.2 modules and features into your J2EE 1.3 applications as follows:

These J2EE 1.3 archives	Can contain
EARs	Both J2EE 1.2 modules (WARs, EJB JARs, client JARs) and J2EE 1.3 modules
EJB JARs	Entity beans that use either 1.x or 2.x container-managed persistence (CMP)

J2EE 1.3 archives The J2EE 1.3 archives are:

Name and version	Description
EAR 1.3	Enterprise (application) archive
WAR 2.3	Web archive (for servlets and JSP pages)
RAR 1.0	Resource adapter archive (for Connector architecture)
EJB JAR 2.0	Enterprise JavaBean (EJB) archive
Client JAR 1.3	Application client archive (CAR)

J2EE 1.3 technologies The J2EE 1.3 technologies include:

Java Servlets 2.3
JavaServer Pages (JSP) 1.2
Enterprise JavaBeans (EJB) 2.0
J2EE Connector 1.0
JDBC Standard Extension 2.0
Java Transaction API (JTA) 1.0
JavaMail 1.2
Java Messaging Service (JMS) 1.0.2
Java API for XML Parsing (JAXP) 1.1
Java Authentication and Authorization Service (JAAS) 1.0

The following technologies previously included with J2EE are now included with the Java 2 Platform, Standard Edition (J2SE): JNDI, RMI-IIOP.

What the development environment supports

The exteNd Director development environment provides built-in support for multiple versions of J2EE, including 1.2 and 1.3. It helps you handle version-related tasks throughout the life cycle of a project, including development, migration, and deployment:

Task	What you can do
Development	You can use the development environment to develop projects for any of the following: J2EE 1.2 archives J2EE 1.3 archives This includes the ability to add J2EE 1.2 and 1.3 modules to a 1.3 EAR as well as add 1.x and 2.x CMP entity beans to a 2.0 EJB JAR. See Versions for new projects and components.
Migration	You can use the development environment to migrate existing projects to a newer J2EE version. Scenarios include: Migrating a J2EE 1.2 project (and any 1.2 subprojects it contains) to 1.3 Migrating the J2EE 1.2 subprojects of a 1.3 project to 1.3 See Migrating projects from J2EE 1.2 to 1.3.
Deployment	You can deploy projects to J2EE servers by using the development environment (or, if necessary, vendor deployment tools). Scenarios include: Deploying a J2EE 1.2 project to a 1.2 or 1.3 server Deploying a J2EE 1.3 project to a 1.3 server For details on selecting an appropriate J2EE server and deploying to it, see Archive Deployment.

Task

What you can do

Development

You can use the development environment to develop projects for any of the following:

J2EE 1.2 archives
J2EE 1.3 archives

This includes the ability to add J2EE 1.2 and 1.3 modules to a 1.3 EAR as well as add 1.x and 2.x CMP entity beans to a 2.0 EJB JAR.

For more information See Versions for new projects and components.

Migration

You can use the development environment to migrate existing projects to a newer J2EE version. Scenarios include:

Migrating a J2EE 1.2 project (and any 1.2 subprojects it contains) to 1.3
Migrating the J2EE 1.2 subprojects of a 1.3 project to 1.3

For more information See Migrating projects from J2EE 1.2 to 1.3.

Deployment

You can deploy projects to J2EE servers by using the development environment (or, if necessary, vendor deployment tools). Scenarios include:

Deploying a J2EE 1.2 project to a 1.2 or 1.3 server
Deploying a J2EE 1.3 project to a 1.3 server

For more information For details on selecting an appropriate J2EE server and deploying to it, see Archive Deployment.

Your choices

This section examines specific kinds of projects and offers advice about making J2EE version choices for them. It covers:

Project scenarios

Use the following table to find the project scenarios that apply to you and learn how you can handle them in the exteNd Director development environment:

If you have this	You can
Source files for a J2EE 1.2 module or application (but no project)	Create one or more J2EE 1.2 projects for the source files, specifying appropriate project types and versions. Possible choices are: EAR 1.2 WAR 2.2 EJB 1.1 CAR 1.2
Source files for a J2EE 1.3 module or application (but no project)	Create one or more J2EE 1.3 projects for the source files, specifying appropriate project types and versions. Possible choices are: EAR 1.3 WAR 2.3 RAR 1.0 EJB 2.0 CAR 1.3
Packaged J2EE 1.2 archive (but no source files or project)	Create a J2EE 1.2 deploy-only project for the archive, specifying an appropriate project type and version. Possible choices are: EAR 1.2 WAR 2.2 EJB 1.1 CAR 1.2
Packaged J2EE 1.3 archive (but no source files or project)	Create a J2EE 1.3 deploy-only project for the archive, specifying an appropriate project type and version. Possible choices are: EAR 1.3 WAR 2.3 RAR 1.0 EJB 2.0 CAR 1.3
J2EE 1.2 enterprise archive project (EAR 1.2)	Do any of the following: Edit it and its subprojects (J2EE 1.2 modules) as needed, while adhering to the J2EE 1.2 APIs and specifications Deploy it to a J2EE 1.2 or 1.3 server Add subprojects to it (J2EE modules you add must be 1.2 modules) Migrate it and its subprojects (J2EE 1.2 modules) from J2EE 1.2 to 1.3: EAR 1.2 to EAR 1.3 WAR 2.2 to WAR 2.3 EJB 1.1 to EJB 2.0 CAR 1.2 to CAR 1.3
J2EE 1.3 enterprise archive project (EAR 1.3)	Do any of the following: Edit it and its subprojects as needed, according to these guidelines: For the EAR itself and its J2EE 1.3 modules, adhere to the J2EE 1.3 APIs and specifications For its J2EE 1.2 modules, adhere to the J2EE 1.2 APIs and specifications Deploy it to a J2EE 1.3 server Add subprojects to it (J2EE modules you add can be 1.2 or 1.3 modules) Migrate it if you want to migrate the J2EE 1.2 modules (subprojects) it contains to J2EE 1.3: WAR 2.2 to WAR 2.3 EJB 1.1 to EJB 2.0 CAR 1.2 to CAR 1.3
J2EE 1.2 project for any module: Web archive (WAR 2.2) Enterprise JavaBean archive (EJB 1.1) Application client archive (CAR 1.2)	Do any of the following: Edit it as needed, while adhering to the J2EE 1.2 APIs and specifications Deploy it to a J2EE 1.2 or 1.3 server Add it as a subproject to a J2EE 1.2 or 1.3 EAR project Migrate it from J2EE 1.2 to 1.3: WAR 2.2 to WAR 2.3 EJB 1.1 to EJB 2.0 CAR 1.2 to CAR 1.3
J2EE 1.3 project for any module: Web archive (WAR 2.3) Resource adapter archive (RAR 1.0) Enterprise JavaBean archive (EJB 2.0) Application client archive (CAR 1.3)	Do any of the following: Edit it as needed, while adhering to the J2EE 1.3 APIs and specifications Deploy it to a J2EE 1.3 server Add it as a subproject to a J2EE 1.3 EAR project
J2EE 1.2 deploy-only project (EAR 1.2, WAR 2.2, EJB 1.1, or CAR 1.2)	Do any of the following: Deploy it to a J2EE 1.2 or 1.3 server Add it as a subproject to a J2EE 1.2 or 1.3 EAR project (if it's a WAR, EJB, or CAR module) Migrate it from J2EE 1.2 to 1.3
J2EE 1.3 deploy-only project (EAR 1.3, WAR 2.3, RAR 1.0, EJB 2.0, or CAR 1.3)	Do either of the following: Deploy it to a J2EE 1.3 server Add it as a subproject to a J2EE 1.3 EAR project (if it's a WAR, RAR, EJB, or CAR module)

If you have this

You can

Source files for a J2EE 1.2 module or application (but no project)

Create one or more J2EE 1.2 projects for the source files, specifying appropriate project types and versions. Possible choices are:

EAR 1.2
WAR 2.2
EJB 1.1
CAR 1.2

Source files for a J2EE 1.3 module or application (but no project)

Create one or more J2EE 1.3 projects for the source files, specifying appropriate project types and versions. Possible choices are:

EAR 1.3
WAR 2.3
RAR 1.0
EJB 2.0
CAR 1.3

Packaged J2EE 1.2 archive (but no source files or project)

Create a J2EE 1.2 deploy-only project for the archive, specifying an appropriate project type and version. Possible choices are:

EAR 1.2
WAR 2.2
EJB 1.1
CAR 1.2

Packaged J2EE 1.3 archive (but no source files or project)

Create a J2EE 1.3 deploy-only project for the archive, specifying an appropriate project type and version. Possible choices are:

EAR 1.3
WAR 2.3
RAR 1.0
EJB 2.0
CAR 1.3

J2EE 1.2 enterprise archive project (EAR 1.2)

Do any of the following:

Edit it and its subprojects (J2EE 1.2 modules) as needed, while adhering to the J2EE 1.2 APIs and specifications
Deploy it to a J2EE 1.2 or 1.3 server
Add subprojects to it (J2EE modules you add must be 1.2 modules)
Migrate it and its subprojects (J2EE 1.2 modules) from J2EE 1.2 to 1.3:
- EAR 1.2 to EAR 1.3
- WAR 2.2 to WAR 2.3
- EJB 1.1 to EJB 2.0
- CAR 1.2 to CAR 1.3

J2EE 1.3 enterprise archive project (EAR 1.3)

Do any of the following:

Edit it and its subprojects as needed, according to these guidelines:
- For the EAR itself and its J2EE 1.3 modules, adhere to the J2EE 1.3 APIs and specifications
- For its J2EE 1.2 modules, adhere to the J2EE 1.2 APIs and specifications
Deploy it to a J2EE 1.3 server
Add subprojects to it (J2EE modules you add can be 1.2 or 1.3 modules)
Migrate it if you want to migrate the J2EE 1.2 modules (subprojects) it contains to J2EE 1.3:
- WAR 2.2 to WAR 2.3
- EJB 1.1 to EJB 2.0
- CAR 1.2 to CAR 1.3

J2EE 1.2 project for any module:

Web archive (WAR 2.2)
Enterprise JavaBean archive (EJB 1.1)
Application client archive (CAR 1.2)

Do any of the following:

Edit it as needed, while adhering to the J2EE 1.2 APIs and specifications
Deploy it to a J2EE 1.2 or 1.3 server
Add it as a subproject to a J2EE 1.2 or 1.3 EAR project
Migrate it from J2EE 1.2 to 1.3:
- WAR 2.2 to WAR 2.3
- EJB 1.1 to EJB 2.0
- CAR 1.2 to CAR 1.3

J2EE 1.3 project for any module:

Web archive (WAR 2.3)
Resource adapter archive (RAR 1.0)
Enterprise JavaBean archive (EJB 2.0)
Application client archive (CAR 1.3)

Do any of the following:

Edit it as needed, while adhering to the J2EE 1.3 APIs and specifications
Deploy it to a J2EE 1.3 server
Add it as a subproject to a J2EE 1.3 EAR project

J2EE 1.2 deploy-only project (EAR 1.2, WAR 2.2, EJB 1.1, or CAR 1.2)

Do any of the following:

Deploy it to a J2EE 1.2 or 1.3 server
Add it as a subproject to a J2EE 1.2 or 1.3 EAR project (if it's a WAR, EJB, or CAR module)
Migrate it from J2EE 1.2 to 1.3

J2EE 1.3 deploy-only project (EAR 1.3, WAR 2.3, RAR 1.0, EJB 2.0, or CAR 1.3)

Do either of the following:

Deploy it to a J2EE 1.3 server
Add it as a subproject to a J2EE 1.3 EAR project (if it's a WAR, RAR, EJB, or CAR module)

Approaching new development

When you start work on a new application or module, a good rule of thumb is to use the latest J2EE version and technologies supported by your target J2EE server(s). This typically provides a more mature platform, including:

J2EE improvements such as additional features, architecture enhancements, and other updates
Server improvements that accompany the newer J2EE implementation, such as faster deployment, better runtime performance, and easier maintenance

For example, if your deployment target is a J2EE 1.3 server, you should develop J2EE 1.3 archives for it (even though 1.2 archives are also supported). Within your archives, it's also recommended that you code to the latest standards available. If you develop EJB entity beans with container-managed persistence, that means using 2.x CMP instead of 1.x CMP.

Deciding when to migrate

Use the following table to decide when to migrate an existing J2EE archive project to a newer J2EE version:

Decision	When it applies
Migrate	If the project needs to use new features or other enhancements of the more recent J2EE version
Migrate	If you want to take advantage of improvements that your J2EE server introduces with its implementation of the more recent J2EE version
Don't migrate	If you need to deploy the project to a J2EE server that does not support the more recent J2EE version

For example, suppose you have a J2EE 1.2 WAR project and want to add servlet filters to it. In that case, you must first migrate this project to J2EE 1.3 (in other words, from WAR 2.2 to WAR 2.3).

Versions for new projects and components

Because the exteNd Director development environment supports multiple versions of J2EE, it offers you a choice of versions when you create parts of an application. This applies:

When creating projects

When you create a generic J2EE project, you can specify the J2EE version (1.2 or 1.3) of the archive that the project represents. The default is J2EE 1.3.

For example, suppose you need a new Web archive project. To create it, you select File>New>Project and choose WAR (on the Generic tab) as the project type. Then the New Project Wizard prompts for details about the project, including its J2EE version:

JVERprojversel

When you create other types of generic J2EE archive projects (EAR, RAR, EJB, CAR), the New Project Wizard adjusts the list of J2EE version choices accordingly. For deploy-only projects, you specify project type and J2EE version at the same time by choosing from a combined list:

JVERdeponlyversel

How your J2EE version choice affects a project When a project is created, your J2EE version choice is reflected in several places:

In this part of the project	Your J2EE version choice affects
Project (SPF) file	The following project settings: The j2eeVersion and moduleVersion attributes in the SPF file. They record the current version status of the project. For example: j2eeVersion="j2ee 1.3" moduleVersion="war 2.3" The project classpath entry for the JAR file that provides the J2EE API packages (needed for compiling). For J2EE 1.2 projects, the entry is `j2ee_api_1_2.jar`; for J2EE 1.3 projects, the entry is `j2ee_api_1_3.jar`.
Deployment descriptor	Which version of the appropriate J2EE deployment descriptor is created for the project. Depending on the project's J2EE version, you get a 1.2 or 1.3 deployment descriptor for your project type: EAR, WAR, RAR, EJB, or CAR. You can examine the DOCTYPE statement of the deployment descriptor to determine which DTD it follows. For details, see J2EE Deployment Descriptor DTDs. (Note that deployment descriptors are not created for deploy-only projects because their archive contents are static.)
Deployment plan (for exteNd Application Server 4.x or 5.x)	Which version of the appropriate exteNd deployment plan you get by default if you create one for the project. If you specify SilverStream 4.x as the server type: Depending on the project's J2EE version, the default is a 1.2 or 1.3 deployment plan for your project type: EAR, WAR, RAR, EJB, or CAR. You can examine the DOCTYPE statement of the deployment plan to determine which DTD it follows. If you specify Novell exteNd 5.x as the server type: Whether your project's J2EE version is 1.2 or 1.3, you always get a 1.3 deployment plan for your project type. For details, see exteNd Application Server Deployment Plan DTDs.

In this part of the project

Your J2EE version choice affects

Project (SPF) file

The following project settings:

The j2eeVersion and moduleVersion attributes in the SPF file. They record the current version status of the project. For example:
```
  j2eeVersion="j2ee 1.3" moduleVersion="war 2.3"
```
The project classpath entry for the JAR file that provides the J2EE API packages (needed for compiling). For J2EE 1.2 projects, the entry is j2ee_api_1_2.jar; for J2EE 1.3 projects, the entry is j2ee_api_1_3.jar.

Deployment descriptor

Which version of the appropriate J2EE deployment descriptor is created for the project. Depending on the project's J2EE version, you get a 1.2 or 1.3 deployment descriptor for your project type: EAR, WAR, RAR, EJB, or CAR. You can examine the DOCTYPE statement of the deployment descriptor to determine which DTD it follows.

For more information For details, see J2EE Deployment Descriptor DTDs.

(Note that deployment descriptors are not created for deploy-only projects because their archive contents are static.)

Deployment plan (for exteNd Application Server 4.x or 5.x)

Which version of the appropriate exteNd deployment plan you get by default if you create one for the project.

If you specify SilverStream 4.x as the server type:

Depending on the project's J2EE version, the default is a 1.2 or 1.3 deployment plan for your project type: EAR, WAR, RAR, EJB, or CAR. You can examine the DOCTYPE statement of the deployment plan to determine which DTD it follows.
If you specify Novell exteNd 5.x as the server type:

Whether your project's J2EE version is 1.2 or 1.3, you always get a 1.3 deployment plan for your project type.

For more information For details, see exteNd Application Server Deployment Plan DTDs.

When creating JSP tag libraries

You can use the Tag Handler Wizard to develop a new or existing JSP tag library. If you ask to create a new tag library, the wizard requires you to specify which JSP version (1.1 or 1.2) to support in it.

To start the Tag Handler Wizard, you select File>New>File and choose Tag handler. It then prompts for several panels of information, including details about the tag library descriptor (TLD) file. The JSP version is one of those details (for a new TLD file):

JVERtaglib

Your JSP version choice is recorded in the TLD file via the jsp-version element. This choice also determines which DTD is used for the TLD file:

JSP version	TLD DTD
1.1	web-jsptaglibrary_1_1.dtd
1.2	web-jsptaglibrary_1_2.dtd

WAR 2.3 projects support both JSP 1.1 and 1.2 tag libraries (although JSP 1.2 is recommended). WAR 2.2 projects support only JSP 1.1 tag libraries.

When creating EJB entity beans

You can use the EJB Wizard to add various kinds of Enterprise JavaBeans to an EJB project. That includes entity beans using container-managed persistence, with a choice of 1.x or 2.x CMP.

To start the EJB Wizard, you select File>New>File and choose EJB as the component to create. It then prompts for the kind of EJB you want:

JVERcmpejb

For an EJB 2.0 project, you can choose either version of CMP entity bean (although 2.x CMP is recommended). Your CMP version choice is recorded in the project's deployment descriptor via the cmp-version element.

EJB 1.1 projects support only 1.x CMP.

Migrating projects from J2EE 1.2 to 1.3

The exteNd Director development environment provides an Update Project Version command that you can select to migrate an existing J2EE 1.2 project to 1.3. For most kinds of projects, this command does the entire migration for you. In a few cases, it will notify you about additional migration tasks that you need to perform manually. The development environment also provides a command for when you just want to update an exteNd deployment plan from J2EE 1.2 to 1.3.

If you have one or more projects to migrate, read the following topics:

Using the Update Project Version command

This section describes the steps to follow once you've decided to migrate a project. For background information on when and what to migrate, see these earlier sections:

Procedure To migrate a project:

In the development environment, open a J2EE archive project (EAR, WAR, EJB, or CAR) that you want to migrate.
On the Project tab of the Navigation Pane, right-click the project (SPF) file to display the popup menu.
Select Update Project Version.

First, the update utility checks the J2EE version of your selected SPF file. If it is already set to J2EE 1.3, the update utility notifies you, asking if you want to proceed. Migrating such a project can make sense if it includes J2EE 1.2 items (deployment descriptors, deployment plans, or subprojects) that you want to update to 1.3. The update utility will migrate just those items that need it.

Once past the SPF check, the update utility prompts you for confirmation before migrating the project. Files that are modified during the migration will be backed up first only if you have enabled backup in your development environment preferences.

For information about enabling backup, see Backup preferences.
Click Yes to start the migration.

The update utility migrates the project from J2EE 1.2 to 1.3, then displays status information about:
- Changes it made to the project
- Unresolved issues (if any) that require you to make some manual changes to the project
This status information appears on the Output tab of the Output Pane. For example:

If you migrate an EAR project, the update utility automatically migrates the J2EE archive subprojects (WARs, EJBs, and CARs) that the EAR contains as well. The update utility includes details about these migrations in the status information it displays:

How migration affects a project When a project is migrated, the update utility makes changes in several places to reflect the new J2EE version:

In this part of the project	Migration affects
Project (SPF) file	The following project settings: The j2eeVersion and moduleVersion attributes in the SPF file. When you migrate, the update utility sets these to J2EE 1.3 values. For example: j2eeVersion="j2ee 1.3" moduleVersion="war 2.3" The project classpath entry for the JAR file that provides the J2EE API packages (needed for compiling). When you migrate, the update utility sets this to: j2ee_api_1_3.jar
Deployment descriptor	The following descriptor items: DOCTYPE statement. When you migrate, the update utility edits it to use the 1.3 deployment descriptor DTD for your project type: EAR, WAR, EJB, or CAR. The cmp-version element for entity beans using container-managed persistence. When you migrate an EJB project, the update utility adds this element for each CMP entity bean, specifying the version as 1.x. The res-auth element for WARs. When you migrate a WAR project, the update utility finds any of these that use 1.2 constant values (SERVLET or CONTAINER) and edits them to use the 1.3 equivalents (Application or Container). See J2EE Deployment Descriptor DTDs. (Note that deployment descriptors are not updated for deploy-only projects because their archive contents are static.)
Deployment plan, if present (for exteNd Application Server)	The following plan items: DOCTYPE statement. When you migrate, the update utility edits it to use the 1.3 deployment plan DTD for your project type: EAR, WAR, EJB, or CAR. EJB plan structure. When you migrate an EJB project, the update utility restructures the deployment plan in accordance with the 1.3 deployment plan DTD (which has changed significantly to support EJB 2.0 features). One major change involves persistenceInfo, a new element for deployment details about entity beans using container-managed persistence. The update utility moves existing field mapping information for CMP entity beans into this element. EAR plan structure. When you migrate an EAR project, the update utility restructures the deployment plan in accordance with the EJB changes described above. See exteNd Application Server Deployment Plan DTDs.

In this part of the project

Migration affects

Project (SPF) file

The following project settings:

The j2eeVersion and moduleVersion attributes in the SPF file. When you migrate, the update utility sets these to J2EE 1.3 values. For example:
```
  j2eeVersion="j2ee 1.3" moduleVersion="war 2.3"
```
The project classpath entry for the JAR file that provides the J2EE API packages (needed for compiling). When you migrate, the update utility sets this to:
```
  j2ee_api_1_3.jar
```

Deployment descriptor

The following descriptor items:

DOCTYPE statement. When you migrate, the update utility edits it to use the 1.3 deployment descriptor DTD for your project type: EAR, WAR, EJB, or CAR.
The cmp-version element for entity beans using container-managed persistence. When you migrate an EJB project, the update utility adds this element for each CMP entity bean, specifying the version as 1.x.
The res-auth element for WARs. When you migrate a WAR project, the update utility finds any of these that use 1.2 constant values (SERVLET or CONTAINER) and edits them to use the 1.3 equivalents (Application or Container).

For more information See J2EE Deployment Descriptor DTDs.

(Note that deployment descriptors are not updated for deploy-only projects because their archive contents are static.)

Deployment plan, if present (for exteNd Application Server)

The following plan items:

DOCTYPE statement. When you migrate, the update utility edits it to use the 1.3 deployment plan DTD for your project type: EAR, WAR, EJB, or CAR.
EJB plan structure. When you migrate an EJB project, the update utility restructures the deployment plan in accordance with the 1.3 deployment plan DTD (which has changed significantly to support EJB 2.0 features).

One major change involves persistenceInfo, a new element for deployment details about entity beans using container-managed persistence. The update utility moves existing field mapping information for CMP entity beans into this element.
EAR plan structure. When you migrate an EAR project, the update utility restructures the deployment plan in accordance with the EJB changes described above.

For more information See exteNd Application Server Deployment Plan DTDs.

Using the Update Deployment Plan Version command

In addition to the Update Project Version command, the exteNd Director development environment provides an Update Deployment Plan Version command on the popup menu for a J2EE project (SPF file). Update Deployment Plan Version works just like Update Project Version except that it only updates the project's exteNd deployment plan.

Update Deployment Plan Version is useful when you want to deploy J2EE 1.2 projects (including deploy-only projects) to Novell exteNd Application Server 5.x, which requires 1.3 deployment plans. When you invoke this command, it migrates the deployment plans of those projects from 1.2 to 1.3 format, but leaves other project characteristics unchanged.

Projects that require some manual migration

When you use the Update Project Version command or the Update Deployment Plan Version command to migrate certain kinds of projects, the update utility may not be able to resolve all issues automatically. In that case, it displays information about changes you need to make to the project yourself.

The need for manual migration typically occurs with EJB and EAR projects containing CMP entity beans. While updating exteNd deployment plans for such projects, the update utility does not handle some items, including:

Complex CMP fields
CMP fields that map to foreign beans
Database profiles for persistence information

You should edit the updated deployment plan to specify these items and check for any other changes that may be needed.

exteNd Application Server considerations

This section presents J2EE version issues specific to the exteNd Application Server (specifically, Novell exteNd Application Server 5.x and SilverStream eXtend Application Server 4.x). It includes some details on the server's implementation of J2EE 1.2 and 1.3 that may help you make decisions about deploying and migrating projects:

About the J2EE containers

The 4.x and 5.x servers are compatible with J2EE 1.3. To implement this support, they provide J2EE 1.3 versions of the Web, client, and EJB containers:

The Web and client containers for J2EE 1.3 are used when you deploy J2EE 1.3 projects (WAR 2.3, CAR 1.3) as well as J2EE 1.2 projects (WAR 2.2, CAR 1.2).
The EJB container for J2EE 1.3 is used when you deploy J2EE 1.3 projects (EJB 2.0) and, in normal cases, when you deploy J2EE 1.2 projects (EJB 1.1).

Because of container implementation changes introduced to support EJB 2.0, some EJB 1.1 deployments can't use the J2EE 1.3 version of the EJB container. For these scenarios, the 4.x server also provides a J2EE 1.2 version of this container. In the 5.x server, that older EJB container is no longer provided, so you'll need to adjust such projects before deploying.

Deploying projects

The following table summarizes the possible project deployment scenarios and shows which version of the appropriate container is used in each case:

Project	Deployment plan	Container
WAR 2.2	WAR 2.2 (4.x server only)	J2EE 1.3 Web container
WAR 2.2	WAR 2.3	J2EE 1.3 Web container
WAR 2.3	WAR 2.3	J2EE 1.3 Web container
CAR 1.2	CAR 1.2 (4.x server only)	J2EE 1.3 client container
CAR 1.2	CAR 1.3	J2EE 1.3 client container
CAR 1.3	CAR 1.3	J2EE 1.3 client container
EJB 1.1	EJB 1.1 (4.x server only)	J2EE 1.2 EJB container
EJB 1.1	EJB 2.0 (for limitations, see EJB deployment notes)	J2EE 1.3 EJB container
EJB 2.0	EJB 2.0 (for limitations, see EJB deployment notes)	J2EE 1.3 EJB container
EAR 1.2	EAR 1.2 (4.x server only)	J2EE 1.3 Web container J2EE 1.3 client container J2EE 1.2 EJB container
EAR 1.2	EAR 1.3 (for limitations, see EJB deployment notes)	J2EE 1.3 Web container J2EE 1.3 client container J2EE 1.3 EJB container
EAR 1.3	EAR 1.3 (for limitations, see EJB deployment notes)	J2EE 1.3 Web container J2EE 1.3 client container J2EE 1.3 EJB container
RAR 1.0	RAR 1.0	J2EE 1.3 containers

EJB deployment notes

In some situations, you may want (or need) to deploy an EJB 1.1 project to the J2EE 1.3 EJB container. One reason is that this lets you take advantage of performance improvements and other implementation enhancements introduced with the newer container version.

For EJB 1.1 projects containing session beans or BMP entity beans, you just need to create an EJB 2.0 deployment plan or include the project in a J2EE 1.3 EAR deployment. No other modifications to the project are required. This simple approach is not possible for EJB 1.1 projects that contain CMP entity beans and use SilverStream extensions to specify CMP details (such as expressions, foreign bean mappings, and complex fields). These extensions are supported by the EJB 1.1 deployment plan, but not the 2.0 plan.

There are also some limitations to note for EJB 2.0 projects containing CMP entity beans. In such projects, beans with 1.x CMP can't use elements specific to EJB 2.0 (such as abstract schema names, local interfaces, and queries). In addition, these beans can't use SilverStream extensions to specify CMP details (because, as mentioned above, the EJB 2.0 deployment plan doesn't support them).