Install enterprise application files with the console

Install enterprise application files with the console

+
Search Tips | Advanced Search

Installing Java EE application files consists of placing assembled enterprise application, Web, 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 installing enterprise application files, ensure that you are installing the application files onto a compatible deployment target. If the deployment target is not compatible, select a different target.
Optionally, determine whether the application that you are installing uses library files that other deployed applications also use. We can define a shared library for each of these shared files. Using shared libraries reduces the number of library file copies on the workstation or server.
To install new enterprise application files to a WAS configuration, you can use the following options:

Administrative console
wsadmin scripts
Java MBean programs
Java programs that call Java EE Deployment Manager (JSR-88) methods

This page describes how to use the admin console to install an...

application
EJB component
SIP module
Web module

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 admin console page without first clicking Cancel on an application installation page.

Go to...

Applications | New application | New Enterprise Application

...in the console navigation tree.
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 admin console uploads the EAR file to the machine on which the console is running and proceeds with application installation.
We can also specify a stand-alone WAR, SAR, or JAR file for installation.
Click Next.

On the second Preparing for application installation page:

Select whether to view all installation options.

Fast Path - Prompt only when additional information is required

Display the module mapping step as well as any steps that require you to specify needed information to install the application successfully.

Detailed - Show all installation options and parameters

Displays all installation options.

Select Generate default bindings to have WAS supply default values for incomplete JNDI and other bindings in the application. WAS ND v7.0 does not change existing bindings.
You do not need to specify JNDI values for EJB bean, local home, remote home, or business interfaces of EJB 3.0 modules. The product assigns container default values during run time. Similarly, for any EJB reference within an EJB 3.0, Web 2.4, or Web 2.5 module, you do not need to specify JNDI values because WAS resolves the targets automatically during run time. Even when you select Generate default bindings, WAS does not generate default values for those JNDI values but it does generate default values for other bindings such as virtual host.
We 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, you can proceed to the Summary step.

Specify values for installation options as needed.
We can click on a step number to move directly to that page instead of clicking Next. The contents of the application or module that you are installing determines which pages are available.

Page Description
Select installation options Provide values for the settings specific to WAS ND. Default values are used if you do not specify a value.
Map modules to servers Specify deployment targets where you want to install the modules contained in the 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.
On single-server products, a deployment target can be...

appserver
Web server

On multiple-server products, a deployment target can be an...

appserver
cluster of appservers
Web server

Provide options to compile JSPs If the Precompile JSPs files setting is enabled on the page...
Select installation options

...and the application uses JSP files, then you can specify JSP compiler options
Provide JNDI names for beans For EJB 2.1, specify a JNDI name for every enterprise bean defined in the application. For example, for the EJB module MyBean.jar, specify MyBean.
For EJB 3.0 you can specify...

JNDI names
local home JNDI names
remote home JNDI names
no JNDI names

If you do not specify a value, WAS provides a default value.
Bind EJB business Specify business interface JNDI names for EJB 3.0 modules.
If you specified a JNDI name for the bean on the page...
Provide JNDI names for beans

...do not specify a business interface JNDI name on this page for the same bean.
If you do not specify the JNDI name for a bean, you can optionally specify a business interface JNDI name. If not specified, WAS provides a container default.
Map default data sources for modules containing 1.x entity beans If the application uses EJB modules that contain Container Managed Persistence (CMP) beans that are based on the EJB 1.x specification, for...
Map default data sources 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.
Map EJB references to beans If the application defines EJB references, you can specify JNDI names for enterprise beans that represent the logical names specified in EJB references.
If the EJB reference is from EJB 3.0, Web 2.4, or Web 2.5 module, the JNDI name is optional. For earlier modules, each EJB reference defined in the application must be bound to an EJB file.
If Allow EJB reference targets to resolve automatically is enabled, the JNDI name is optional for all modules. WAS ND v7.0 provides a container default value or automatically resolves the EJB reference for incomplete bindings.
Map resource references to resources If the application defines resource references, specify JNDI names for the resources that represent the logical names defined in resource references.
We 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.
We can optionally specify extended data source properties to enable a data source that uses heterogeneous pooling to connect to a DB2 database.
Each resource reference defined in the application must be bound to a resource defined in the WAS configuration before clicking on Finish on the Summary page.
Map virtual hosts for Web modules If the application uses 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 used to access artifacts such as servlets and JSPs 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 page.
Map security roles to users or groups If the application has security roles defined in its deployment descriptor, 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 whether 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 or groups page 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 or groups page.

