Configuration mapping during migration

This topic describes what changes during migration, which always involves migrating a single instance to another single instance on the same machine or a separate machine. An example is a server group node from a Version 4.0.x environment migrating to a Version 5.x node that you later federate into a deployment manager cell.

Many migration scenarios are possible. The Version 5.x migration tools map objects and attributes to the Version 5.x environment when you restore a configuration from a previous version.

Bootstrap port

Migration maps a default bootstrap NameServer port setting, 900, from V3.5.x and V4.0.x Advanced Edition to the V5.x NameServer default, 2809. The migration tools map a non-default value directly into the V5.x environment.

For Advanced Single Server Edition migration, the bootstrap NameServer port maps to the NameServer value of the Application Server defined in the server configuration file.

Command line parameters

The migration tools convert appropriate command line parameters to Java virtual machine (JVM) settings in the server process definition. Most settings are mapped directly. Some settings, such as memory heap sizes, are not migrated because their roles in the V5.x configuration either do not exist, have different meanings, or have different scopes.

Cluster members

Version 4.0.x server groups are converted to Version 5.x clusters. Migration configures cluster members differently than stand-alone servers. When migrating a server group, all servers in the group are assigned to the HTTP transport port number of the server group, regardless of whether or not they each had a unique port number. Therefore, after migration, all the Application Servers in the new cluster use the same HTTP transport port. Migrated cluster members cannot run until federated into a Network Deployment cell. You can use the administrative console to assign unique port numbers, which lets you run the server without federating it.

Default Server

The name of the default server in Version 5.x is server1. All objects previously owned by the DefaultServer of the prior version, are owned by server1 of Version 5.x after migration.

Enterprise applications for cluster members

Migration does not deploy enterprise applications on cluster members when migrating from Version 3.5.x or Version 4.0.x. You must manually deploy these applications on the cluster using scripting or the deployment manager administrative console.

Automated migration of enterprise applications that are installed in a directory other than the default installedApps directory is not feasible in Version 5.x. Versions 4.0, 5.0, and 5.1 each allow enterprise applications to be installed in a location other than the default installedApps directory. However, for architectural reasons, this property is not migrated from previous versions of WebSphere Application Server to Version 5.0 or Version 5.1. The migration process instead redeploys the enterprise application to the default installedApps directory in the new version. Enterprise applications that are not installed in the default directory must be reinstalled in their new Version 5.x environment.

Java database connectivity (JDBC) drivers and data sources

Version 5.x significantly redefines JDBC and data source objects. The migration tools map V3.5.x and V4.0.x data sources to Version 5.x data sources, using predecessor settings as input variables. The data source that is used is the WebSphere Application Server V4.0.x data source that uses the ConnectionManager architecture.

Migration after federation

[5.0 only][Version 5.0.1][Version 5.0.2]Migration of a V3.5.x or V4.0.x node to a V5.x node

You cannot migrate a previous version configuration to a Version 5.x Application Server node after the node is federated into a deployment manager cell. The master copy of the configuration no longer resides on the Version 5.x Application Server node. A master configuration is on the deployment manager node.

You can perform the migration by removing the Application Server node from the cell, migrating, and refederating the node to the cell. As the node is federated, the deployment manager copies the migrated configuration into the master configuration that it maintains for the Application Server node.

You can migrate a V5.0.x node that belongs to a cell without removing the node from the cell.

Migrate the deployment manager first, before migrating any base nodes in the cell.


Migration tip

Operating platform Tip in Platform-specific tips for installing and migrating
All platforms Avoiding the use of a V5.0.x deployment manager after migrating to V5.1



Use the same cell name when migrating Network Deployment from V5.0.x to V5.1.x. If you use a different cell name, federated nodes cannot successfully migrate to the Network Deployment V5.1.x cell.

Migrating a base WebSphere Application Server node that is within a cell to V5.1.x also migrates the node agent to V5.1.x. A cell can have some V5.1.x nodes and other nodes that are at V5.0.x levels.

Models, clones, and server groups

Version 3.5.x models and clones and V4.0.x server groups are redefined in V5.x as clusters. Application servers are the only objects supported as models and cluster members in V5.x. This change is a significant difference from V3.5.x, in which many objects can be models and clones. All models and clones relating to Application Servers are mapped to clusters in V5.

Special mapping occurs during the migration of all the other objects that you could previously clone. All clones are treated as simple objects and map as if they are not cluster members. Models that are not Application Server models are ignored and unmapped.

Name bindings

Version 5.x has a new naming structure. All references, such as Enterprise JavaBeans (EJB) references that were valid in previous versions no longer work in Version 5.x. However, you can use the administrative console to add a name binding that maps an old name into the new Version 5.x naming structure. For example, the name of the Version 3.5.x or 4.0.x enterprise bean reference can be both the name of the binding and the Java Naming and Directory Interface (JNDI) name in the Version 5.x name space.

For an example, see Migrating to WebSphere V5: An End-to-End Migration Guide, which is available from the Redbooks Web site at http://www.ibm.com/redbooks .

Node name

