WebSphere WebSphere Enterprise Service Bus, Version 6.0.1 Operating Systems: AIX, HP-UX, Linux, Solaris, Windows

Installing a mediation module EAR file with the console

Installing a mediation module consists of moving the installable EAR file, for the mediation module, onto a server or cluster that will host the mediation module. Installed mediation modules that start and run properly are considered deployed.

Before you begin

If you have exported your mediation module to a JAR file then use the serviceDeploy command to create an installable EAR file from the mediation module JAR file. For more information about creating an installable EAR file for a mediation module, see Deploying a mediation module.

Why and when to perform this task

To enable WebSphere ESB to use the functions provided by a mediation module to integrate applications and services, you need to install the EAR file for the module into a server or cluster, then start the deployed module.

This topic describes how to use the administrative console to install a mediation module EAR file. Alternatively, you can also use other methods, like the install or installinteractive command with the wsadmin tool, in the same way as you install enterprise application files into WebSphere Application Server.

Important: After you start performing the steps below, click Cancel to exit if you decide not to install the application. Do not simply move to another administrative console page without first clicking Cancel on an application installation page.

To use the administrative console to install a mediation module EAR file, complete the following steps:

Steps for this task

  1. Click Applications > Install New Application in the console navigation tree. The first of two Preparing for application installation pages is displayed.
  2. On the first Preparing for application installation page, complete the following substeps:
    1. Specify the full path name of the mediation module EAR file (.ear file). The EAR file that you are installing can be either on the client machine (the machine that runs the administrative console Web browser) or on the server machine (the machine to which the client is connected). If you specify an EAR file on the client machine, then the administrative console uploads the EAR file to the machine on which the console is running and proceeds with application installation.
    2. Click Next.
  3. On the second Preparing for application installation page, complete the following substeps:
    1. Select whether to generate default bindings.

      Using the default bindings causes any incomplete bindings in the application to be filled in with default values. Existing bindings are not altered.

      You can customize default values used in generating default bindings.

    2. Click Next. If security warnings are displayed, click Continue. The Install New Application pages are displayed. If you chose to generate default bindings, and your application does not use a resource adapter, you can proceed to the Summary step (last step below).
  4. On the Step: Select installation options panel, provide values for the following settings. For more information about the settings on this page, see Select installation options settings. Default values are used if you do not specify a value.
    1. For Directory to install application, specify the directory into which the application EAR file will be installed. The default value is the value of APP_INSTALL_ROOT/cell_name, where the APP_INSTALL_ROOT variable is install_root/installedApps. For example, for WebSphere ESB installed on Windows into C:\Program Files\WESB\, the default location is C:\Program Files\WESB\profile_name\installedApps\cell_name.
      Note: If an installation directory is not specified when an application is installed in a stand-alone profile, the application is installed in APP_INSTALL_ROOT/base_cell_name. If you add the stand-alone server to a deployment manager cell, the cell name of the new server configuration becomes the cell name of the deployment manager node. If the -includeapps option is used for the addNode utility, then the applications that are installed prior to the addNode operation still use the installation directory APP_INSTALL_ROOT/base_cell_name. However, an application that is installed after the stand-alone server has been added to the network configuration uses the default installation directory APP_INSTALL_ROOT/network_cell_name. To move the application to the APP_INSTALL_ROOT/network_cell_name location upon running the addNode operation, you should explicitly specify the installation directory as ${APP_INSTALL_ROOT}/${CELL} during installation. In such a case, the application files can always be found under APP_INSTALL_ROOT/current_cell_name.
    2. For Distribute application, specify whether WebSphere ESB expands or deletes application binaries in the installation destination. The default is to enable application distribution. As a result, when you save changes in the console, application binaries for newly installed applications are expanded to the directory specified. The binaries are also deleted when you uninstall and save changes to the configuration. If you disable this option, then you must ensure that the application binaries are expanded appropriately in the destination directories of all nodes where the application is expected to run.
      Important: If you disable this option and you do not copy and expand the application binaries to the nodes, a later saving of the configuration or manual synchronization does not move the application binaries to the nodes for you.
    3. For Use Binary Configuration, specify whether the server or cluster uses the binding, extensions, and deployment descriptors located with the application deployment document, the deployment.xml file (default), or those located in the EAR file.
    4. For Application name, type a name for the application. Application names must be unique within a cell and cannot contain characters that are not allowed in object names. For a list of characters that are not allowed in object names, see Object names
    5. For Create MBeans for resources, specify whether to create MBeans for various resources (such as servlets or JSP files) within an application when the application is started. The default is to create MBean instances.
    6. For Enable class reloading, specify whether to enable class reloading when application files are updated. The default is not to enable class reloading. Enabling class reloading sets reloadEnabled to true in the deployment.xml file for the mediation module. If a mediation module's class definition changes, the server run time stops and starts the application to reload application classes.
    7. For Reload interval in seconds, specify the number of seconds to scan the application's file system for updated files. The default is the value of the reload interval attribute in the IBM extension (META-INF/ibm-application-ext.xmi) file of the EAR file. To enable reloading, specify a value greater than zero (for example, 1 to 2147483647). To disable reloading, specify zero (0).

      The reload interval specified here takes effect only if class reloading is enabled.

    8. For Deploy Web services, specify whether the Web services deploy tool wsdeploy runs during application installation. The tool generates code needed to run applications using Web services. The default is not to run the wsdeploy tool. You must enable this setting if the EAR file contains modules using Web services and has not previously had the wsdeploy tool run on it, either from the Deploy menu choice of an assembly tool or from a command line.
    9. For Validate Input off/warn/fail, specify whether WebSphere ESB examines the application references specified during application installation or updating and, if validation is enabled, warns you of incorrect references or fails the operation. An application typically refers to resources using data sources for container managed persistence (CMP) beans or using resource references or resource environment references defined in deployment descriptors. The validation checks whether the resource referred to by the application is defined in the scope of the deployment target of that application. Select off for no resource validation, warn for warning messages about incorrect resource references, or fail to stop operations that fail as a result of incorrect resource references.
    10. For Process embedded configuration, specify whether the embedded configuration should be processed. An embedded configuration consists of files such as resource.xml and variables.xml. When selected or true, the embedded configuration is loaded to the application scope from the .ear file. If the .ear file does not contain an embedded configuration, the default is false. If the .ear file contains an embedded configuration, the default is true.
  5. On the Step: Map modules to servers panel, for every module select a target server or cluster from the Clusters and Servers list. Select the check box beside Module to select the mediation module.

    If the application uses a WebSphere Adapter, specify target servers or clusters for each RAR file. Also map all other modules that use the resource adapters defined in the RAR modules to the same targets.

    Note: When installing a RAR file onto a server, WebSphere ESB looks for the manifest (MANIFEST.MF) for the connector module. It looks first in the connectorModule.jar file for the RAR file and loads the manifest from the _connectorModule.jar file. If the class path entry is in the manifest from the connectorModule.jar file, then the RAR uses that class path. To ensure that the installed connector module finds the classes and resources that it needs, check the Class path setting for the RAR using the console. For more information about the Class path setting, see the Resource Adapter settings and WebSphere relational resource adapter settings for the administrative console.

    You can specify Web servers as targets that route requests to the application. The plug-in configuration file plugin-cfg.xml for each Web server is generated based on the applications which are routed through it. If you want a Web server to serve the application, use the Ctrl key to select an application server or cluster and the Web server together in order to have the plug-in configuration file plugin-cfg.xml for that Web server generated based on the applications which are routed through it.

  6. If your application defines resource references, for Step: Map resource references to resources, specify JNDI names for the resources that represent the logical names defined in resource references. Each resource reference defined in the application must be bound to a resource defined in your WebSphere ESB configuration before clicking on Finish on the Summary panel.
    1. Optional: Specify login configuration name and authentication properties for the resource.
    2. Click OK to save the values and return to the mapping step.
  7. If your application uses Web modules, for Step: Map virtual hosts for web modules, select a virtual host from the list that should map to a Web module defined in the application.

    The port number specified in the virtual host definition is used in the URL that is used to access artifacts such as servlets and JSP files in the Web module. Each Web module must have a virtual host to which it maps. Not specifying all needed virtual hosts will result in a validation error displaying after you click Finish on the Summary panel.

  8. If the application has security roles defined in its deployment descriptor then, for Step: Map security roles to users/groups, specify users and groups that are mapped to each of the security roles.

    Select Role to select all of the roles or select individual roles. For each role, you select one of the following choices for how security should be applied:

    Option Description
    Everyone This is equivalent to no security.
    All authenticated Anyone who authenticates with a valid user name and password is a member of the role.
    Mapped users Individual users are listed as members of the role.
    Mapped groups Groups are the most convenient way to add the users, every member of the identified groups becomes a member of the role.

    For Mapped users or Mapped groups, to select specific users or groups from the user registry, complete the following sub-steps:

    1. Select a role and click Lookup users or Lookup groups.
    2. On the Lookup users/groups panel displayed, enter search criteria to extract a list of users or groups from the user registry.
    3. Select individual users or groups from the results displayed.
    4. Click OK to map the selected users or groups to the role selected on the Step: Map security roles to users/groups panel.
  9. If the application has Run As roles defined in its deployment descriptor, for Step: Map RunAs roles to user, specify the Run As user name and password for every Run As role. Run As roles are used by enterprise beans that must run as a particular role while interacting with another enterprise bean. Select Role to select all of the roles or select individual roles. After selecting a role, enter values for the user name, password, and verify password and click Apply.
  10. If your application contains resource environment references, for Step: Map resource environment references to resources, specify JNDI names of resources that map to the logical names defined in resource environment references. If each resource environment reference does not have a resource associated with it, after you click Finish a validation error is displayed.
  11. If your application defines Run-As Identity as System Identity, for Step: Replace RunAs System to RunAs Roles, you can optionally change it to Run-As role and specify a user name and password for the Run As role specified. Selecting System Identity implies that the invocation is done using the WebSphere Application Server security server ID and should be used with caution as this ID has more privileges.
  12. If your application has resource references that map to resources that have an Oracle database doing backend processing, for Step: Specify the isolation level for Oracle type provider, specify or correct the isolation level to be used for such resources when used by the application. Oracle databases support ReadCommitted and Serializable isolation levels only.
  13. On the Summary panel, verify the cell, node, and server onto which the application modules will install:
    1. Beside Cell/Node/Server, click Click here.
    2. Verify the settings.
    3. Click Finish.