Map RunAs roles to users If the application has Run As roles defined in its deployment descriptor, 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.
Ensure all unprotected 1.x methods have the correct level of protection If the application contains EJB 1.x CMP beans that do not have method permissions defined for some of the EJB methods, specify to leave such methods unprotected or assign protection with deny all access.
Bind listeners for message-driven beans If the application contains message driven enterprise beans, provide a listener port name or an activation specification JNDI name for every message driven bean.
Map default data sources for modules containing 2.x entity beans If the application uses EJB modules that contain CMP beans that are based on the EJB 2.x specification, 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.
We can optionally specify a login configuration name and authentication properties for the data source. When creating authentication properties, click OK to save the values and return to the mapping step.
We can optionally specify extended data source properties to enable a data source that uses heterogeneous pooling to connect to a DB2 database. The default data source for EJB modules is optional if data sources are specified for individual CMP beans.
Map data sources for all 2.x CMP beans If the application has CMP beans that are based on the EJB 2.x specification, 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, 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.
Ensure all unprotected 2.x methods have the correct level of protection If the application contains EJB 2.x CMP beans that do not have method permissions defined in the deployment descriptors for some of the EJB methods, specify whether you want to...

assign a specific role to the unprotected methods
add the methods to the exclude list
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.
Provide options to perform the EJB Deploy If the Deploy enterprise beans setting is enabled on the Select installation options page, then you can specify options for the EJB deployment tool.
On this page, you can specify extra class paths, RMIC options, database types, and database schema names to be used while running the EJB deployment tool.
We can specify the EJB deployment tool options on this page when installing or updating an application that contains EJB modules. The EJB deployment tool runs during installation of EJB 1.x or 2.x modules. The EJB deployment tool does not run during installation of EJB 3.0 modules.
Map shared libraries Specify shared library files for the application or Web modules to use. A defined shared library must exist to associate the application or module to the library file.
Map shared library relationships Specify relationship identifiers and composition unit names for shared libraries that modules in the enterprise application reference.
When installing your enterprise application, WAS creates a composition unit for each shared library relationship in the business-level application specified for Business-level application name on the Select installation options page.
Provide JSP reloading options for Web modules If the application uses Web modules, for Provide JSP reloading options for Web modules, configure the class reloading of JSPs.
Map context roots for Web modules If the application uses Web modules defined in the application XML deployment descriptor, for Map context roots for Web modules, specify a context root for each Web module in the application.
WAS ND v7.0 does not include Web modules from annotations on this page.
Initialize parameters for servlets If the application uses Web modules that support Servlet 2.5, for Initialize parameters for servlets, specify or override initial parameters that are passed to the init method of Web module servlet filters.
This page shows servlets from the module XML deployment descriptor. Servlet deployment information from annotations is not available on this page.
Map environment entries for Web modules If the application uses Web modules that support Servlet 2.5, for Map environment entries for Web modules, configure the environment entries of Web modules such as servlets and JSPs.
This page shows environment entries from the module XML deployment descriptor. Environment entry deployment information from annotations is not available in this page.
Map resource environment entry references to resources If the application contains resource environment references, 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.
Correct use of system identity If the application defines Run-As Identity as System Identity 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 WAS security server ID and should be used with caution as this ID has more privileges.
Correct isolation levels for all resource references If the application has resource references that map to resources that have an Oracle database doing backend processing, 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.
Bind message destination references to administered objects If the application uses message driven beans, specify the JNDI name of the J2C administered object to bind the message destination reference to the message driven beans.
If the message destination reference is from a EJB 3.0 module, then the JNDI name is optional and the run time provides a container default value.
If multiple message destination references link to the same message destination, only one JNDI name is collected. When a message destination reference links to the same message destination as a message driven bean and the destination JNDI name has been collected already, the destination JNDI name for the message destination reference is not collected.
Provide JNDI names for JCA objects If the application contains an embedded .rar file, specify the name and JNDI name of each...

J2C connection factory
J2C administered object
J2C activation specification

Bind J2C activationspecs to destination JNDI names If the application contains an embedded .rar file, its activationSpec property has the value Destination, and its introspected type is javax.jms.Destination, specify the jndiName value for each activation bound to it.
Select current backend ID, specify the backend ID representing the backend database to be used when the EJB module runs.
This step is not shown if the Deploy enterprise beans setting is enabled on the Select installation options page and if a database type other than None is specified on the page...
Provide options to perform the EJB Deploy

Metadata for modules If the application has EJB 3.0 or Web 2.5 modules, you can lock deployment descriptors for one or more of the EJB 3.0 or Web 2.5 modules.
If you set the metadata-complete attribute to true and lock deployment descriptors, WAS writes the complete module deployment descriptor, including deployment information from annotations, to XML format.
Provide options to perform the Web services deployment If the Deploy Web services setting is enabled on the Select installation options page and the application uses Web services, you can specify wsdeploy command options
For information on this page, refer to descriptions of the wsdeploy -cp and -jardir options.
Configure remote request dispatch properties Remote Request Dispatcher is a pluggable extension to the Web container that allows application frameworks, servlets and JSPs to include content from outside of the currently running resource JVM as part of the response sent to the client.
Refer to Remote dispatcher property settings

