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
- Click in the console navigation tree. The first of two Preparing for application installation pages
is displayed.
- On the first Preparing for application installation page, complete
the following substeps:
- 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.
- Click Next.
- On the second Preparing for application installation page,
complete the following substeps:
- 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.
- 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).
- 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.
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Optional: Specify login configuration name and authentication
properties for the resource.
- Click OK to save the values and return
to the mapping step.
- 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.
- 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:
- Select a role and click Lookup users or Lookup groups.
- On the Lookup users/groups panel displayed, enter search criteria
to extract a list of users or groups from the user registry.
- Select individual users or groups from the results displayed.
- Click OK to map the selected users or groups to the role
selected on the Step: Map security roles to users/groups panel.
- 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.
- 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.
- 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.
- 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.
- On the Summary panel, verify the cell, node, and server onto which
the application modules will install:
- Beside Cell/Node/Server, click Click here.
- Verify the settings.
- 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.
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:
- Associate any shared libraries that
the application needs to the application.
- 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.
- 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.