Installing a mediation module EAR file consists of placing the
installable EAR file for the mediation module onto a server or cluster configured
to hold the mediation module. Installed mediation modules that start and run
properly are considered deployed.
Before you begin
Before installing a mediation module EAR file, ensure that you have
used the serviceDeploy command to create an installable EAR file from the
JAR file that contains the mediation module. For more information about creating
an installable EAR file for a mediation module, see
Installing a module on a production server.
Why and when to perform this task
Required cleanup: This task needs reviewing to make it specific to a mediation module. Some steps may need changing or deleting.
To enable WebSphere Process Server 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.
Required cleanup: Is this option appropriate for mediation modules? If so, what example can we use? [Original example "For example, you can specify a Java Naming and Directory Interface (JNDI) prefix for EJB files in EJB modules, default data source and connection factory settings for EJB modules, virtual host for Web modules, and so on."]
- Click Next. If security warnings are displayed,
click Continue. The Install New Application pages are displayed. If
you chose to generate default bindings, you can proceed to the Summary step
(last step below).
- On the Step: Select installation options panel, provide
values for the following settings. Default values are used if you
do not specify a value.
- For Directory to install application, specify the directory
to 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, on Windows C:\WESB\profiles\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 Process Server 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 Process Server 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.
Required cleanup: Are only ESB servers offered, or should the administrator be told to use an ESB server? Original text " Ensure that you are installing your application onto an appropriate
deployment target"
. 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. You
can optionally specify login configuration name and authentication properties
for the resource. After specifying authentication properties, click OK to
save the values and return to the mapping step. Each resource
reference defined in the application must be bound to a resource defined in
your WebSphere Application Server configuration before clicking on Finish on
the Summary panel.
- 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 Process Server 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.