Install a new application

 

To install an enterprise application to a WAS configuration, you can use the administrative console or wsadmin.sh. This document describes how to use the administrative console to install an application, EJB component, or Web module.

Note that once 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.

  1. Click...

    Applications | Install New Application

    ...in the console navigation tree. The first of two Preparing for application install pages is shown.

  2. On the first Preparing for application install page...

    1. Specify the full path name of the *.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 stand-alone WAR or JAR file for installation.

    2. If you are installing a stand-alone WAR file, specify the context root.

    3. Click Next.

  3. On the second Preparing for application install 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. You can customize default values used in generating default bindings. For example, you can specify JNDI prefix for all the 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.

      The Install New Application pages are now shown. If you chose to generate default bindings, you can proceed to the Summary step (step 23 below). "Example: Install an EAR file using the default bindings" provides sample steps.

  4. Provide options to perform the installation panel

    Default values are used if you do not specify a value.

    1. For Pre-compile JSP, specify whether to precompile JSP files as a part of installation. The default is not to precompile JSP files.

    2. For Directory to Install Application, specify the directory to which the application EAR file will be installed. Default is...

      $WAS_HOME/installedApps/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.

    4. For Use Binary Configuration, specify whether the appserver 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.

    5. For Deploy EJBs, specify whether the EJBDeploy tool runs during application installation.

      The tool generates code needed to run EJB files. The default is not to run the EJBDeploy tool. You must enable this setting if the EAR file was assembled using the Assembly Toolkit and the EJBDeploy tool was not run during assembly, if the EAR file was not assembled using the Assembly Toolkit tool, or if the EAR file was assembled using versions of the Application Assembly Tool (AAT) previous to Version 5. Note that enabling this setting might cause the installation program to run for several minutes.

    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 appserver 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. Set reloadingEnabled to true when editing your Web module's extended deployment descriptors 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, 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 overrides the value specified in the IBM extensions for each Web module in the EAR file (which in turn overrides the reload interval specified in the IBM extensions for the application in the EAR file). This setting takes effect only if class reloading is enabled.

    10. For Deploy WebServices, 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 Web Services > Deploy Web Service menu of the Assembly Toolkit or from a command line.

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

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

  7. 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 (step 23) and the installation is cancelled.

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

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

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

  11. On the Step: Map modules to appservers panel, for every module select a target server or a cluster from the Clusters and Servers list. Select the check box beside Module to select all of the application modules or select individual modules.

  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 the check box beside 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...

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

    2. On the Lookup users/groups panel shown, 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 the check box beside 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 for messaging beans, provide a listener port name for every message driven bean. If a name is not specified for each bean, then a validation error displays after you click on Finish on the Summary panel.

  16. If your application uses EJB modules that contain CMP beans that are based on the EJB 2.0 specification, for Step: Provide default datasource mapping for modules containing 2.0 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. 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.0 specification, on the Step: Map datasources for all 2.0 CMP panel, for each of the 2.0 CMP beans specify a JNDI name and the type of resource authorization for data sources to be used. 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 shown after you click Finish and installation is cancelled.

  18. If your application contains EJB 2.0 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.0 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 EJBs setting is enabled on the Provide options to perform the installation 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 path, 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... Mapping 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, a validation error is shown after you click Finish.

  21. If your application defines Run-As Identity as System Identity, for Step: Replacing 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 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. On the Summary panel, verify the cell, node, and server onto which the application modules will install. Beside the Cell/Node/Server option, click Click here and verify the settings. Then click Finish.

    Note: After clicking Finish, 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 appserver running the administrative console. Then, try installing the application file again.

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

  25. Click Save on the administrative console taskbar to save the changes to your configuration. The application is registered with the administrative configuration and application files are copied to the target directory...

    $WAS_HOME/installedApps/cell
    ...by default or the directory that you designate.

    For the single-server (base) installation, application files are copied to the destination directory when you click Save.

    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.

  26. Start the application.

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

Enterprise applications
Managing shared libraries
Assembling applications with the Assembly Toolkit
Install applications using wsadmin.sh
Preparing for application installation settings
Example: Install an EAR file using the default bindings