IBM Rational Application Developer for Windows and Linux, Version 6.0 Migration Guide
Chapter 1. Migrating from WebSphere Studio V5.1, 5.1.1, or 5.1.2
Chapter 2. Updating Faces runtime resources for Web projects from Rational Application Developer V6.0
Chapter 3. Updating Faces runtime resources for portlet projects from Rational Application Developer V6.0
Chapter 4. Migrating J2EE projects
Chapter 5. Migrating to the portal tools in Rational Application Developer V6.0
Chapter 6. Changes in WebSphere test environments
This documentation provides instructions for migrating from
WebSphere(R) Studio Application Developer V5.1.x to
Rational(R) Application Developer V6.0.
Additional information can be found on the following topics:
Information about using Rational Application Developer can be found in the
online help.
Refer to www.ibm.com/developerworks/rational
for updated documentation.
For information on migrating from prior versions of WebSphere Studio to
v5.x or migrating from VisualAge(R) for Java(TM) to WebSphere
Studio, go to www.ibm.com/software/awdtools/studioappdev/support/
and search for "migration guide".
To migrate from WebSphere Studio V5.1.x:
- Before installing, read about compatibility
with Eclipse V2.x and WebSphere Studio V5.1.x.
Note that backward compatibility is not supported for portlet application
projects migrated from Portal Toolkit V5.0.2.2 with
WebSphere Studio V5.1.2.
- Back up your WebSphere Studio V5.1.x workspace.
- Install Rational Application Developer. Refer to the
Installation Guide (install.html file) which is available at
the root of the first product CD.
- Recommended: By default, the first time you start
Rational Application Developer, you are prompted to confirm that you want to
use a workspace called rationalsdp6.0\workspace. That is, the
Workspace Launcher dialog box points to a directory that is not your WebSphere
Studio workspace. To explore the new environment before migrating your
old workspace, accept the default or specify some other new directory name
when you start Rational Application Developer. You might do this, for
example, so you can create one or two test projects, read about what's
new (Help -> Welcome), do some of the new
tutorials (Help -> Tutorials Gallery), or
experiment with some of the new samples (Help -> Samples
Gallery).
- Migrate your projects to V6.0. Projects created in WebSphere
Studio V5.1.x can be automatically migrated to V6.0 as
follows:
- Migrating a workspace: When you are ready to migrate your
V5.1.x workspace for good, start Rational Application Developer
with your old workspace. A progress indicator confirms that your
projects are being automatically migrated.
Notes: During workspace migration a Problems
dialog box opens with the message Could not restore workbench
layout. Reason: Problems occurred restoring
workbench. The error messages have no impact on the successful
migration of the workspace. Note the name of perspective that could not
be restored by clicking the Details button in the error dialog box,
then click OK to close the dialog box.
To restore the perspective:
- Close the perspective by selecting Window -> Close
Perspective
- Reopen the perspective by selecting Window -> Open
Perspective.
- Note:
- For Enterprise Generation Language (EGL) projects that used EGL Web
perspective in WebSphere Studio V5.1.2: this
perspective has been removed in Rational Application Developer
V6.0. All EGL projects are safely migrated without this
perspective in Rational Application Developer V6.0. Do the
following if you used the EGL Web perspective:
- Close the EGL Web perspective.
- Enable EGL capabilities in the Preferences (Window ->
Preferences). Refer to the online help for details on
enabling EGL capabilities.
- Select Window -> Open Perspective and choose
the Web perspective.
- Migrating projects loaded from a SCM (source code management)
system: Projects from WebSphere Studio 5.1.x that
exist in a SCM system are automatically migrated to V6.0 when they are
loaded into Rational Application Developer.
- Migrating projects imported using Project Interchange:
Projects exported from WebSphere Studio V5.1.2 or
V5.1.1 and imported into Rational Application Developer
V6.0 using the Project Interchange feature are automatically migrated
to V6.0. The Project Interchange feature was available in
WebSphere Studio V5.1.2 and was an optional plug-in for
V5.1.1.
Notes:
- If you used the Portal Toolkit V5.0.2.2 with
WebSphere Studio V5.1.2 to develop portlet projects, your
workspace will be automatically migrated to be compatible with Rational
Application Developer. See Chapter 5, Migrating to the portal tools in Rational Application Developer V6.0 for more information.
- For each V5.1.x project migrated to V6.0, the
migration program automatically adds a
.compatibility file to the project folder in V6.0. This
file is used for the purpose of backward compatibility with WebSphere Studio
V5.1.x. Do not edit or delete this file. Refer to
the section on compatibility with WebSphere
Studio V5.1.x for more information.
Important:
- If there are debug launch configurations associated with the workspace you
are migrating, you should note that some launch configuration will not migrate
automatically. For information on how to restore launch configurations
to a migrated workspace, refer to Debugger changes in V6.0.
- If you used the XSLT debugger or EGL debugger on projects in your migrated
workspace, you will need to change the Java runtime environment (JRE) that is
installed with Rational Application Developer V6.0. Refer to Debugger changes in V6.0 for details on how to make this change.
- If you have programs developed using the Enterprise Generation Language
that were migrated to V6.0, you should note that there are new reserved
words for EGL in version 6.0. If you use these words as variable
or part names you will need to change them. Refer to EGL reserved words in V6.0
- The DB2(R) Net JDBC Driver is not supported in Rational Application
Developer V6.0. If you created JDBC connections using the DB2
Net JDBC Driver, you will not be able to reconnect in Rational Application
Developer V6.0. You will need to change the connection to use
one of the supported JDBC drivers. Refer to the online help for more
information on the JDBC drivers supported in V6.0.
- If you have Web or XML file content migrated from WebSphere Studio
Application Developer V5.1.x that used the Shift_JIS character
set and included vendor selected characters, you must specify the Windows-31J
character set instead.
- If you installed any vendor plug-ins with WebSphere Studio Application
Developer V5.1.x, you need to get the corresponding plug-ins for
V6.0 and reinstall them.
- If you installed any back-level WebSphere V5.x unit test
environments when you installed Rational Application Developer, and if you use
the embedded messaging service, upgrade it by installing the version provided
with Rational Application Developer. Refer to the installation
guide for details on installing the embedded messaging service.
- If you use features that require Agent Controller, upgrade it by
installing the version provided with Rational Application Developer.
For details, refer to the installation guide.
- To migrate from VisualAge Generator, consult the VisualAge Generator
to Enterprise Generation Language (EGL) Migration Guide that is
available in PDF format in the "Installing and migrating" section of the
online help under the help topic "Accessing the VisualAge Generator to EGL
Migration Guide." The most recent copy can be obtained from http://www.ibm.com/developerworks/rational/library/egldoc.html.
When you first open any WebSphere Studio V5.1.x workspace in
Rational Application Developer, it is automatically migrated. Once you
have migrated a workspace, you can no longer open it in WebSphere Studio
Application Developer. However, the projects in the V6.0
workspace can still be shared with WebSphere Studio V5.1.x,
either by using a source code management (SCM) system (such as Rational
ClearCase(R)), by importing and exporting the project using Project
Interchange, or through importing archives and exporting projects.
Important: portlet applications from Portal Toolkit
V5.0.2.2 that are migrated to Portal Tools in Rational
Application Developer V6.0 will not be backward compatible.
- Note:
- The following does not apply to portlet application projects.
Existing V5.1.x projects that are loaded into V6.0
from a SCM system or another developer using Project Interchange will be
compatible for sharing with V5.1.x provided you do
not take any the following actions:
- Alter the compatibility metadata that is added to the .project file
and the
.compatiblity file created by the migration tool.
- Delete the
.compatibility file from those projects.
- Perform "Remove Compatibility" on an enterprise application project (if
the enterprise application or any of its modules or utility projects must be
compatible with WebSphere Studio Application Developer
V5.1.x).
A .compatibility file is automatically created in the project
directory when a V5.1.x project is opened in the Rational
Application Developer V6.0 workspace. The .compatibility
file is used by Rational Application Developer to track the timestamps of
project resources when these resources are migrated. You should not
edit or delete it.
For information on disabling compatibility with WebSphere Studio
Application Developer V5.1.x, refer to Disabling compatibility with WebSphere Studio V5.1.x.
Eclipse considerations
This version of Rational Application Developer is based on Eclipse
V3.0. If you develop your own plug-ins, you should read about
changes to the platform before migrating.
For details, refer to the readme file in the sub-directory
eclipse\readme of the installation location of Rational Application Developer
V6.0. The sections of the readme file that are of interest for
migration are:
- Compatibility with Previous Releases
- Upgrading Workspace from a Previous Release
- Interoperability with Previous Releases
J2EE project compatibility
Compatibility of projects created in WebSphere Studio V5.1.x
with Rational Application Developer V6.0 is enabled by means of
metadata that is automatically added to .project files when you migrate
your V5.1.x workspace. Similarly, if you create a new
J2EE 1.2 or 1.3 module or application in Rational Application
Developer V6.0, build metadata is automatically added to the
.project file for compatibility with V5.1.x. Do
not edit or delete this information directly.
- Note:
- This compatibility metadata will cause messages about "missing builders" to
be displayed or logged when a new J2EE 1.2 and J2EE 1.3 module
or application created in V6.0 is used in WebSphere Studio Application
Developer V5.1.x where the V6.0 builders are not
available. These messages are normal; you can ignore them.
As long as this compatibility metadata is present, you will messages about
"missing builders" when Rational Application Developer V6.0 projects
are loaded back in WebSphere Studio V5.1.x. The following
is an example of a "missing builder" message:
!ENTRY org.eclipse.core.resources 2 1 Sep 06, 2004 19:55:20.592
!MESSAGE Skipping builder com.ibm.wtp.j2ee.LibCopyBuilder for project Test60EARWeb.
Either the builder is missing from the install, or it belongs to a project nature that is missing or disabled.
These messages are normal; you can ignore them. When you are
sure you no longer need to work with a given project in WebSphere Studio
V5.1.x, you can stop the messages by disabling backward compatibility for that
project.
Important: New J2EE 1.2 or 1.3 specification
projects created in V6.0 are compatible with WebSphere Studio
V5.1.x, but once the project is loaded into WebSphere Studio
there are some manual steps that are required before you can work with the
project. These steps are required because runtime targets on new J2EE
1.2 or 1.3 specification projects created in 6.0 are not
directly backward compatible to target servers in V5.1.x.
The manual steps after loading a new V6.0 project in
V5.1.x are as follows:
- Open the .classpath file for each J2EE project that has
a
.classpath file.
- Delete the following classpath entries from the .classpath file and
save and close the file.
-
<classpathentry kind="con"
path="org.eclipse.jdt.launching.JRE_CONTAINER/
org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/WebSphere v5.1 JRE"/>
-
<classpathentry kind="con"
path="com.ibm.wtp.server.java.core.container/
com.ibm.etools.websphere.runtime.core.runtimeTarget.v51/was.base.v51"/>
- Make sure server targeting support is enabled in the J2EE preferences
page. Select Window -> Preferences ->
J2EE and confirm that Enable server targeting support is
selected under "Server Targeting Support."
- Right click on the project and select Properties ->
J2EE.
- Select the corresponding target server for the runtime target on the
project (for example, WebSphere Application Server V5.1 using the JDK
1.4 runtime environment) and click OK.
- The target server you selected will be compatible for both Rational
Application Developer V6.0 and WebSphere Studio Application Developer
V5.1.x. After the changes are committed into the SCM
system, the J2EE projects are interoperable between V5.1.x and
V6.0 using a SCM system.
- Note:
- If the target server is set again in Rational Application Developer
V6.0, J2EE project compatibility will be lost and will need to be
reestablished.
UML diagram compatibility
UML diagrams that existed in WebSphere Studio Application Developer
V5.1.x are forward compatible and can be opened in read-only
mode in Rational Application Developer V6.0. In V6.0, the
J2EE Migration Wizard automatically migrates UML diagrams created in
V5.1.x J2EE projects during J2EE project structure
migration. Once migrated, the UML diagrams can be edited in Rational
Application Developer V6.0.
- Note:
- UML diagrams in a workspace migrated to or created in Rational Application
Developer V6.0 cannot be opened in WebSphere Studio Application
Developer V5.1.x.
Compatibility with WebSphere Studio Application Developer
V5.1.x can be totally removed from an enterprise application
project created in Rational Application Developer V6.0 or an enterprise
application project migrated from an earlier version of WebSphere
Studio. You should disable compatibility with WebSphere Studio
V5.1.x only if you are certain that the enterprise application
project should no longer be either interoperable or compatible with
V5.1.x.
To remove compatibility with WebSphere Studio Application Developer
V5.1.x:
- Right-click on an enterprise application project and select the
Remove Compatibility menu option from the pop up.
- A dialog box asks for confirmation to remove the backward compatibility of
the enterprise application project and all the modules and utility projects
nested under the project.
- Click Yes to continue with the Remove Compatibility
operation.
Once the Remove Compatibility operation is run, the enterprise application
project and all the module and utility projects nested under the enterprise
application project are no longer backward compatible with WebSphere Studio
Application Developer V5.1.x.
The JavaServer Faces runtime resources that originally shipped in WebSphere
Studio Application Developer V5.1.x have been updated for
Rational Application Developer V6.0.1. If you want to
continue development on Web projects that were created with this previous
product version, it is recommended that you update the Faces runtime resources
to the latest levels.
In Rational Application Developer V6.0.1, the Faces runtime
resource updates happen automatically when a Web project is imported or a
workspace is opened that contains out-of-date resources. After
importing a Web project or opening a workspace from WebSphere Studio
Application Developer V5.1.x to Rational Application Developer
V6.0.1, you will be prompted to update the Faces runtime
resources to the latest levels.
Automatically updating runtime resources
To update the Faces runtime resources automatically for a Web
project:
- Import a Web project (or a workspace) containing Faces content from
WebSphere Studio Application Developer V5.1.x. The
Project Migration window opens.
- Note:
- If the Project Migration window does not open, your automatic build
preference setting is probably disabled. In Project Explorer,
right-click your Web project and select Build ->
Project; the process of rebuilding a project opens the Project
Migration window.
- If you have other Web projects with Faces content in your workspace, check
Apply this choice to any other projects that need to be upgraded
and all your Web projects will be updated.
- Click one of the following:
- Yes to complete the update automatically.
- Later to defer the update. To update runtime resources
automatically after selecting Later, you have to close and reopen
the Web project or restart the workbench before rebuilding your Web
project. If you have disabled automatic builds, right-click your Web
project and select Build Project.
- Never to keep your runtime resources back-level. If you
choose Never and intentionally stay with the back-level runtime
resources, you will not be prompted again to update them. In the
future, you will need to update the runtime resources manually if you require
them.
- Note:
- If you created Faces JSPs that contained Faces Client components, you must
separately update the Faces Client components runtime resources to the latest
levels. Refer to Updating Faces Client runtime resources in a Web project.
Manually updating runtime resources
To update the Faces runtime resources manually for a Web
project:
- Import your existing Web project with Faces content into a Rational
Application Developer V6.0.1 workspace.
- Create a new Web project (or, if you are working with EGL, create a new
EGL Web project) named JSF601. You will use this project
only as a source for the latest runtime resources; it can be deleted
after the update is complete.
- In the Project Explorer, right-click on the JSF601 project and
select Properties from the menu.
- Click Web Project Features and select Add Faces Base
Components and Add Faces Client Framework, then click
OK.
- If you are working with EGL, create a JSF page file as
follows:
- Right-click the WebContent folder of your new EGL Web project.
- Select New -> Other -> Faces JSP
File.
The eglintdebug.jar and
eglintdebugsupport.jar files are added to your
project.
- For each existing Faces project that you want to update, do the
following:
- In Project Explorer, expand an existing project to show the files in the
WebContent/WEB-INF/lib/ folder. Locate and delete any of the following
JAR files in this directory:
- eglintdebug.jar (EGL only)
- eglintdebugsupport.jar (EGL only)
- fda.jar (EGL only)
- fdaj.jar (EGL only)
- jsf-api.jar
- jsf-ibm.jar
- jsf-impl.jar
- odc-jsf.jar
- Locate and open the file
WebContent/WEB-INF/faces-config.xml. Add the following elements
into this configuration file if they are not already present:
<lifecycle>
<phase-listener>com.ibm.faces.webapp.ValueResourcePhaseListener</phase-listener>
</lifecycle>
<application>
<variable-resolver>com.ibm.faces.databind.SelectItemsVarResolver</variable-resolver>
<property-resolver>com.ibm.faces.databind.SelectItemsPropResolver</property-resolver>
</application>
- For any JAR files that you deleted, copy the JAR file of the same name
from the WebContent/WEB-INF/lib directory of the JSF601 project and
paste it into your original project in the same location. Some
configurations will not require all of these JAR files to be present in the
project; do not copy a particular JAR file if it was not in the original
project.
- Open the web.xml deployment descriptor in the original project and
add the following to the configuration:
<context-param>
<param-name>com.ibm.ws.jsf.JSP_UPDATE_CHECK</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>com.ibm.ws.jsf.LOAD_FACES_CONFIG_AT_STARTUP</param-name>
<param-value>true</param-value>
</context-param>
- If your original project used WebSphere Data Objects (WDO) for any data
access, do the following additional steps:
- In your original project, click File -> New
-> Faces JSP File to create a new temporary Faces JSP
file.
- Drag a relational record list component from the Data drawer on the
palette to the page.
- Pick any connection and data source and click Finish.
The data selected is not important. This process will generate any
necessary configuration to continue using WDO in this project.
- Delete the temporary JSP file.
- If you are working with EGL, right click on the name of each
EGL Web project and click Generate; then, if you are not
building the projects automatically, click Project ->
Build All.
- Delete the JSF601 Web project.
The JavaServer Faces Client runtime resources that originally shipped in
WebSphere Studio Application Developer V5.1.x have been updated
for Rational Application Developer V6.0.1. If you want to
continue development on Web projects that were created with this previous
product version, it is recommended that you update the Faces Client runtime
resources to the latest levels.
In Rational Application Developer V6.0.1, the Faces Client
runtime resource updates happen automatically when a Web project is imported
or a workspace is opened that contains out-of-date resources. After
importing a Web project or opening a workspace from WebSphere Studio
Application Developer V5.1.x to Rational Application Developer
V6.0.1, you will be prompted to update the Faces Client runtime
resources to the latest levels.
Automatically updating runtime resources
To update the Faces Client runtime resources automatically for a
Web project:
- Import a Web project (or a workspace) containing Faces Client content from
WebSphere Studio Application Developer V5.1.x. The
Project Migration window opens.
- Note:
- If the Project Migration window does not open, your automatic build
preference setting is probably disabled. In Project Explorer,
right-click your Web project and select Build ->
Project; the process of rebuilding a project opens the Project
Migration window.
- If you have other Web projects with Faces Client content in your
workspace, check Apply this choice to any other projects that need to be
upgraded and all your Web projects will be updated.
- Click one of the following:
- Yes to complete the update automatically.
- Later to defer the update. To update runtime resources
automatically after selecting Later, you have to close and reopen
the Web project or restart the workbench before rebuilding your Web
project. If you have disabled automatic builds, right-click your Web
project and select Build Project.
- Never to keep your runtime resources back-level. If you
choose Never and intentionally stay with the back-level runtime
resources, you will not be prompted again to update them. In the
future, you will need to update the runtime resources manually if you require
them.
- From the Java Resources -> JavaSource folder
in your Web project, delete all client data mediator class packages with the
naming convention
com.ibm.dynwdo4jsmediators.<client-data-name>.
Do not delete the package named
com.ibm.dynwdo4jsmediators. This package contains
metadata (ecore and emap files) for the client data in your project that will
be used to regenerate the mediators.
- From the Java Resources -> JavaSource folder
in your Web project, open the OdysseyBrowserFramework.properties file
and delete the entries for EMAP_FILES and
ECORE_FILES.
- For each data object in the Client Data view:
- Right-click and select Configure.
- On the Advanced tab, click Regenerate from server-side
data to regenerate all mediators for the data object.
Manually updating runtime resources
To update the Faces Client runtime resources manually for a Web
project:
- Complete the Manually updating runtime resources steps in Updating Faces runtime resources in a Web project.
- Complete steps 4-6 of the Automatically updating runtime
resources section above.
Problems may occur when changing the target server of a project
containing Faces Client components from WebSphere Application Server
V5.1 to V6.0.
There are two problems that may occur when changing the target server of a
project containing Faces Client components from WebSphere Application Server
V5.1 to V6.0:
- Client data mediator classes that have already been generated will no
longer compile. They need to be regenerated one JSP at a
time::
- Open the OdysseyBrowserFramework.properties file found in the root
Java source folder. Save the contents for future use.
- In the OdysseyBrowserFramework.properties file, for each JSP in
your Web project containing Faces client data, find the
<client-data-name>.ecore and <client-data-name>.emap
entries for properties EMAP_FILES and ECORE_FILES.
- Keep only the matching entries for the client data on your JSP, and delete
all other entries.
For example, if your current page has a Client Data called ACCOUNT, and
your properties file had entry like:
EMAP_FILES=com\\ibm\\dynwdo4jsmediators/account.emap com\\ibm\\dynwdo4jsmediators/orders.emap
you should delete
com\\ibm\\dynwdo4jsmediators/orders.emap from the
entry. The entry would now appear as:
EMAP_FILES=com\\ibm\\dynwdo4jsmediators/account.emap
- Save the properties file.
- Select a client data object in a JSP then right-click and select
Configure.
- On the Advanced tab, click Regenerate All.
This will regenerate all the artifacts needed for all client data on the
current JSP.
- Repeat these steps 2-6 for each JSP containing client data in your Web
project.
- After regenerating the client data mediator classes, there will still be
some mediator classes left that will not compile. These are mediators
for schema elements no longer used in Service Data Objects (SDOs) in
V6.x and have the naming convention
*_DataGraphSchema_wdo4js_*.java and
*_RootDataObject_wdo4js_*.java. Delete these mediator classes
from your Web project to prevent these compile errors.
- After the update completes successfully, restore the original contents of
the OdysseyBrowserFramework.properties file.
- Tree view Faces Client components bound to WDOs fail to run on the server
after changing the project's target server to WebSphere Application
Server V6.0. The workaround is to modify the source view of your
JSP to change all className tags to use SDO DataObject class instead of WDO
DataObject class. For example, for a WDO named
account:
- For the root object, change the className tag from
className="com.ibm.etools.wdo.DataObject(DynWDO`account`RootDataObject)"
to
className="commonj.sdo.DataObject(DynWDO`account`DataGraphRoot)".
- For all child nodes, change the className tag from
className="com.ibm.etools.wdo.DataObject(DynWDO`account`ACCOUNT)"
to
className="commonj.sdo.DataObject(DynWDO`account`ACCOUNT)",
where ACCOUNT is the name of the data node.
Upgrading to automated Diff handlers and processors
Diff processors and handlers are now automatically generated. If you
wrote Diff handlers and processors for your Faces Client components in
WebSphere Studio V5.1.x, it is recommended that you discard that
code and use the automatically generated processors and handlers:
- Generate the new Diff handlers and processors on each client data object
in your Web project.
- Select the client data object, right-click and select
Configure.
- On the Advanced tab, click Regenerate All.
- Remove the code you wrote to invoke your Diff processor and handlers since
the generated processors and handlers are invoked automatically. A
typical example of where this code was used would be for the Command event for
the Command Button component, as such:
String Diff = getClientData1().getDiffStr();
if (DiffProcessor.Synch(getRoot(), Diff) == true)
return "";
return "failure";
- Remove the files corresponding to the old custom handlers and processors
you created from your Web project.
Keeping custom Diff handlers and processors written for
V5.1.x
Although this is not recommended, if you decide you need to keep your
custom Diff handlers and processors from V5.1.x, they will need
to be modified in order to work in V6.0, as the DiffHandler interface
and DiffInfo class have changed.
- The DiffHandler interface has changed as follows:
- The handle method now throws Exception in addition to
DiffException.
- The new find method is used by the framework to find objects.
- The new getId method is used for debugging and allows the framework to
print the value of an object.
The find and getId methods are used internally by the generated
DiffHandlers. For your custom DiffHandlers, you can implement empty
methods just to comply with the interface. Those methods will not be
called by the framework.
The DiffHandler interface is now:
public interface DiffHandler
{
public void handle(DiffInfo Diff) throws DiffException, Exception;
public Object find (DiffInfo Diff) throws DiffException, Exception;
public String getId (DiffInfo Diff, boolean Original);
}
- The DiffInfo class has changed as follows:
- The method ArrayList getAncestors() has been replaced by the method
DiffInfo getParent(), which provides an easier way to access the information
for each object in the ancestor tree in a recursive manner.
- The methods getCurrent() and getOriginal() now return a DataObject object
instead of an EObject object. It is not mandatory that you change your
code to use the DataObject object. However, the DataObject interface is
much easier and more intuitive to use than EObject. You can easily cast
a DataObject object to an EObject object for existing code.
- A new method String getPropertyName() was added to identify the property
name for which this object applies. This is important if, for example,
a given class has two properties of the same type. Previously in the
DiffInfo class, the code would have been unable to differentiate between the
two properties.
The DiffInfo class is now:
public class DiffInfo
{
public char getCrud()
public DataObject getCurrent()
public String getEClassName()
public DataObject getOriginal()
public String getPropertyName()
public DiffInfo getParent()
}
- Note:
- The DiffInfo class is no longer supported for public use as Diff processors
and handlers are now automatically generated. Keeping your old handlers
is only a temporary solution and it is strongly advised that automated
handlers be used.
Changes to Faces Client components in V6.0
- Support for WebSphere Application Server V6.0.
- Support for Service Data Objects (SDO) on WebSphere Application Server
V6.0.
- EGL data is now supported as client data.
- Diff processors and handlers are automatically generated.
- There are new events for the following components:
- TabbedPanel: onInitialPageShow
- Tree: onNodeExpand, onNodeCollapse, onExpand, onCollapse
- DataGrid: onPage, onSort, onFilter
For Struts Web projects created in WebSphere Studio V5.1.x,
you must make a small modification to the Web project's deployment
descriptor in order to run the EAR project on WebSphere Application Server
V6.0. You may also wish to manually convert existing Struts
1.0.2 or Struts 1.1 Beta (2 or 3) Web projects to Struts
1.1.
Modifying the deployment descriptor of existing Struts Web
Projects
When a Struts project is created in WebSphere Studio v5.x, the
config parameter (<param-name>config</param-name>) in the web
project's deployment descriptor is set to
WEB-INF/struts-config.xml. WebSphere Application Server
V6.0 requires that a leading "/" be present in this parameter.
If you run a Struts Web project that was created in WebSphere Studio
V5.1.x on WebSphere Application Server V6.0, you may
receive a java.net.MalformedURLException exception upon starting
the EAR project.
- Note:
- Rational Application Developer V6.0 will add the "/" when a new Struts
project is created; however, it must be added manually when migrating
from WebSphere Studio V5.1x.
Follow these steps to correct in V6.0 the deployment descriptor of a
Struts Web project that was created in WebSphere Studio
v5.1.x:
- Open the Struts Web project in the Project Explorer.
- Double-click the Web project's Web Deployment Descriptor
file in the Project Explorer. The Web deployment descriptor editor
opens.
- Click the Source tab to open the Source page.
- Change the line
<param-value>WEB-INF/struts-config.xml</param-value>
(this is located within the <servlet></servlet> tags)
to
<param-value>/WEB-INF/struts-config.xml</param-value>
.
- Save the Web Deployment Descriptor
The java.net.MalformedURLException exception should not occur
when the EAR project is restarted.
Converting Struts 1.1 Beta Web projects to Struts
1.1
In WebSphere Studio V5.1.x, the Struts runtime library
stepped up from Struts 1.1 Beta (2 or 3) in V5.0.x to
Struts 1.1 (final). If you have existing Struts 1.1 Beta
(2 or 3) Web projects and you want to convert them to Struts 1.1
(final), you may convert them manually. (Note: it is
not required that you convert Struts 1.1 Beta (2 or 3) projects to
Struts 1.1. )
To convert Struts 1.1 Beta (2 or 3) projects to Struts 1.1,
do the following:
- Load your Struts 1.1 Beta projects into a Rational Application
Developer V6.0 workspace.
- Create a new Struts 1.1 Web project named, for example,
Struts11. You create this temporary project in order to
provide convenient access to the Struts 1.1 runtime files you will need
while you are converting your real projects. You can delete this
project when you are done.
- For each Struts 1.1 Beta project that you want to convert to Struts
1.1, do the following:
- Delete the following JAR files from your project's Web
Content/WEB-INF/lib directory:
- commons-*.jar.
- struts.jar.
- Copy the following JAR files from Struts11/WebContent/WEB-INF/lib
directory to your project's Web Content/WEB-INF/lib directory:
- commons-*.jar.
- struts.jar.
- Delete the following Tag Library Descriptor (TLD) files from your
project's Web Content/WEB-INF directory:
struts-*.tld.
- Copy the following TLD files from Struts11/WebContent/WEB-INF directory to
your project's Web Content/WEB-INF directory:
struts-*.tld.
Converting Struts 1.0.2 Web projects to Struts
1.1
In WebSphere Studio V5.1.x (and V5.0.x), when
adding Struts support to a Web project you had the option to choose Struts
1.0.2. If you have existing Struts 1.0.2
Web projects and you want to convert them to Struts 1.1, you may
convert them manually. (Note: it is not required that
you convert Struts 1.1 Beta (2 or 3) projects to Struts
1.1. )
To convert Struts 1.0.2 projects to Struts 1.1, do the
following:
- Load your Struts 1.0.2 projects into a Rational Application
Developer V6.0 workspace.
- Create a new Struts 1.1 Web project named, for example,
Struts11. You create this temporary project in order to
provide convenient access to the Struts 1.1 runtime files you will need
while you are converting your real projects. You can delete this
project when you are done.
- For each Struts 1.0.2 project that you want to convert to
Struts 1.1, do the following:
- Delete the struts.jar file from your project's Web
Content/WEB-INF/lib directory.
- Copy the following JAR files from the Struts11/WebContent/WEB-INF/lib
directory to your project's Web Content/WEB-INF/lib directory:
- commons-*.jar.
- struts.jar.
- jarkarta-oro.jar.
- Delete the following Tag Library Descriptor (TLD) files from your
project's Web Content/WEB-INF directory:
struts-*.tld.
- Copy the following TLD files from Struts11/WebContent/WEB-INF directory to
your project's Web Content/WEB-INF directory:
struts-*.tld.
There are a number of changes to the debugging tools in Rational
Application Developer V6.0. You will need to be aware of these
changes in order to use these tools with your projects following
migration. You may need to change or restore settings.
Migrating workspaces and launch configurations
When a V5.1.x workspace from WebSphere Studio Application
Developer is opened in Rational Application Developer V6.0, the
following debugger launch configurations associated with the workspace will
not automatically migrate:
- Debug on Server: Launch configurations that were
previously created via the Debug on Server action will not migrate to
V6.0. To launch an application for debugging on a server in
V6.0, reselect the application and choose Debug on
Server. This will create a new launch configuration for the
application.
- Server Attach: WebSphere Application Server debug launch
configurations that were previously created for a server attach will not
migrate to V6.0. The WebSphere Application Server debug launch
configuration no longer exists. To perform a server attach for
debugging in V6.0, use the Debug on Server action and create
a WebSphere V5 server attach for 5.x or a WebSphere V6.0 server
attach for 6.0.
- SQLJ debugger: The SQLJ debug launch configuration no
longer exists and SQLJ launch configurations that were previously created will
not migrate to V6.0. To launch SQLJ programs for debugging in
V6.0, use the Java Application launch configuration.
- Stored Procedure debugger: Stored procedure debugger
launch configurations that were previously created will migrate to Rational
Application Developer V6.0 and be available for use in the
Debug launch configurations dialog box. After migrating, if
you use the Debug action in the Data Definition view
pop-up menu, a new launch configuration will be created for you.
- Note:
- If you migrate a workspace containing a stored procedure and then rebuild the
stored procedure for debugging, migrated launch configurations associated with
the stored procedure will not work.
- EGL debugger: After migrating a workspace, the following
steps must be performed for existing EGL debugger launch configurations:
- Modify the installed Java runtime environment (JRE) to point to the
correct location. After migrating a workspace, its installed JRE will
point to the JRE from the previous version of WebSphere Studio Application
Developer. To change this, point to the new JRE location as
follows:
- Select Window -> Preferences from the
workbench menu.
- In the resulting Preferences dialog, expand the Java node and
then select Installed JREs.
- On the right-hand side, set the installed JRE to point to the JRE that has
been installed with the current version of this product. The location
of the JRE is the subdirectory \eclipse\jre of the installation directory of
Rational Application Developer V6.0.
- In the launch configuration, select the Source tab prior to
launching (failing to do this will result in a "source not found"
error). If you had added source locations to the launch configuration
in the V5.1.x workspace, you will need to manually add these
locations back to the migrated launch configuration.
- Compiled Language debugger: After migrating a workspace,
the following steps need to be performed for existing compiled language
debugger launch configurations:
- If you had set environment variables in the System Environment
tab of the Compiled Application launch configuration, you will need
to manually add them back to the migrated launch configuration.
- If you had added source locations to the Compiled Application
or Attach to a running process launch configurations, you will need
to manually add them back to the migrated launch configuration.
Debug views
The Storage and Storage Mapping views no longer exist. They have
been replaced by the Memory and Memory Rendering views.
The XSLT debugger
The XSLT debugger has changed in V6.0 and many of its views and
actions have changed significantly. For further information, see the
XSLT debugger documentation in the information center.
One of the most significant changes in the XSLT debugger is its dependency
on the JRE that is installed with Rational Application Developer
V6.0. If you migrate a workspace from WebSphere Studio
Application Developer V5.1.x, you will need to modify the
installed JRE to point to the correct location before you can launch an XSLT
debug session for it. To do this, you can perform one of the following
actions:
- Change the JRE for the entire workspace by pointing it to the new JRE
location by doing the following steps:
- Select Window -> Preferences from the
workbench menu.
- In the Preferences window, expand the Java node and then select
Installed JREs.
- On the right hand side, set the installed JRE to point to the one that has
been installed with the current version of this product. The location
of the JRE is the subdirectory \eclipse\jre of the installation directory of
Rational Application Developer V6.0.
- If you intend to launch the debug session via the Debug launch
configurations dialog box, you can change the JRE for the launch configuration
by pointing it to the new JRE location. To do this, open the launch
configuration in the Debug launch configurations dialog box.
Select the JRE tab and specify the new JRE location in the
Alternate JRE field.
If you created code in a Web project targeted at WebSphere Application
Server V5.1 that used WebSphere Data Objects (WDO) relational records
or relational record lists, when you target these applications to WebSphere
Application Server V6.0 you will now use Service Data Objects (SDO)
relational records and relational record lists. The migration from WDO
to SDO happens automatically when you change the target server of your
application from WebSphere Application Server V5.1 to WebSphere
Application Server V6.0.
The target server can be changed in two ways:
- You can modify the target server using the project's properties
dialog. Right-click on the project in the Project Explorer view, and
select Properties -> Server -> Target
runtime.
- During J2EE migration using the J2EE Migration Wizard you can re-target
the application to use another server.
- Note:
- You can only migrate to a higher J2EE specification level.
Help topics on changing your target server and using the J2EE Migration
Wizard can be found in the online help for Rational Application
Developer.
Compatibility considerations
- Any code written to the public application programming interfaces (APIs)
for the WDO access beans will be supported in V6.0 (although the
implementation classes have changed to target the SDO runtime).
- New code generated for WebSphere Application Server V6.0 will not
use the WDO access beans, but will instead generate code for the pure SDO
APIs.
- Any code generated to a project while targeted at V6.0 will not run
on a V5.1 server even if migrated back by re-targeting the
server.
- Code written for V5.1 can be migrated forward and backwards by
targeting a V5.1 server.
Type collision errors may occur following migration from WDO to SDO
After a project utilizing WDO is migrated to an SDO-based project, if you
add SDO data to an existing JSP page that has existing WDO data, type
collision errors may occur. This arises due to the mixing of existing
WDO access beans and stand-alone SDO APIs. For example, you may see a
compilation error on the Java source file of the JSP similar to the
following:
The import com.ibm.websphere.sdo.mediator.exception.MediatorException collides with another imported type
These type collision errors can be corrected as follows:
- Remove the colliding import statement from the Java source file.
Using the example above, you would remove the following import statement from
the source file:
import com.ibm.websphere.wdo.mediator.exception.MediatorException;
- Modify the Java source file that references that type to use the fully
qualified class name. Based on the example above, the type
MediatorException must be changed to
com.ibm.websphere.wdo.mediator.exception.MediatorException.
For instance, source code written as
catch ( MediatorException e1 ) {
must be changed to
catch ( com.ibm.websphere.wdo.mediator.exception.MediatorException e1 ) {
Changes to a Web project after changing the target server from
V5.1 to V6.0 (WDO to SDO)
The following changes are made automatically when the target server is
changed from V5.1 to V6.0:
- The Java archive (JAR) files wdo_web.jar and
wdo_jdbc_access.jar are removed from the project.
- The following JAR files are removed from the project's class
path:
- emf-runtime.jar
- emf-event.jar
- wdo-interface.jar
- wdo.jar
- jdbcmediator.jar
- wdo.xmlmediator.jar
- The files sdo_web.jar and sdo_access_beans.jar are added to
the project (SDO runtime JAR files are automatically added to any V6.0
project's classpath).
- Any JavaServer Pages Standard Tag Library (JSTL) 1.0 JAR files are
removed from the project. (JSTL 1.1/JSP 2.0 JAR files are
automatically added to any V6.0 project's class path).
- The following import statements are changed in any Java sourcre
files:
- com.ibm.websphere.wdo.access.connections.ConnectionManager
changes to
com.ibm.websphere.sdo.access.connections.ConnectionManager.
- com.ibm.websphere.wdo.mediator.rdb.ConnectionWrapper
changes to
com.ibm.websphere.sdo.mediator.jdbc.ConnectionWrapper.
Changes to a Web project after changing the server target from
V6.0 to V5.1 (SDO to WDO)
The following changes are made automatically when the target server is
changed from V6.0 to V5.1:
- The JAR files sdo_web.jar and sdo_access_beans.jar are
removed from the project.
- The JAR files wdo_web.jar and wdo_jdbc_access.jar are added
to the project.
- The following JAR files are added to the project's classpath:
- emf-runtime.jar
- emf-event.jar
- wdo-interface.jar
- wdo.jar
- jdbcmediator.jar
- wdo.xmlmediator.jar
- JSTL 1.0 JAR files are added to the project. (JSTL
1.1/JSP 2.0 JARs are removed from the project's class
path).
- The following import statements are changed in any Java source
files:
- com.ibm.websphere.sdo.access.connections.ConnectionManager
becomes
com.ibm.websphere.wdo.access.connections.ConnectionManager.
- com.ibm.websphere.sdo.mediator.jdbc.ConnectionWrapper
becomes
com.ibm.websphere.wdo.mediator.rdb.ConnectionWrapper.
Changes to a Web project after changing the J2EE level of your
application from 1.3 to 1.4
In addition to the changes that occur to migrate from WDO to SDO by
changing the server target to WebSphere Application Server V6.0,
changing the J2EE specification level of your application from 1.3 to
1.4 updates any tag library (taglib) references in your JavaServer
Pages (JSPs) from using WDO, JSTL 1.0 tag libraries to SDO, JSTL
1.1/jsp 2.0 tag libraries. The following table shows the
changes in the JSP taglib references when you move from J2EE 1.3 to
J2EE 1.4.
Table 1. JSP taglib references in J2EE 1.3 and J2EE 1.4.
| J2EE 1.3 taglib (WDO)
| J2EE 1.4 taglib (SDO)
|
| http://www.ibm.com/websphere/wdo/core
| http://www.ibm.com/websphere/sdo/core
|
| http://java.sun.com/jstl/core
| http://java.sun.com/jsp/jstl/core
|
| http://java.sun.com/jstl/fmt
| http://java.sun.com/jsp/jstl/fmt
|
| http://java.sun.com/jstl/xml
| http://java.sun.com/jsp/jstl/xml
|
| http://java.sun.com/jstl/sql
| http://java.sun.com/jsp/jstl/sql
|
There are new reserved words in Enterprise Generation Language (EGL) in
Rational Application Developer.
The new reserved words are listed here:
- as
- isa
- like
- matches
- money
- openUI
- ref
- self
- string
- this
EGL programs from WebSphere Studio V5.1.x that are imported
and built in a V6.0 workspace that use these words as variable or part
names will be tagged with the following
message:IWN.SYN.2002.e 39/2 Syntax error on
input "variableName". You can correct the problem by renaming the
variable.
The JavaServer Faces and Faces Client runtime resources that originally
shipped in Rational Application Developer V6.0 have been updated for
Rational Application Developer V6.0.1. If you want to
continue development on Web projects that were created with this previous
product version, it is recommended that you update the Faces and Faces Client
runtime resources to the latest levels.
In Rational Application Developer V6.0.1, the Faces and Faces
Client runtime resource updates happen automatically when a Web project is
imported or a workspace is opened that contains out-of-date Faces or Faces
Client runtime resources. After importing a Web project or opening a
workspace from Rational Application Developer V6.0 to Rational
Application Developer V6.0.1, you will be prompted to update
these runtime resources to the latest levels.
Automatically updating runtime resources
To update the Faces and Faces Client runtime resources
automatically for a Web project:
- Import a Web project (or a workspace) containing Faces or Faces Client
content from Rational Application Developer V6.0. The Project
Migration window opens.
- Note:
- If the Project Migration window does not open, your automatic build
preference setting is probably disabled. In Project Explorer,
right-click your Web project and select Build ->
Project; the process of rebuilding a project opens the Project
Migration window.
- If you have other Web projects with Faces or Faces Client content in your
workspace, check Apply this choice to any other projects that need to be
upgraded and all your Web projects will be updated.
- Click one of the following:
- Yes to complete the update automatically.
- Later to defer the update. To update runtime resources
automatically after selecting Later, you have to close and reopen
the Web project or restart the workbench before rebuilding your Web
project. If you have disabled automatic builds, right-click your Web
project and select Build Project.
- Never to keep your runtime resources back-level. If you
choose Never and intentionally stay with the back-level runtime
resources, you will not be prompted again to update them. In the
future, you will need to update the runtime resources manually if you require
them.
Manually updating runtime resources
To update the Faces and Faces Client runtime resources manually
for a Web project:
- Create a new Web project (or, if you are working with EGL, create a new
EGL Web project) named JSF601. You will use this project
only as a source for the latest runtime resources; it can be deleted
after the update is complete.
- In the Project Explorer, right-click on the JSF601 project and
select Properties from the menu.
- Click Web Project Features and select Add Faces Base
Components and Add Faces Client Framework, then click
OK.
- If you are working with EGL, create a JSF page file as
follows:
- Right-click the WebContent folder of your new EGL Web project.
- Select New -> Other -> Faces JSP
File.
The eglintdebug.jar and
eglintdebugsupport.jar files are added to your
project.
- For each existing Faces project that you want to update, do the
following:
- In Project Explorer, expand an existing project to show the files in the
WebContent/WEB-INF/lib/ folder. Locate and delete any of the following
JAR files in this directory:
- eglintdebug.jar (EGL only)
- eglintdebugsupport.jar (EGL only)
- fda6.jar (EGL only)
- fdaj6.jar (EGL only)
- jsf-api.jar
- jsf-ibm.jar
- jsf-impl.jar
- odc-jsf.jar
- For any JAR files that you deleted, copy the JAR file of the same name
from the WebContent/WEB-INF/lib directory of the JSF601 project and
paste it into your original project in the same location. Some
configurations will not require all of these JAR files to be present in the
project; do not copy a particular JAR file if it was not in the original
project.
- If you are working with EGL, right click on the name of each
EGL Web project and click Generate; then, if you are not
building the projects automatically, click Project ->
Build All.
- Delete the JSF601 Web project.
The JavaServer Faces and Faces Client runtime resources that originally
shipped in Rational Application Developer V6.0 have been updated for
Rational Application Developer V6.0.1. If you want to
continue development on portlet projects that were created with this previous
product version, it is recommended that you update the Faces and Faces Client
runtime resources to the latest levels.
In Rational Application Developer V6.0.1, the Faces and Faces
Client runtime resource updates happen automatically when a portlet project is
imported or a workspace is opened that contains out-of-date Faces or Faces
Client runtime resources. After importing a portlet project or opening
a workspace from Rational Application Developer V6.0 to Rational
Application Developer V6.0.1, you will be prompted to update
these runtime resources to the latest levels.
Automatically updating runtime resources
To update the Faces and Faces Client runtime resources
automatically for a portlet project:
- Import a portlet project (or a workspace) containing Faces or Faces Client
content from Rational Application Developer V6.0. The Project
Migration window opens.
- Note:
- If the Project Migration window does not open, your automatic build
preference setting is probably disabled. In Project Explorer,
right-click your portlet project and select Build ->
Project; the process of rebuilding a project opens the Project
Migration window.
- If you have other portlet projects with Faces or Faces Client content in
your workspace, check Apply this choice to any other projects that need
to be upgraded and all your portlet projects will be updated.
- Click one of the following:
- Yes to complete the update automatically.
- Later to defer the update. To update runtime resources
automatically after selecting Later, you have to close and reopen
the portlet project or restart the workbench before rebuilding your portlet
project. If you have disabled automatic builds, right-click your
portlet project and select Build Project.
- Never to keep your runtime resources back-level. If you
choose Never and intentionally stay with the back-level runtime
resources, you will not be prompted again to update them. In the
future, you will need to update the runtime resources manually if you require
them.
- To update the portlet-specific Faces runtime resources,
jsf-portlet.jar and jsf-wp.jar, you need to follow the manual
update steps below.
Manually updating runtime resources
To update the Faces and Faces Client runtime resources manually
for a portlet project:
- Create a new portlet project named JSFP601. You will use
this project only as a source for the latest runtime resources; it can be
deleted after the update is complete.
- In the Project Explorer, right-click on the JSFP601 project and
select Properties from the menu.
- Click Web Project Features and select Add Faces Client
Framework for Portlet Project, then click OK.
- For each existing Faces portlet project that you want to update, do the
following:
- In Project Explorer, expand an existing project to show the files in the
WebContent/WEB-INF/lib/ folder. Locate and delete any of the following
JAR files in this directory:
- jsf-api.jar
- jsf-ibm.jar
- jsf-impl.jar
- jsf-portlet.jar
- odc-jsf.jar
- For any JAR files that you deleted, copy the JAR file of the same name
from the WebContent/WEB-INF/lib directory of the JSFP601 project
and paste it into your original project in the same location. Some
configurations will not require all of these JAR files to be present in the
project; do not copy a particular JAR file if it was not in the original
project.
- If your portlet project uses the IBM(R) portlet API or person link
component, copy the jsf-wp.jar file into your original project.
- If you copy the file odc-jsf.jar, copy the file
odc-jsf-portlet.jar as well.
- Delete the JSFP601 portlet project.
The J2EE Migration Wizard has been updated in Rational Application
Developer V6.0 to migrate J2EE projects to the J2EE 1.4
specification level. The J2EE Migration Wizard supports the migration
from both the J2EE 1.2 and 1.3 specifications to the J2EE
1.4 specification level for all J2EE module types.
Refer to J2EE 1.3 to 1.4 specification level migration and J2EE 1.2 to 1.4 specification level migration for details on the migration of J2EE
1.3 and 1.2 specification level artifacts to J2EE 1.4
specification level.
- Note:
- Before using the J2EE Migration Wizard, it is strongly recommended that you
take the following steps:
- Backup your entire workspace.
- If you are working with a shared repository, check out or lock all
corresponding projects.
The J2EE Migration Wizard can be accessed as follows:
- In the J2EE Hierarchy view of the J2EE perspective, right-click
the enterprise application project that you want to migrate.
- Select Migrate -> J2EE Migration Wizard from
the pop-up menu.
- Follow the instructions on the J2EE Migration Wizard Welcome Page before
proceeding with the migration process.
Note:
Refer to the online help for full details on using the J2EE Migration
Wizard. Changes to the wizard are described in Changes in the J2EE Migration Wizard in Rational Application Developer V6.0.
Refer to J2EE 1.3 to 1.4 specification level migration and J2EE 1.2 to 1.4 specification level migration for details on the changes to J2EE
1.3 and 1.2 specification level artifacts when they are migrated
to J2EE 1.4.
Secure Web services are not migrated by the J2EE Migration Wizard when Web
services are migrated from J2EE 1.3 to J2EE 1.4. The
migration of secure Web services requires manual steps.
After the J2EE migration, the secure binding and extension files must be
migrated manually to J2EE 1.4 as follows:
- Double click on the webservices.xml file to open the Web Services
editor.
- Select the Binding Configurations tab to edit the binding
file.
- Add all the necessary binding configurations under the new sections
Request Consumer Binding Configuration Details and Response
Generator Binding Configuration Details.
- Select the Extension tab to edit the extension file.
- Add all the necessary extension configurations under the new sections
Request Consumer Service Configuration Details and Response
Generator Service Configuration Details.
- Save and exit the editor.
J2EE projects can be migrated from the J2EE 1.3 to J2EE 1.4
specification level. This section describes, for each type of J2EE
project, the artifacts migrated from J2EE 1.3 to J2EE 1.4 by the
J2EE Migration Wizard.
The J2EE Migration Wizard supports the migration of enterprise bean
deployment descriptors from the J2EE 1.3 specification level EJB
resource to J2EE 1.4. Stateless session beans and message-driven
beans are migrated to J2EE 1.4.
Migrating session beans
The J2EE Migration Wizard migrates stateless session beans that are defined
as service endpoint interfaces (SEI) in the webservices.xml descriptor
of an EJB project in J2EE 1.3 to the J2EE 1.4 specification
level by setting the service endpoint interfaces on the stateless session
bean.
The J2EE 1.4 specification requires a SEI be defined on a stateless
session bean if the session bean is to be used as a Web services
endpoint. During the migration of an EJB JAR file, all session beans in
the EJB project get the service endpoint set to the name used in the
webservices.xml descriptor of the EJB project. The following is
an example of how the metadata of an EJB project looks before and after
migration to the J2EE 1.4 specification level.
EJB project in J2EE 1.3:
webservices.xml descriptor with a stateless session bean
used as a Web service endpoint interface before migration
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE webservices PUBLIC "-//IBM Corporation, Inc.//DTD J2EE Web services 1.0//EN"
"http://www.ibm.com/webservices/dtd/j2ee_web_services_1_0.dtd">
<webservices id="WebServices_1084831328093">
<webservice-description id="WebServiceDescription_1084831328093">
<webservice-description-name>EchoEJBService</webservice-description-name>
<wsdl-file>META-INF/wsdl/EchoEJB.wsdl</wsdl-file>
<jaxrpc-mapping-file>META-INF/EchoEJB_mapping.xml</jaxrpc-mapping-file>
<port-component id="PortComponent_1084831328103">
<port-component-name>EchoEJB</port-component-name>
<wsdl-port id="WSDLPort_1084831328103">
<namespaceURI>http://test</namespaceURI>
<localpart>EchoEJB</localpart>
</wsdl-port>
<service-endpoint-interface>test.EchoEJB</service-endpoint-interface>
<service-impl-bean id="ServiceImplBean_1084831328103">
<ejb-link>EchoEJB</ejb-link>
</service-impl-bean>
</port-component>
</webservice-description>
</webservices>
The <service-endpoint-interface> and
<service-impl-bean> tags in the preceding example define
stateless session bean "EchoEJB" as a service endpoint in the webservices
descriptor at the J2EE 1.3 specification level prior to
migration.
EJB project in J2EE 1.4: EJB deployment descriptor for
the same stateless session bean "EchoEJB" with service endpoint interface
created by the migration process
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar>
<ejb-jar id="ejb-jar_ID" version="2.1" xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd">
<display-name>
EchoEJBProject</display-name>
<enterprise-beans>
<session id="EchoEJB">
<ejb-name>EchoEJB</ejb-name>
<home>test.EchoEJBHome</home>
<remote>test.EchoEJB</remote>
<service-endpoint>test.EchoEJB</service-endpoint>
<ejb-class>test.EchoEJBBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
</session>
</enterprise-beans>
</ejb-jar>
The<service-endpoint> tag in the preceding example defines
"EchoEJB" as a service endpoint in the J2EE 1.4 specification level
after migration.
Migrating message-driven beans
The J2EE Migration Wizard supports the migration of EJB 2.0 to EJB
2.1 message-driven beans.
Message-driven beans were introduced in EJB 2.0 to support the
processing of asynchronous messages from a Java Message Service (JMS).
The EJB 2.1 specification expands the definition of the message-driven
bean so that it can support any messaging system, not just JMS.
- Note:
- Message-driven beans that have been migrated from the EJB 2.0
specification level to EJB 2.1 and are deployed to WebSphere
Application Server version 6 must be deployed against a Java Connector
Architecture (JCA) 1.5 resource adapter instead of a listener port (as
in WebSphere Application Server version 5). You must use the Deployment
Descriptor Editor to change the WebSphere Bindings settings for the EJB
2.1 message-driven beans to use a JCA adapter. See Configuring an EJB 2.1 message-driven bean to use a JCA adapter.
The EJB 2.0 message-driven bean artifacts migrated are:
- acknowledgeMode
- messageSelector
- destinationType
- subscriptionDurablity
Some of the EJB 2.0 message-driven bean elements are replaced with
activation-config properties. The property names and values
used in the activation-config property to describe the messaging
service will vary depending on the type of message service used.
However, EJB 2.1 defines a set of fixed properties for JMS-based
message-driven beans.
The following example compares the elements of a sample bean in EJB
2.0 with how the elements appear in EJB 2.1.
An example of message-driven bean elements in EJB
2.0:
<message-driven id="Mdb20">
<ejb-name>Mdb</ejb-name>
<ejb-class>ejbs.MdbBean</ejb-class>
<transaction-type>Bean</transaction-type>
<message-selector>mdbMessage</message-selector>
<acknowledge-mode>Auto-acknowledge</acknowledge-mode>
<message-driven-destination>
<destination-type>javax.jms.Topic</destination-type>
<subscription-durability>Durable</subscription-durability>
</message-driven-destination>
</message-driven>
An example of message-driven bean elements in EJB
2.1:
<message-driven id="Mdb21">
<ejb-name>Foo/ejb-name>
<ejb-class>ejbs.FooBean</ejb-class>
<messaging-type>javax.jms.MessageListener</messaging-type>
<transaction-type>Bean/transaction-type>
<message-destination-type>javax.jms.Topic</message-destination-type>
<activation-config>
<activation-config-property>
<activation-config-property-name>destinationType</activation-config-property-name>
<activation-config-property-value>javax.jms.Topic</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>subscriptionDurability</activation-config-property-name>
<activation-config-property-value>Durable</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>acknowledgeMode</activation-config-property-name>
<activation-config-property-value>AutoAcknowledge</activation-config-property-value>
</activation-config-property>
<activation-config-property>
<activation-config-property-name>messageSelector</activation-config-property-name>
<activation-config-property-value>fooSelector</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
Message-driven beans that have been migrated from Enterprise Java Bean
(EJB) 2.0 to the EJB 2.1 specification level and are deployed to
WebSphere Application Server version 6 must be deployed against a Java
Connector Architecture (JCA) 1.5 resource adapter instead of a listener
port.
The following steps describe how to change the deployment descriptor of EJB
2.1 message-driven beans to use a JCA adapter:
- Open the EJB project in the Project Explorer.
- Double-click the EJB project's Deployment Descriptor file
in the Project Explorer. The EJB deployment descriptor editor
opens.
- Click the Bean tab to open the Bean page.
- For each EJB 2.1 message-driven bean in the EJB project, do the
following:
- Select the EJB 2.1 message-driven bean in the list of beans on the
left-hand side of the Bean page.
- Under the heading WebSphere Bindings, select the JCA
Adapter button.
- Specify bindings deployment properties:
- ActivationSpec JNDI name.
Type the JNDI name of the J2C activation specification that is to be used
to deploy this message-driven bean. This name must match the name of a
J2C activation specification that you define to WebSphere Application
Server.
- ActivationSpec Authorization Alias.
The name of a J2C authentication alias used for authentication of
connections to the JCA resource adapter. A J2C authentication alias
specifies the user ID and password that is used to authenticate the creation
of a new connection to the JCA resource adapter.
- Destination JNDI name.
Type the JNDI name that the message-driven bean uses to look up the JMS
destination in the JNDI name space.
- Save the changes and close the Deployment Descriptor editor.
Artifacts of a Web deployment descriptor are migrated by the J2EE Migration
Wizard when a J2EE 1.3 level Web project is migrated to J2EE
1.4.
The following Web application artifacts are migrated:
Authentication constraints
J2EE 1.4 includes a Description object that has two
attributes: language and value. This
Description object did not exist in J2EE 1.3; the description was
an attribute on the Authentication Constraint. So, when the artifacts
of a Web deployment descriptor are migrated to J2EE 1.4, the
value of the Description object is taken from the description
attribute of the Authentication constraint.
Security constraints
Similarly, in J2EE 1.3 the description was an attribute on Security
Constraint . In J2EE 1.4 there is a new Description object with
the attributes language and value. So, the
value of the Description object is taken from the description
attribute of the Security Constraint.
Web application
The description string attribute of the ContextParam object in the J2EE
1.3 specification level has been moved to a Description object in
ParamValue in J2EE 1.4.
The TagLib object in J2EE 1.3 has been moved to the JSPConfig object
in J2EE 1.4. The JSPConfig objects belonged to the Web root
object in 1.3.
The J2EE Migration Wizard migrates the artifacts of a J2EE Connector
architecture (JCA) 1.0 descriptor to JCA 1.5. The
migrated artifacts are related to the elements of the ResourceAdaptor object
as two new objects, OutboundResourceAdaptor and ConnectionDefinition, were
added to the ResourceAdaptor object in J2EE 1.4 specification level for
Connector projects.
The mapping of the migrated elements is described below.
- The following elements are moved from the ResourceAdaptor object to the
OutboundResourceAdaptor object:
- reauthenticationSupport
- transactionSupport
- The following elements are moved from the ResourceAdaptor object to the
ConnectionDefinition object:
- managedConnectionFactoryClass
- connectionFactoryInterface
- connectionFactoryImplClass
- connectionInterface
- connectionImplClass
- The outboundResourceAdaptor object contains a list of ConnectionDefinition
definitions. Hence the ConnectionDefinition is added to the
ConnectionDefinition list held by OutboundResourceAdaptor.
- The OutboundResourceAdaptor object is contained by the ResourceAdaptor
object.
- The AuthenticationMechanism object has undergone some changes in JCA
1.5 where the customAuthMechType element is replaced by the
authenticationMechanism and the authenticationType element is replaced by
authenticationMechanism
- The description attribute in the ResourceAdaptor object is replaced with a
Description object where the description attribute string is set to value
element in the Description object for the following objects:
- SecurityPermission
- AuthenticationMechanism
- ConfigurationProperties
The J2EE 1.4 specification has added support for Web services
through the new JAX-RPC 1.0 API.
The JAX-RPC API supports service endpoints through:
- servlets with JAXR-RPC
- servlets with direct SOAP
- stateless session beans
The J2EE 1.4 specification supports the Web services for J2EE
specification (JSR 109). JSR 109 defines the deployment requirements
for Web services and utilizes the JAX-RPC programming model.
The following Web services artifacts are migrated using the J2EE Migration
Wizard:
- Web services descriptor
- Web services client descriptor
- JAX-RPC mapping descriptor
Migrating Web service deployment descriptors
Any Web service deployment descriptors contained in J2EE 1.3
projects that are migrated to the J2EE 1.4 specification level will be
migrated from JSR-109 V1.0 (for J2EE 1.3) to J2EE
1.4.
Web service deployment descriptors, as defined by JSR-109 V1.0,
consist of the files webservices.xml, webservicesclient.xml, and
all JAX-RPC mapping deployment descriptors that are referenced by the
webservices.xml and webservicesclient.xml files. As with
other J2EE deployment descriptors, migration will modify the structure of the
information contained in the descriptors in order to make them comply with the
J2EE 1.4 specification. One structural change which is
particular to the Web service deployment descriptors is the change to the way
in which qualified names are represented. In JSR-109 V1.0,
qualified names are represented using a sequence of two elements,
<namespaceURI> and <localpart>, which
contain the namespace URI and the local part of the name respectively.
Qualified names in J2EE 1.4 are based on the XMLSchema QName type,
which uses XML namespaces.
Further details on the migration of each of the Web service deployment
descriptors is provided below.
- Web services descriptor (webservices.xml)
The webservices.xml deployment descriptor is present in Web projects
and EJB projects that contain J2EE Web services. Both the
<wsdl-port> element and the <soap-header>
element contain qualified names and their contents will be migrated to the
J2EE 1.4 format.
For example, if <wsdl-port> is represented as follows
before migration,
<wsdl-port>
<namespaceURI>http://addressbook.webservice</namespaceURI>
<localpart>AddressBook</localpart>
</wsdl-port>
after migration <wsdl-port> will be represented as:
<wsdl-port xmlns:pfx="http://addressbook.webservice">pfx:AddressBook</wsdl-port>
The prefix "pfx" is used as the namespace prefix for all qualified names
that are migrated.
- Web services client descriptor (webservicesclient.xml)
The webservicesclient.xml deployment descriptor is present in J2EE
1.3 Web projects, EJB projects, and application client projects that
contain J2EE Web service clients. During migration from J2EE 1.3
to 1.4, the contents of webservicesclient.xml are migrated and
moved to the deployment descriptor for the project. The process that
occurs is as follows:
- For Web projects, all <service-ref> elements in
webserivcesclient.xml are moved under the <web-app>
element in web.xml.
- For application client projects, all <service-ref>
elements in webservicesclient.xml are moved under the
<application-client> element in
application-client.xml.
- For EJB projects, all <service-ref> elements within a
<component-scoped-refs> in the webserviceclient.xml
are moved under the corresponding <enterprise-bean> in
ejb-jar.xml.
- Webservicesclient.xml is deleted.
Both the <service-qname> element and the
<soap-header> element contain qualified names and their
contents will be migrated to the J2EE 1.4 format. For example,
if <service-qname> is represented as follows before
migration,
<service-qname>
<namespaceURI>http://addressbook.webservice</namespaceURI>
<localpart>AddressBookService</localpart>
</service-qname>
after migration <service-qname> will be represented
as:
<service-qname xmlns:pfx="http://addressbook.webservice">pfx:AddressBookService</service-qname>
The prefix "pfx" is used as the namespace prefix for all qualified names
that are migrated.
- JAX-RPC mapping descriptor
Both the webservices.xml and webservicesclient.xml deployment
descriptors can reference one or more JAX-RPC mapping deployment
descriptors.
In the webservices.xml file, these references are contained in the
<jaxrpc-mapping-file> element under each
<webservice-description> element. In the
webservicesclient.xml file, these references are contained in the
<jaxrpc-mapping-file> element under each
<service-ref> element.
During migration from J2EE 1.3 to 1.4, all the JAX-RPC
mapping deployment descriptors referenced in webservices.xml and
webservicesclient.xml are migrated. Migration includes migrating
all qualified names to the J2EE 1.4 format (see the sections above on
webservices.xmland webservicesclient.xml for examples of
qualified names following migration).
J2EE modules can be migrated from the J2EE 1.2 specification level
to J2EE 1.4. This section describes the artifacts migrated for
J2EE projects from J2EE 1.2 to J2EE 1.4 specification level by
the J2EE Migration Wizard.
For details on using the J2EE Migration Wizard, refer to Chapter 4, Migrating J2EE projects.
Migrating an EJB project from the EJB 1.1 to EJB 2.1
specification level is described in this section.
Migrating an EJB project from EJB 1.1 to EJB 2.1 involves the
migration of container-managed persistence (CMP) entity beans.
There have been no changes in entity beans between J2EE 1.3 and J2EE
1.4 specification level. Migrating CMP entity beans from the EJB
1.1 to EJB 2.1 specification level is accomplished the same way
as migrating a CMP entity bean from EJB 1.1 to EJB 2.0.
Migrating container-managed entity beans from EJB 1.1 to EJB 2.x
specification level requires the following steps:
- Convert the EJB project from EJB 1.1 to
EJB 2.x.
- Migrate the EJB code from EJB 1.1 to EJB
2.x.
- Migrate any user-defined EJB 1.1
references to local references in EJB 2.x.
An EJB 1.1 project can be converted to an EJB 2.x project
using the J2EE Migration Wizard.
- In the J2EE Hierarchy view, right-click on the 1.1 project, and
then select Migrate -> J2EE Migration
Wizard.
Or, if you want to preserve the original EJB 1.1 project, you can
create a new 2.x project and then import the existing project JAR file
into it (File -> Import -> EJB
JAR).
Although the project is an EJB 2.x project, the existing (or
imported) EJB 1.1 container-managed persistence (CMP) entity beans
remain EJB 1.1 beans. That is, the CMP entity beans are not
converted to EJB 2.x.
The J2EE Migration Wizard migrates the enterprise beans within an EJB
2.x project from 1.1 into 2.x. (If you choose to
migrate your 1.1 CMP entity beans to 2.x, all beans in the
2.x project must be migrated. However, you can selectively
choose to add local client views to these migrated 2.x beans.)
- The wizard will maintain the existing EJB 1.1 inheritance in the
EJB 2.x project.
- The wizard will migrate EJB 1.1 (proprietary) relationships into
EJB 2.x (standard) relationships, plus other benefits.
- Note:
- If you have any mapped associations, EJB 2.x associations will be
created for the associations themselves, but the role maps for those
associations will become invalid. If you run validation, you will see
an error occur. To get around this, open the mapping editor first and
save the map. The role maps will be removed. You may then run
validation again and re-map the roles.
For projects converted from EJB 1.1 to EJB 2.x, steps must be
taken to migrate existing EJB 1.1 code to EJB 2.x.
- Note:
- EJB 2.x beans are only supported in an EJB 2.x project
(although a 2.x project also supports 1.1 beans).
- For any CMP 1.1 bean, replace each CMP field with abstract
getXXX and setXXX methods. (Then the bean class
needs to be abstract.)
- For any CMP, create an abstract getXXX and setXXX
method for the primary key.
- For any CMP 1.1 finder method, create an EJBQL (EJB
Query Language) method for each finder method.
- Note:
- EJB Query Language has the following limitations in Rational Application
Developer V6.0:
- EJB Query Language queries involving EJBs with keys made up of
relationships to other EJBs will appear as invalid and cause errors at
deployment time.
- The IBM EJB Query Language support extends the EJB 2.x
specification in various ways, including relaxing some restrictions, adding
support for more DB2 functions, and so on. If portability across
various vendor databases or EJB deployment tool is a concern, then care should
be taken to write all EJB Query Language queries strictly according to
instructions described in Chapter 11 of the EJB 2.x
specification.
- For any CMP 1.1 finder, return
java.util.Collection instead of
java.util.Enumeration.
- For any CMP 1.1 bean, change all occurrences of
this.field = value to setField(value) in
ejbCreate() and elsewhere throughout the code.
- Update your exception handling (rollback behavior) for non-application
exceptions:
- Throw javax.ejb.EJBException instead of
java.rmi.RemoteException to report non-application
exceptions.
- In EJB 2.x and 1.1, all non-application exceptions thrown by
the instance result in the roll back of the transaction in which the instance
executed, and in discarding the instance.
- Update your Exception handling (rollback behavior) for application
exceptions:
- In EJB 2.x and 1.1, an application exception does not cause
the container to automatically roll back a transaction.
- In EJB 1.1, the container performs the rollback only if the
instance was invoked using the setRollbackOnly() method on its
EJBContext object.
- Update any CMP setting of application-specific default values to be inside
ejbCreate (not using global variables, since EJB 1.1
containers set all fields to generic default values before calling
ejbCreate which will overwrite any previous application specific
defaults).
When creating EJB 1.1 relationships were created, EJB references
were created to the Remote Client view. During the EJB 1.1
project migration using the J2EE Migration Wizard, these EJB remote references
for the EJB 1.1 relationships are removed and replaced with EJB local
references. Local references for user-defined EJB references must be
recreated manually.
- Note:
- In EJB 2.x, EJB relationships can be created only if the beans have
Local Client view defined on them and the EJB local references are created for
the EJB 2.x relationships.
For user-defined EJB references, migration is not done using the
J2EE Migration Wizard. However, follow these steps to set up the local
references:
- Delete the existing EJB remote references in References page of the
deployment descriptor editor.
- Add an EJB local reference in References page of the deployment descriptor
editor.
During the project structure migration using the J2EE Migration Wizard, the
method elements (that include security identity, container transaction, method
permissions, access intent and isolation levels) of the same type for all the
beans are merged to make them logically grouped.
A sample of the method elements before and after the project structure
migration.
The following is a sample of the method permission in the source page of
the deployment descriptor editor before project structure migration.
<method-permission>
<role-name>rol1</role-name>
<role-name>rol2</role-name>
<method>
<ejb-name>TestBean1</ejb-name>
<method-intf>Home</method-intf>
<method-name>getEJBMetaData</method-name>
<method-params>
</method-params>
</method>
<method>
<ejb-name>TestBean1</ejb-name>
<method-intf>Home</method-intf>
<method-name>getHomeHandle</method-name>
<method-params>
</method-params>
</method>
<method>
<ejb-name>TestBean2</ejb-name>
<method-intf>Home</method-intf>
<method-namae>remove</method-name>
<method-params>
<method-param>java.lang.Object</method-param>
</method-params>
</method>
<method>
<ejb-name>TestBean2</ejb-name>
<method-intf>Home</method-intf>
<method-name>remove</method-name>
<method-params>
<method-param>javax.ejb.Handle</method-param>
</method-params>
</method>
</method-permission>
<method-permission>
<role-name>rol1</role-name>
<role-name>rol2</role-name>
<method>
<ejb-name>TestBean2</ejb-name>
<method-intf>Remote</method-intf>
<method-name>isIdentical</method-name>
<method-params>
<method-param>javax.ejb.EJBObject</method-param>
</method-params>
</method>
</method-permission>
The following is a sample of the method permission in the source page of
the deployment descriptor editor after project structure migration.
<method-permission>
<role-name>rol1</role-name>
<role-name>rol2</role-name>
<method>
<ejb-name>TestBean1</ejb-name>
<method-intf>Home</method-intf>
<method-name>getEJBMetaData</method-name>
<method-params>
</method-params>
</method>
<method>
<ejb-name>TestBean1</ejb-name>
<method-intf>Home</method-intf>
<method-name>getHomeHandle</method-name>
<method-params>
</method-params>
</method>
<method>
<ejb-name>TestBean2</ejb-name>
<method-intf>Home</method-intf>
<method-name>remove</method-name>
<method-params>
<method-param>>java.lang.Object</method-param>
</method-params>
</method>
<method>
<ejb-name>TestBean2</ejb-name>
<method-intf>Home</method-intf>
<method-name>remove</method-name>
<method-params>
<method-param>javax.ejb.Handle</method-param>
</method-params>
</method>
<method>
<ejb-name>TestBean2</ejb-name>
<method-intf>Remote</method-intf>
<method-name>isIdentical</method-name>
<method-params>
<method-param>javax.ejb.EJBObject</method-param>
</method-params>
</method>
</method-permission>
- Note:
- When the CMP 1.x to CMP 2.x bean migration is also selected
along with the project structure migration in the J2EE Migration Wizard, the
access intent and isolation levels are removed but everything else is merged
during migration. The reason that access intents and isolation level
are removed is that they are no longer valid due the changes in the extensions
model. With the new model we have both access intents and isolation
level defined in access intents and we have bean-level access intents and
method-level access intents. It is always advised to use the bean-level
access intents rather than the method-level access intents.
Artifacts of a Web deployment descriptor are migrated by the J2EE Migration
Wizard when a J2EE 1.2 Web project is migrated to the J2EE 1.4
specification level.
The following Web application artifacts are migrated:
Authentication constraints
J2EE 1.4 includes a Description object that has two
attributes: language and value. This
Description object did not exist in J2EE 1.2; the description was
an attribute on the Authentication Constraint. So, when the artifacts
of a Web deployment descriptor are migrated to J2EE 1.4, the
value of the Description object is taken from the description
attribute of the Authentication constraint.
Security constraints
Similarly, in J2EE 1.2 the description was an attribute on Security
Constraint . In J2EE 1.4 there is new Description object with
the attributes language and value. So, the
value of the Description object is taken from the description
attribute of the Security Constraint.
Web application
The description string attribute of the ContextParam object in the J2EE
1.2 specification level has been moved to a Description object in
ParamValue in J2EE 1.4.
The TagLib object in J2EE 1.2 has been moved to the JSPConfig object
in J2EE 1.4. The JSPConfig objects belonged to the Web root
object in 1.2.
Changes have been made to the J2EE Migration Wizard in Rational Application
Developer V6.0 that are common to the migration of all J2EE
specification levels.
Project structure migration is optional
In WebSphere Studio V5.1.x through V5.1.2,
project structure migration would take place simultaneously with J2EE
specification level migration. Project structure migration was not
optional when migrating J2EE specification levels.
In the J2EE Migration Wizard in Rational Application Developer V6.0,
Migrate project structure is a separate, optional selection from
Migrate project J2EE specification level. J2EE specification
level migration and project structure migration may be performed
independently.
Target server is required
In Rational Application Developer V6.0, new and existing J2EE
projects migrated to a higher J2EE specification level require a target server
be set on the project. Server targeting is the default mechanism of how
the classpath is set on a J2EE project in V6.0. For information
in setting a target server and using the J2EE Migration Wizard, refer to the
online help.
Portal Toolkit V5.0.2.2 projects will be migrated
automatically to Rational Application Developer V6.0 Portal Tools by
migrating the Portal Toolkit workspace, or loading the project from a SCM
(source code management) system, or importing the project using the Project
Interchange feature. If you are migrating from earlier versions of
Portal Toolkit, you will need to export your portlet projects to WAR files and
import the WAR files into the Portal Tools in Rational Application Developer
V6.0.
Before migrating portal applications, you must install the portal tools
feature of Rational Application Developer V6.0. Refer to the
installation guide.
- Note:
- Backward compatibility of portlet projects is not supported.
Automatic migration is only supported for projects created in Portal
Toolkit V5.0.2.2 with WebSphere Studio
V5.1.2. Refer to Chapter 1, Migrating from WebSphere Studio V5.1, 5.1.1, or 5.1.2 for details on migration.
If your portlet project is associated to an enterprise application project,
you will need to set the appropriate target server on the EAR project.
You can set the target server on the Server Properties page
(Properties -> Server).
During migration of Portal Toolkit V5.0.2.2 projects,
some additional changes take place:
- The target server is set to WebSphere Portal V5.0, if no target
server is set to the project.
- The portlet build path is corrected
- A portlet project nature is added.
If you are migrating from earlier versions of Portal Toolkit, you need to
manually migrate your portlet projects to Portal Tools in Rational Application
Developer V6.0, as follows:
- Export the existing project to a WAR file: In the earlier version of
Portal Toolkit, export each project to a WAR file with source files.
- Right-click the project and select Export.
- Select WAR file and Export source files and click
Finish.
- Import the portlet WAR file:
- In the Portal Tools for Rational Application Developer V6.0, create
a new empty portlet project.
- Select File -> New -> Project
-> Portal -> Portlet Project or Portlet Project
(JSR 168).
- Deselect Create a portlet.
- Click Show Advanced.
- If you are importing a WebSphere Portal 4.2 portlet, select
2.2 as the servlet version.
- Select WebSphere Portal v5.0 as the target server, and
click Finish.
- Import the WAR file to this new empty portlet project.
- Select Import.
- Select WAR file and specify the WAR file that you exported
above (Exporting project to WAR file in earlier version).
- Select the new empty portlet project.
- Select Overwrite existing resources without warning.
- Do not select Delete project on overwrite.
- Delete the TLD file:
It is recommended that you delete the portlet TLD file from the project if
it exists. Otherwise, you will get a warning message when you rebuild
the project. Leaving it may cause a problem when the portlet project is
deployed to WebSphere Portal and the TLD file of the portlet is different from
the file in the server.
- If you are migrating a WebSphere Portal 4.2 portlet, you need to
migrate this migrated portlet project to WebSphere Portal 5.x.
For information on migrating WebSphere Portal V4.2 portlets to
V5.x, refer to Migrating WebSphere Portal V4.2 portlets to V5.x.
For information on migrating Faces resources in a portlet project, refer to
Updating Faces runtime resources in a portlet project.
Rational Application Developer V6.0 does not support developing
WebSphere Portal V4.2 portlets. You need to migrate WebSphere
Portal V4.2 portlet projects to V5.x.
Most portlets written for WebSphere Portal V4.2 will run unchanged
in WebSphere Portal V5.x. Some of the Portlet
4.2.x APIs are now marked as deprecated, but still available on
WebSphere Portal V5.x.
- Note:
- Migrated portlet application projects are not backward compatible.
To migrate portlet applications for WebSphere Portal V4.2 to
V5.x, do the following steps:
- Migrate the Portal V4.2 portlet projects to Portal V5.x
portlet projects:
- Right-click the portlet application project that you want to
migrate.
- Select Properties -> Portlet API to open the
Portlet API page.
- Select WebSphere Portal Version 5.x from the Portlet API
level drop-down list.
- Click OK, and the following changes are automatically
made:
- The tag library descriptor (TLD) file for the portlet API is removed if it
exists.
- The Web level is changed from 2.2 to 2.3.
- The portlet specific class path entries are removed, as the WebSphere
Portal JRE container and WebSphere Portal runtime target container will
dynamically add them.
- If your portlet project is associated to an enterprise application
project, it is recommended that you migrate the J2EE level of the EAR project
to J2EE 1.3. Portlet applications designed for WebSphere Portal
V5.x should be compliant with the J2EE level 1.3
specifications.
- Note:
- Before migrating your enterprise application project to J2EE 1.3, read
Chapter 4, Migrating J2EE projects. For information on using the J2EE Migration Wizard,
refer to the online help.
- If the migrated portlet project is only associated to the enterprise
application project, do as follows:
- Close all editors in the workbench.
- Right-click the enterprise application project with which the migrated
portlet project is associated.
- Select Migrate -> J2EE Migration Wizard and
click Next.
- Select J2EE version 1.3 and WebSphere Portal
as the target server.
- Click Finish.
- If other portlet projects are associated with the enterprise application
project, you must remove the migrated portlet project and add it to another
enterprise application project.
- Remove the module of the migrated portlet project from the enterprise
application project.
- Expand the enterprise application project and select the deployment
descriptor.
- Select Open With -> Deployment Descriptor
Editor.
- Select the Module tab. On the Module page of the editor,
select the WAR file of the migrated portlet project.
- Click Remove.
- Select File -> Save to save the
changes.
- Create a new enterprise application project and add the portlet project to
it.
- Select File -> New ->
Project.
- Select Show All Wizards check box.
- Expand the J2EE and select Enterprise Application
Project.
- Fill in the project Name field, select J2EE version
1.3 and WebSphere Portal as the target server and
click Next.
- On the EAR Module Projects page, select the migrated portlet
project and click Finish.
The portlet project is now migrated to WebSphere Portal V5.x.
The JavaServer Faces runtime resources that originally shipped in WebSphere
Studio Application Developer V5.1.2 have been updated for
Rational Application Developer V6.0.1. If you want to
continue development on portlet projects that were created with Portal Toolkit
5.0.2.2 for this previous product version, it is
recommended that you update the Faces runtime resources to the latest
levels.
In Rational Application Developer V6.0.1, the Faces runtime
resource updates happen automatically when a portlet project is imported or a
workspace is opened that contains out-of-date resources. After
importing a portlet project created with Portal Toolkit
5.0.2.2 for WebSphere Studio Application Developer
V5.1.x to Rational Application Developer V6.0.1,
you will be prompted to update the Faces runtime resources to the latest
levels.
Automatically updating runtime resources
To update the Faces runtime resources automatically for a
portlet project:
- Import a portlet project containing Faces content from WebSphere Studio
Application Developer V5.1.x. The Project Migration
window opens.
- Note:
- If the Project Migration window does not open, your automatic build
preference setting is probably disabled. In Project Explorer,
right-click your portlet project and select Build ->
Project; the process of rebuilding a project opens the Project
Migration window.
- If you have other portlet projects with Faces content in your workspace,
check Apply this choice to any other projects that need to be
upgraded and all your portlet projects will be updated.
- Click one of the following:
- Yes to complete the update automatically.
- Later to defer the update. To update runtime resources
automatically after selecting Later, you have to close and reopen
the portlet project or restart the workbench before rebuilding your portlet
project. If you have disabled automatic builds, right-click your
portlet project and select Build Project.
- Never to keep your runtime resources back-level. If you
choose Never and intentionally stay with the back-level runtime
resources, you will not be prompted again to update them. In the
future, you will need to update the runtime resources manually if you require
them.
- To update the portlet-specific Faces runtime resources,
jsf-portlet.jar and jsf-wp.jar, you need to follow the manual
update steps below.
- Note:
- If you created Faces JSPs that contained Faces Client components, you must
separately update the Faces Client components runtime resources to the latest
levels. Refer to Updating Faces Client runtime resources in a Web project.
Manually updating runtime resources
To update the Faces runtime resources manually for a portlet
project:
- Import your existing portlet project with Faces content into a Rational
Application Developer V6.0.1 workspace.
- Create a new portlet project named JSFP601 with the Faces
portlet option selected in the second page. You will use this
project only as a source for the latest runtime resources; it can be
deleted after the update is complete.
- In the Project Explorer, right-click on the JSFP601 project and
select Properties from the menu.
- Click Web Project Features and select Add Faces Client
Framework for Portlet Project, then click OK.
- For each existing Faces project that you want to update, do the
following:
- In Project Explorer, expand an existing project to show the files in the
WebContent/WEB-INF/lib/ folder. Locate and delete any of the following
JAR files in this directory:
- jsf-api.jar
- jsf-ibm.jar
- jsf-impl.jar
- jsf-portlet.jar
- odc-jsf.jar
- Locate and open the file
WebContent/WEB-INF/faces-config.xml. Add the following elements
into this configuration file if they are not already present:
<lifecycle>
<phase-listener>com.ibm.faces.webapp.ValueResourcePhaseListener</phase-listener>
</lifecycle>
<application>
<variable-resolver>com.ibm.faces.databind.SelectItemsVarResolver</variable-resolver>
<variable-resolver>com.ibm.faces.application.WPPortletVariableResolver</variable-resolver>
<property-resolver>com.ibm.faces.databind.SelectItemsPropResolver</property-resolver>
</application>
- Note:
- If your portlet project is using the JSR 168 API, specify
com.ibm.faces.application.PortletVariableResolver
instead of
com.ibm.faces.application.WPPortletVariableResolver.
- For any JAR files that you deleted, copy the JAR file of the same name
from the WebContent/WEB-INF/lib directory of the JSFP601 project
and paste it into your original project in the same location. Some
configurations will not require all of these JAR files to be present in the
project; do not copy a particular JAR file if it was not in the original
project.
- If your portlet project uses the IBM portlet API or person link component,
copy the jsf-wp.jar file into your original project.
- If you copy the file odc-jsf.jar, copy the file
odc-jsf-portlet.jar as well.
- Open the web.xml deployment descriptor in the original project and
add the following to the configuration:
<context-param>
<param-name>com.ibm.ws.jsf.JSP_UPDATE_CHECK</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>com.ibm.ws.jsf.LOAD_FACES_CONFIG_AT_STARTUP</param-name>
<param-value>true</param-value>
</context-param>
- Delete the JSFP601 portlet project.
In Rational Application Developer V6.0, the WebSphere Application
Server test environments included with the product have changed from those
included with previous editions of WebSphere Studio Application
Developer.
The following is a summary of the changes to the WebSphere Application
Server test environments in Rational Application Developer V6.0:
- WebSphere Application Server V4.x servers are no longer supported
test environments. However, J2EE 1.2 specification level
applications can still be exported and deployed manually for testing on remote
V4.x servers.
- WebSphere Application Server V6.0 server has been added as an
installable test environment. It supports running J2EE 1.4
specification level applications.
- The WebSphere Portal test environment has been added for testing portals
and portlet applications.
The following table shows the WebSphere Application Server test environment
levels included with the different versions of WebSphere Studio Application
Developer and Rational Application Developer.
Table 2. WebSphere Application Server test environments in WebSphere Studio Application Developer and Rational Application Developer
| WebSphere Application Server V4.x AEs
| WebSphere Application Server V5.x Base
| WebSphere Application Server Express 5.x
| WebSphere Application Server V5.x Portal
| WebSphere Application Server V6.0
|
| WebSphere Studio Application Developer V5.1
| V4.0.6
| V5.0.2
| V5.0.2
| N/A
| N/A
|
| WebSphere Studio Application Developer V5.1.1
| V4.0.7 + PQ78374
| V5.0.2 + PQ78374 +PQ78419, V5.1
| V5.0.2 & V5.1
| N/A
| N/A
|
| WebSphere Studio Application Developer V5.1.2
| V4.0.7 + PQ78374
| V5.0.2 + PQ78374 +PQ78419, V5.1.0.3
| V5.0.2 & V5.1.0.3
| V5.0.2.3 Base + WebSphere Portal
V5.0.2.1
| N/A
|
| Rational Application Developer V6.0
| N/A
| V5.0.x, V5.1.1
| V5.0.2 & V5.1.1
| V5.0.2.6 Base + WebSphere Portal
V5.0.2.2, V5.1.1 Base + WebSphere Portal
5.1
| V6.0
|
Copyright and notices