A Version 3.5.x and a Version 4.0.x repository can contain more than one node name and associated children. The WASPostUpgrade tool processes only those objects and children that match the node name of the migrating node. The tool identifies node names in the configuration files that it is migrating and selects any nodes names in a configuration file that match the long network name or short network name of the migrating machine.

PageList servlet

The configuration of the PageList servlet has changed in Version 5.x. Direct use of the servlet has been deprecated. The PageList servlet is available as part of the servlet extension configuration in the Web archive (WAR) file. All references are updated to the servlet configuration supported in Version 5.

You can also use the to modify the servlet configuration.

If you use or extend the PageList servlet, you might see an error similar to the following example when running a migrated application that uses the servlet:

Error 500: No PageList information is configured for servlet 
EmpInfoApp.SearchByDept

Use the to correct the error, by moving the usage or extension to your migrated Enterprise archive (EAR) file:

  1. Start the to load the EAR file that generates the error.
  2. Open the Web modules within the EAR file.
  3. Expand the Web module that generates the error.
  4. Open the Web components and find the one that generates the error.
  5. Expand the Servlets. The PageList Extensions option displays.
  6. Add your extension information.
  7. Save the EAR file and redeploy it.

Properties directory, classes directory, and the lib/app directory
Property file migration from Version 3.5.x and Version 4.0.x

[5.0 only][Version 5.0.1][Version 5.0.2]Migration does not process property files from V3.5.x and V4.0.x. You must manually convert settings in these files to the V5.0.x equivalent configuration.

Samples

No migration of Samples from previous versions is available. Equivalent Version 5.x Samples are available to use.

Security

Java 2 Security is enabled by default in Version 5.x. Security enablement might cause some applications to run on Version 4.0 and not run on Version 5.x. Several techniques are available that you can use to define different levels of Java 2 Security in Version 5.x. One is to create a was.policy file as part of the application, to enable all security permissions. The migration tools call the wsadmin command to add an existing was.policy file in the Version 5.x properties directory to enterprise applications as they migrate. The migration tools perform this task while moving Version 4.0 applications into Version 5.

Global security that uses Lightweight Third Party Authentication (LTPA) in Versions 3.5.x and 4.0.x is migrated to the base WebSphere Application Server product and to the Network Deployment product. However, although global security was enabled in Versions 3.5.x and 4.0.x, it is disabled during migration to Version 5.x.

If you add this node later to an IBM WebSphere Application Server Network Deployment, Version 5.x configuration, you can enable and use the LTPA configuration. Use the administrative console to generate keys for the migrated LTPA mechanism. After generating the keys, you can enable global security.

The Global security feature that uses localos authentication mechanisms in Versions 3.5.x and 4.0.x is migrated to the Network Deployment product. However, although global security was enabled in Versions 3.5.x and 4.0.x, it is disabled during migration to Version 5.x. The Network Deployment product does not support the authentication mechanism known as SWAM. Migration sets the authentication mechanism in Version 5.x to LTPA. Use the administrative console to generate keys for the migrated LTPA. After generating the keys, you can enable global security.

Version 4.0.x introduced properties to support tuning the JNDI search timeout value along with LDAP reuse connection. These two properties are now settings in the Security Center of the Version 5.x administrative console. Version 4.0.x property values are not migrated to Version 5.x settings.

Use the Version 5.x administrative console to change these settings to match your Version 4 property values, if necessary.

Servlet package name change

The package that contains the DefaultErrorReporter servlet has changed for Version 5.x. In Versions 3.5.x and 4.0.x, the servlet was in the com.ibm.servlet.engine.webapp class. In Version 5.x, the servlet is in the com.ibm.ws.webcontainer.servlet class. Direct use of the DefaultErrorReporter servlet has been deprecated.

InvokerServlet and SimpleFileServlet servlets

The InvokerServlet and SimpleFileServlet servlets are internal servlets that have not been public since WebSphere Application Server Version 3.5. If you referenced these servlets in any version after Version 3.5 through the web.xml file, you should remove these entries from the web.xml file and use the ibm-web-ext.xmi file to enable or disable these servlets using serveServletsByClassnameEnabled and fileServingEnabled. See the following example:

<?xml version="1.0" encoding="UTF-8"?>
<webappext:WebAppExtension xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI"  
xmlns:webappext="webappext.xmi" xmlns:webapplication="webapplication.xmi"  
xmlns:commonext.localtran="commonext.localtran.xmi"  
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmi:id="WebApp_ID_Ext" reloadInterval="3" reloadingEnabled="true" 
fileServingEnabled="false" directoryBrowsingEnabled="false" 
serveServletsByClassnameEnabled="true" preCompileJSPs="false" 
autoRequestEncoding="false" autoResponseEncoding="false">
  <defaultErrorPage xsi:nil="true"/>
  <additionalClassPath xsi:nil="true"/>
  <webApp href="WEB-INF/web.xml#WebApp_ID"/>
  <extendedServlets xmi:id="ServletExtension_1">
    <extendedServlet href="WEB-INF/web.xml#Servlet_1"/>
  </extendedServlets>
  <extendedServlets xmi:id="ServletExtension_2">
    <markupLanguages xmi:id="MarkupLanguage_1" name="HTML" mimeType="text/html" 
    errorPage="Page_1" defaultPage="Page_2">
      <pages xmi:id="Page_2" name="Hello.page" uri="/HelloHTML.jsp"/>
      <pages xmi:id="Page_1" name="Error.page" uri="/HelloHTMLError.jsp"/>
    </markupLanguages>
    <markupLanguages xmi:id="MarkupLanguage_2" name="VXML" mimeType="text/x-vxml" 
    errorPage="Page_3" defaultPage="Page_4">
      <pages xmi:id="Page_4" name="Hello.page" uri="/HelloVXML.jsp"/>
      <pages xmi:id="Page_3" name="Error.page" uri="/HelloVXMLError.jsp"/>
    </markupLanguages>
    <markupLanguages xmi:id="MarkupLanguage_3" name="WML" mimeType="vnd.wap.wml" 
    errorPage="Page_5" defaultPage="Page_6">
      <pages xmi:id="Page_6" name="Hello.page" uri="/HelloWML.jsp"/>
      <pages xmi:id="Page_5" name="Error.page" uri="/HelloWMLError.jsp"/>
    </markupLanguages>
    <extendedServlet href="WEB-INF/web.xml#Servlet_2"/>
  </extendedServlets>
  <extendedServlets xmi:id="ServletExtension_3">
    <extendedServlet href="WEB-INF/web.xml#Servlet_3"/>
    <localTransaction xmi:id="LocalTransaction_1" unresolvedAction="Rollback"/>
  </extendedServlets>
</webappext:WebAppExtension>

Stdin, stdout, stderr, passivation, and working directories

The location for these directories is typically within the installation directory of a previous version. The default location for stdin, stdout, and stderr is the logs directory of the Version 5.x installation root. The migration tools attempt to migrate existing passivation and working directories. Otherwise, appropriate Version 5.x defaults are used.

Using common directories between versions in a coexistence scenario can cause problems.

Transport ports
The migration tools migrate all ports. The tools warn about port conflicts in a log when a port already exists. You must resolve port conflicts before running the servers that are in conflict, at the same time.

The default transport type of the servlet engine in Version 3.5.x is Open servlet engine (OSE). Because Version 5.x no longer supports OSE transport, the migration tools map these transports to HTTP transports, using the same port assignments.

You must manually add VirtualHost alias entries for each port.

Web modules

The specification level of the Java 2 Platform, Enterprise Edition (J2EE) that Version 5.x implements requires behavior changes in the Web container for setting the content type. If a default servlet writer does not set the content type, not only does the Version 5.x Web container no longer default to it, the Web container returns the call as "null". This situation might cause some browsers to display resulting Web container tags incorrectly. Migration sets the autoResponseEncoding IBM extension to true for Web modules as it migrates enterprise applications. This action prevents the problem.

Version 3.5.x to Version 5.x migration

The migration tools assist in the transition from Version 3.5.x to Version 5, by migrating system configurations and creating J2EE artifacts, including J2EE security roles mapping. The migration tools create initial J2EE enterprise applications based on Version 3.5.x configurations. However, because of the significant change in application structures, plan to carefully test and fine tune migrated applications, using development and deployment tools, to determine exactly how the applications function in Version 5.x.

Analyze the WASPostUpgrade.log file for detailed information about migrated enterprise beans. The J2EE programming model specifies an architecture for how applications are created and deployed. Because applications in Version 3.5.x do not have the same architecture, the WASPostUpgrade tool recreates applications. It creates all migrated Web resources and enterprise beans in J2EE applications. It maps all enterprise applications from the Version 3.5.x installation into J2EE applications with the same name, deployed in the same server.

The WASPostUpgrade tool maps Web resources and enterprise beans that are not included in an enterprise application, into a default J2EE application that includes the name of the server. The tool maps Web applications to J2EE WAR files. The tool deploys enterprise beans as EJB 1.1 beans in J2EE JAR files. The tool combines resources in a J2EE EAR file and deploys it in the Version 5.x configuration. Some differences exist between the EJB 1.0 and EJB 1.1 specifications, but in most cases, EJB 1.0 beans can run successfully as EJB 1.1 beans.

Mapping details for V3.5.x to Version 5.x migration
Version 4.0.x to Version 5.x migration

This migration is much less complicated than moving from V3.5.x to V5.x. The V4.0.x configuration is already at the J2EE 1.2 specification level. Although Version 5.x is at the J2EE 1.3 specification level, J2EE 1.2 objects are supported.


Related concepts
Migrating
Related tasks
Migrating and coexisting
Using enterprise beans in applications
Related reference
Java 2 security
Process logs



Searchable topic ID:   cins_migconf
Last updated: Jun 21, 2007 8:07:48 PM CDT    WebSphere Business Integration Server Foundation, Version 5.0.2
http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.wasee.doc/info/ee/ae/cins_migconf.html

Library | Support | Terms of Use | Feedback