On the Summary page, verify the cell, node, and server onto which the application modules will install:

Beside Cell/Node/Server, click Click here.
Verify the settings.
Return to the Summary page.
Click Finish.

Results
Several messages are displayed, indicating whether the application file is installing successfully.
If Validate input off/warn/fail on the Select installation options page is set to warn, the default, several validation warnings might be displayed. If the setting is fail, the validation warnings might cause errors.
If you receive an OutOfMemory error and the source application file does not install, the system might not have enough memory or the 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 error, package the 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 error, check the options you specified on the Java virtual machine page of the appserver running the admin console. We might increase the maximum heap size. Then, try installing the application file again.

Next steps
After the application file installs successfully, do the following:

Save the changes to the configuration.
The application is registered with the admin configuration and application files are copied to the target directory, which is APP_ROOT/installedApps/cell_name by default or the directory that you designate.
For a single-server product, application files are copied to the destination directory when the changes are saved.
For a multiple-server product, files are copied to remote nodes when the configuration on the dmgr synchronizes with the configuration on individual nodes.
If you clicked the Save link in the application installation messages, the Preparing for the application installation page displays again. Click Applications > Application Types > WebSphere enterprise apps to exit the page and to see the application in the list of installed applications.
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, edit the application configuration.

Preparing for application installation settings
Preparing for application installation binding settings
Select installation options settings
Provide options to perform the EJB Deploy settings
Bind listeners for message-driven beans settings

Related concepts

Enterprise (Java EE) applications
Application bindings

Related tasks

Example: Installing an EAR file using the default bindings
Example: Installing a Web Services Sample with the console
Manage shared libraries
Assembling applications
Getting started with scripting
Manage applications through programming
Install enterprise apps using scripting
Install enterprise modules with JSR-88
Troubleshooting deployment

Related
Extended data source properties