Result

Several messages are displayed, indicating whether your application file is installing successfully.

If you receive an OutOfMemory exception and the source application file does not install, your system might not have enough memory or your application might have too many modules in it to install successfully onto the server. If lack of system memory is not the cause of the exception, package your application again so the .ear file has fewer modules. If lack of system memory and the number of modules are not the cause of the exception, check the options you specified on the Java Virtual Machine page of the application server running the administrative console. Then, try installing the application file again.

For Windows platforms During installation certain application files are extracted in the directory represented by the configuration session and, when the configuration is saved, these files are saved in the WebSphere Application Server configuration repository. On Windows machines, there is a limit of 256 characters for file paths. Therefore, the application installation might fail if the path for application files in the configuration session or in the configuration repository exceeds the limit of 256 characters. You might see FileNotFound exceptions with path name too long in the message. To overcome such problems, make application names and module URI names shorter in length, which helps reduce the file path length. Then, try installing the application file again.

What to do next

After the application file installs successfully, complete the following actions:
  1. Associate any shared libraries that the application needs to the application.
  2. Save the changes to your configuration. The application is registered with the administrative configuration and application files are copied to the target directory, which is install_root/installedApps/cell_name by default or the directory that you designate. When installed into a Network Deployment profile, files are copied to remote nodes when the configuration on the deployment manager synchronizes with the configuration on individual nodes.
  3. If the module is deployed on a server cluster, click Rollout Update on the Enterprise Applications page to propagate the changed configuration on all members of the cluster. Rollout Update sequentially updates the configuration on the nodes that contain cluster members.

To enable WebSphere ESB to use the functions provided by a mediation module to integrate applications and services, the deployed module must be started. You can start the module manually or configure it to start automatically. You can also administer the module in other ways; for example, to change the configuration of the module, to stop or update the module, and otherwise manage its activity.


Task topic

Terms of Use | Rate this page

Timestamp iconLast updated: 13 Dec 2005
http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.wesb.doc\ae\trun_app_instwiz.html

(C) Copyright IBM Corporation 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)