Installing application files consists of placing assembled enterprise
application, Web, enterprise bean (EJB), or other installable modules on a
server or cluster configured to hold the files. Installed files that start
and run properly are considered deployed.
Before you begin
Before installing enterprise application files, ensure that you are
installing your application files onto a
compatible deployment target. If the deployment target
is not compatible, select a different target.
Why and when to perform this task
To install new enterprise application files to a WebSphere Application
Server configuration, you can use the administrative console, the
wsadmin tool, or
Java
programs that call J2EE DeploymentManager (JSR-88) methods. This article
describes how to use the administrative console to install an application,
EJB component, or Web module.
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.
Steps for this task
- Click Applications > Install New Application in the console
navigation tree. The first of two Preparing for application
installation pages is displayed.
- On the first Preparing
for application installation page:
- Specify the full path name of the source enterprise application
file (.ear file otherwise known as an EAR file). The
EAR file that you are installing can be either on the client machine (the
machine that runs the 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. You can
also specify a standalone Web application archive (WAR) or Java archive (JAR)
file for installation.
- If you are installing a standalone WAR file, specify the context
root.
- Click Next.
- On the second Preparing
for application installation page:
- 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. 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. Preparing for application installation settings describes available customizations and provides sample
bindings.
- 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). Example: Installing an EAR file using the default bindings provides sample steps.
- On the Step: Select installation options panel, provide
values for the following settings specific to WebSphere Application Server.
Default values are used if you do not specify a value.
- For Pre-compile JSP, specify whether to precompile JavaServer
page (JSP) files as a part of installation. The default is not
to precompile JSP files. Install onto a 6.x
deployment target. If you select Pre-compile JSP and try installing
your application onto a 5.x deployment target, the installation is rejected.
For this option, install only onto a 6.x deployment target.
- 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, C:\WebSphere\AppServer\profiles\profile
_name\installedApps\cell_name.
Note: If an installation directory is not specified
when an application is installed on a single-server (base) configuration,
the application is installed in APP_INSTALL_ROOT/base_cell_name.
When the base server is made a part of a Network Deployment configuration
(using the addNode utility), the cell name of the new 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 base server is 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
Application 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 application
server 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. The default is not to use the
binary configuration. If you select Use Binary Configuration, your
application files must be installed onto a 6.x deployment target. The files cannot be installed
onto a 5.x deployment target.
- For Deploy enterprise beans, specify whether the EJBDeploy
tool runs during application installation. The tool generates
code needed to run EJB files. You must enable this setting in the following
situations:
- The EAR file was assembled using an assembly tool such as Rational Application
Developer, Rational Web Developer or Application Server Toolkit (AST) and
the EJBDeploy tool was not run during assembly.
- The EAR file was not assembled using an assembly tool.
- The EAR file was assembled using versions of the Application Assembly
Tool (AAT) previous to Version 5.
Enabling this setting might cause the installation program
to run for several minutes. Also, install onto a 6.x
deployment target. If you select Deploy enterprise beans and
try installing your application onto a 5.x deployment target, the installation
is rejected. For this option, install only onto a 6.x deployment target.
- For Application name, name the application. Application
names must be unique within a cell and cannot contain characters that are not allowed in 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. For EJB modules or any non-Web
modules, enabling class reloading sets reloadEnabled to true in the deployment.xml file
for the application. If an application's class definition changes, the application
server run time stops and starts the application to reload application classes.
For
Web modules such as servlets and JSP files, a Web container reloads a Web
module only when the IBM extension reloadingEnabled in the ibm-web-ext.xmi file
is set to true. You can set reloadingEnabled to true when
editing the extended deployment descriptors of your Web module in an assembly
tool.
To disable reloading of a Web module, set the IBM extension reloadingEnabled
in the ibm-web-ext.xmi file to false. Or, if the Web module
has the IBM extension reloadingEnabled in the ibm-web-ext.xmi file
set to true, enable class loading, and set the Reload interval property
to zero (0).
- 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. Note that if you select Deploy and
try installing your application onto a 5.x
deployment target, the installation is rejected. For this option, install
only onto a 6.x deployment target.
- For Validate Input off/warn/fail, specify whether WebSphere
Application 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 all of the application
modules or select individual modules. 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 uses EJB modules, on the Step: Provide JNDI
Names for Beans panel, specify a JNDI name for each enterprise bean in
every EJB module. You must specify a JNDI name for every enterprise
bean defined in the application. For example, for the EJB module MyBean.jar,
specify MyBean.
- If your application uses EJB modules that contain Container Managed
Persistence (CMP) beans that are based on the EJB 1.x specification, for Step:
Provide default datasource mapping for modules containing 1.x entity beans,
specify a JNDI name for the default data source for the EJB modules.
The default data source for the EJB modules is optional if data sources
are specified for individual CMP beans.
- If your application has CMP beans that are based on the EJB 1.x
specification, for Step: Map datasources for all 1.x CMP, specify a
JNDI name for data sources to be used for each of the 1.x CMP beans.
The data source attribute is optional for individual CMP beans if a
default data source is specified for the EJB module that contains CMP beans.
If neither a default data source for the EJB module nor a data source for
individual CMP beans are specified, then a validation error displays after
you click Finish and the installation is cancelled.
- If your application defines EJB references, for Step: Map EJB
references to beans, specify JNDI names for enterprise beans that represent
the logical names specified in EJB references. Each EJB reference
defined in the application must be bound to an EJB file before clicking Finish on
the Summary panel.
- 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 can
specify if predefined users such as Everyone or All authenticated
users are mapped to it. To select specific users or groups from the user
registry:
- 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 EJB 1.x CMP beans that do not have
method permissions defined for some of the EJB methods, for Step: Ensure
all unprotected 1.x methods have the correct level of protection, specify
if you want to leave such methods unprotected or assign protection with deny
all access.
- If your application contains message driven enterprise beans, for Step:
Provide Listener Ports or activation specification JNDI name for messaging
beans, provide a listener port name or an activation specification JNDI
name for every message driven bean. A listener port name must
be provided when using the JMS providers: Version 5 default messaging, WebSphere
MQ, or generic. An activation specification must be provided when the application's
resources are configured using the default messaging provider or any generic
J2C resource adapter that supports inbound messaging. If neither
is specified, then a validation error is displayed after you click Finish on
the Summary panel. Also, if the module containing the message driven bean
is deployed on a 5.x deployment target and
a listener port is not specified, then a validation error is displayed after
you click Next.
- If your application uses EJB modules that contain CMP beans that
are based on the EJB 2.x specification, for Step: Provide default datasource
mapping for modules containing 2.x entity beans, specify a JNDI name for
the default data source and the type of resource authorization to be used
for the default data source for the EJB modules. You can optionally
specify a login configuration name and authentication properties for the data
source. When creating authentication properties, you must click OK to
save the values and return to the mapping step. The default data source for
EJB modules is optional if data sources are specified for individual CMP beans.
- If your application has CMP beans that are based on the EJB 2.x
specification, on the Step: Map datasources for all 2.x CMP panel,
for each of the 2.x CMP beans specify a JNDI name and the type of resource
authorization for data sources to be used. You can optionally
specify a login configuration name and authentication properties for the data
source. When creating authentication properties, you must click OK to
save the values and return to the mapping step. The data source attribute
is optional for individual CMP beans if a default data source is specified
for the EJB module that contains CMP beans. If neither a default data source
for the EJB module nor a data source for individual CMP beans are specified,
then a validation error is displayed after you click Finish and installation
is cancelled.
- If your application contains EJB 2.x CMP beans that do not have
method permissions defined in the deployment descriptors for some of the EJB
methods, on the Step: Ensure all unprotected 2.x methods have the correct
level of protection panel, specify whether you want to assign a specific
role to the unprotected methods, add the methods to the exclude list, or mark
them as unchecked. Methods added to the exclude list are marked
as uncallable. For methods marked unchecked no authorization check is performed
prior to their invocation.
- If the Deploy enterprise beans setting is enabled on the Select
installation options panel, then you can specify options for the EJBDeploy
tool on the Step: Provide options to perform the EJB Deploy panel.
On this panel, you can specify extra class paths, RMIC options, database
types, and database schema names to be used while running the EJBDeploy tool.
The tool is run on the EAR file during installation after you click Finish.
- 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.
- If your application uses message driven beans, for Step: Build
message destination to administered objects, specify the JNDI name of
the J2C administered object to bind the message destination reference to the
message driven beans.
- If your application contains an embedded .rar file, for Step:
Map JCA resources to resources, specify the name and JNDI name of each
J2C connection factory, J2C administered object and J2C activation specification.
- If your application contains an embedded .rar file, its
activationSpec property has the value Destination, and its introspected
type is javax.jms.Destination, for Step: Bind J2CActivationSpec
to Destination Jndi name, specify the jndiName value for each activation
bound to it.
- If your application has EJB modules for which deployment code has
been generated for multiple backend databases using an assembly tool, for Step:
Select a backend ID, specify the backend ID representing the backend database to be used
when the EJB module runs.
- 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, do the following:
- 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. For the Network Deployment installation, files are copied
to remote nodes when the configuration on the deployment manager synchronizes
with the configuration on individual nodes.
- Start the application.
- Test the application. For example, point a Web browser at the URL for
the deployed application and examine the performance of the application. If
necessary, update the application.