Page	Description
Select installation options	Provide values for the settings specific to WAS ND. Default values are used if you do not specify a value.
Map modules to servers	Specify deployment targets where you want to install the modules contained in the 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. On single-server products, a deployment target can be... appserver Web server On multiple-server products, a deployment target can be an... appserver cluster of appservers Web server
Provide options to compile JSPs	If the Precompile JSPs files setting is enabled on the page... Select installation options ...and the application uses JSP files, then you can specify JSP compiler options
Provide JNDI names for beans	For EJB 2.1, specify a JNDI name for every enterprise bean defined in the application. For example, for the EJB module MyBean.jar, specify MyBean. For EJB 3.0 you can specify... JNDI names local home JNDI names remote home JNDI names no JNDI names If you do not specify a value, WAS provides a default value.
Bind EJB business	Specify business interface JNDI names for EJB 3.0 modules. If you specified a JNDI name for the bean on the page... Provide JNDI names for beans ...do not specify a business interface JNDI name on this page for the same bean. If you do not specify the JNDI name for a bean, you can optionally specify a business interface JNDI name. If not specified, WAS provides a container default.
Map default data sources for modules containing 1.x entity beans	If the application uses EJB modules that contain Container Managed Persistence (CMP) beans that are based on the EJB 1.x specification, for... Map default data sources 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.
Map EJB references to beans	If the application defines EJB references, you can specify JNDI names for enterprise beans that represent the logical names specified in EJB references. If the EJB reference is from EJB 3.0, Web 2.4, or Web 2.5 module, the JNDI name is optional. For earlier modules, each EJB reference defined in the application must be bound to an EJB file. If Allow EJB reference targets to resolve automatically is enabled, the JNDI name is optional for all modules. WAS ND v7.0 provides a container default value or automatically resolves the EJB reference for incomplete bindings.
Map resource references to resources	If the application defines resource references, specify JNDI names for the resources that represent the logical names defined in resource references. We 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. We can optionally specify extended data source properties to enable a data source that uses heterogeneous pooling to connect to a DB2 database. Each resource reference defined in the application must be bound to a resource defined in the WAS configuration before clicking on Finish on the Summary page.
Map virtual hosts for Web modules	If the application uses 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 used to access artifacts such as servlets and JSPs 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 page.
Map security roles to users or groups	If the application has security roles defined in its deployment descriptor, 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 whether 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 or groups page 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 or groups page.
Map RunAs roles to users	If the application has Run As roles defined in its deployment descriptor, 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.
Ensure all unprotected 1.x methods have the correct level of protection	If the application contains EJB 1.x CMP beans that do not have method permissions defined for some of the EJB methods, specify to leave such methods unprotected or assign protection with deny all access.
Bind listeners for message-driven beans	If the application contains message driven enterprise beans, provide a listener port name or an activation specification JNDI name for every message driven bean.
Map default data sources for modules containing 2.x entity beans	If the application uses EJB modules that contain CMP beans that are based on the EJB 2.x specification, 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. We can optionally specify a login configuration name and authentication properties for the data source. When creating authentication properties, click OK to save the values and return to the mapping step. We can optionally specify extended data source properties to enable a data source that uses heterogeneous pooling to connect to a DB2 database. The default data source for EJB modules is optional if data sources are specified for individual CMP beans.
Map data sources for all 2.x CMP beans	If the application has CMP beans that are based on the EJB 2.x specification, 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, 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.
Ensure all unprotected 2.x methods have the correct level of protection	If the application contains EJB 2.x CMP beans that do not have method permissions defined in the deployment descriptors for some of the EJB methods, specify whether you want to... assign a specific role to the unprotected methods add the methods to the exclude list 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.
Provide options to perform the EJB Deploy	If the Deploy enterprise beans setting is enabled on the Select installation options page, then you can specify options for the EJB deployment tool. On this page, you can specify extra class paths, RMIC options, database types, and database schema names to be used while running the EJB deployment tool. We can specify the EJB deployment tool options on this page when installing or updating an application that contains EJB modules. The EJB deployment tool runs during installation of EJB 1.x or 2.x modules. The EJB deployment tool does not run during installation of EJB 3.0 modules.
Map shared libraries	Specify shared library files for the application or Web modules to use. A defined shared library must exist to associate the application or module to the library file.
Map shared library relationships	Specify relationship identifiers and composition unit names for shared libraries that modules in the enterprise application reference. When installing your enterprise application, WAS creates a composition unit for each shared library relationship in the business-level application specified for Business-level application name on the Select installation options page.
Provide JSP reloading options for Web modules	If the application uses Web modules, for Provide JSP reloading options for Web modules, configure the class reloading of JSPs.
Map context roots for Web modules	If the application uses Web modules defined in the application XML deployment descriptor, for Map context roots for Web modules, specify a context root for each Web module in the application. WAS ND v7.0 does not include Web modules from annotations on this page.
Initialize parameters for servlets	If the application uses Web modules that support Servlet 2.5, for Initialize parameters for servlets, specify or override initial parameters that are passed to the init method of Web module servlet filters. This page shows servlets from the module XML deployment descriptor. Servlet deployment information from annotations is not available on this page.
Map environment entries for Web modules	If the application uses Web modules that support Servlet 2.5, for Map environment entries for Web modules, configure the environment entries of Web modules such as servlets and JSPs. This page shows environment entries from the module XML deployment descriptor. Environment entry deployment information from annotations is not available in this page.
Map resource environment entry references to resources	If the application contains resource environment references, 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.
Correct use of system identity	If the application defines Run-As Identity as System Identity 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 WAS security server ID and should be used with caution as this ID has more privileges.
Correct isolation levels for all resource references	If the application has resource references that map to resources that have an Oracle database doing backend processing, 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.
Bind message destination references to administered objects	If the application uses message driven beans, specify the JNDI name of the J2C administered object to bind the message destination reference to the message driven beans. If the message destination reference is from a EJB 3.0 module, then the JNDI name is optional and the run time provides a container default value. If multiple message destination references link to the same message destination, only one JNDI name is collected. When a message destination reference links to the same message destination as a message driven bean and the destination JNDI name has been collected already, the destination JNDI name for the message destination reference is not collected.
Provide JNDI names for JCA objects	If the application contains an embedded .rar file, specify the name and JNDI name of each... J2C connection factory J2C administered object J2C activation specification
Bind J2C activationspecs to destination JNDI names	If the application contains an embedded .rar file, its activationSpec property has the value Destination, and its introspected type is javax.jms.Destination, specify the jndiName value for each activation bound to it. Select current backend ID, specify the backend ID representing the backend database to be used when the EJB module runs. This step is not shown if the Deploy enterprise beans setting is enabled on the Select installation options page and if a database type other than None is specified on the page... Provide options to perform the EJB Deploy
Metadata for modules	If the application has EJB 3.0 or Web 2.5 modules, you can lock deployment descriptors for one or more of the EJB 3.0 or Web 2.5 modules. If you set the metadata-complete attribute to true and lock deployment descriptors, WAS writes the complete module deployment descriptor, including deployment information from annotations, to XML format.
Provide options to perform the Web services deployment	If the Deploy Web services setting is enabled on the Select installation options page and the application uses Web services, you can specify wsdeploy command options For information on this page, refer to descriptions of the wsdeploy -cp and -jardir options.
Configure remote request dispatch properties	Remote Request Dispatcher is a pluggable extension to the Web container that allows application frameworks, servlets and JSPs to include content from outside of the currently running resource JVM as part of the response sent to the client. Refer to Remote dispatcher property settings