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 Select installation
options panel, provide values for the settings specific to WebSphere
Application Server. Default values are used if you do not specify
a value.
- On the Map modules to
servers panel, specify deployment
targets where you want to install the modules contained in your application.
Modules can be installed on the same deployment target or dispersed
among several deployment targets. Each module must be mapped to a target server.
A deployment target can be an application server or Web server.
- If your application uses EJB modules, on the 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.
Refer to Provide
JNDI Names for Beans help.
- If your application uses EJB modules that contain Container Managed
Persistence (CMP) beans that are based on the EJB 1.x specification, for 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 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 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.
Refer to Map
EJB references to beans help.
- If your application defines resource references, for 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 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 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 Map security roles to users/groups panel.
- If the application has Run As roles defined in its deployment descriptor,
for 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 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 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 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 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 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 EJB deployment tool on the 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 EJB deployment tool. The tool is
run on the EAR file during installation after you click Finish.
- If your application contains resource environment references, for 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 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 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 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 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 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 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
a single-server installation, application files are copied to the destination
directory when the changes are saved.
- 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.