Install application files with the console

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.

 

Overview

To install new enterprise application files to a WebSphere Application Server configuration, 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.

 

Procedure

  1. Click Applications > Install New Application in the console navigation tree. The first of two Preparing for application installation pages is displayed.

  2. On the first Preparing for application installation page:

    1. 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. We can also specify a standalone Web application archive (WAR) or JAR file for installation.

    2. If you are installing a standalone WAR file, specify the context root.

    3. Click Next.

  3. On the second Preparing for application installation page:

    1. 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. We can customize default values used in generating default bindings. For example, one 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.

    2. Click Next. If security warnings are displayed, click Continue. The Install New Application pages are displayed. If you chose to generate default bindings, one can proceed to the Summary step (last step below). Example: Installing an EAR file using the default bindings provides sample steps.

  4. 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.

    1. 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.

    2. 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, where the APP_INSTALL_ROOT variable is install_root/installedApps; for example, C:\WebSphere\AppServer\profiles\profile _name\installedApps\cell.

      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. 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. 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. To move the application to the APP_INSTALL_ROOT/network_cell 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.

    3. For Distribute application, specify whether WAS 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 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.

    4. 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.

    5. 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 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 V5.

      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.

    6. 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.

    7. 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.

    8. 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. We 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).

    9. 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.

    10. 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.

    11. For Validate Input off/warn/fail, specify whether WAS 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.

    12. 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.

  5. 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. We 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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 WAS configuration before clicking on Finish on the Summary panel.

  11. 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.

  12. 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, one 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:

    1. Select a role and click Lookup users or Lookup groups.

    2. On the Lookup users/groups panel displayed, enter search criteria to extract a list of users or groups from the user registry.

    3. Select individual users or groups from the results displayed.

    4. Click OK to map the selected users or groups to the role selected on the Step: Map security roles to users/groups panel.

  13. 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.

  14. 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.

  15. 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: V5 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.

  16. 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. 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. The default data source for EJB modules is optional if data sources are specified for individual CMP beans.

  17. 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. 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. 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.

  18. 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.

  19. If the Deploy enterprise beans setting is enabled on the Select installation options panel, then one can specify options for the EJBDeploy tool on the Step: Provide options to perform the EJB Deploy panel. On this panel, one 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.

  20. 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.

  21. If your application defines Run-As Identity as System Identity, for Step: Replace RunAs System to RunAs Roles, one 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 WAS security server ID and should be used with caution as this ID has more privileges.

  22. 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.

  23. 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.

  24. 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.

  25. 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.

  26. 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.

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

    1. Beside Cell/Node/Server, click Click here.

    2. Verify the settings.

    3. 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:

  1. Associate any shared libraries that the application needs to the application.

  2. 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 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.

  3. Start the application.

  4. 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.

 

See also


Preparing for application installation settings

 

See Also


Enterprise (J2EE) applications
Application bindings

 

Related Tasks


Manage shared libraries
Assembling applications
Installing applications with the wsadmin tool

 

See Also


Example: Installing an EAR file using the default bindings