The product application management architecture provides a set of classes that allows application developers to collect WebSphere® Application Server-specific deployment information, hereafter called binding information, and store it in the application EAR file. Such an EAR file can then be installed into a WebSphere Application Server configuration, using application management interfaces that are described in the topic Installing an application through programming. This topic uses a programming example to explain how an EAR file can be populated with binding information.
This task assumes a basic familiarity with WebSphere Application Server programming interfaces and MBean programming. Read about WebSphere Application Server programming interfaces and MBean programming in the application programming interfaces documentation.
Complete the following tasks to prepare an application for installation through programming.
// create preferences to pass in the locale information Hashtable prefs = new Hashtable(); prefs.put(AppConstants.APPDEPL_LOCALE, Locale.getDefault()); // create a controller instance for EAR file // specified by a fully-qualified path in earName AppDeploymentController flowController = AppManagementFactory.readArchive (earName, prefs);
Name | Description | Value |
---|---|---|
appController | A controller instance that manages tasks. | AppDeploymentController |
colNames | The task column names | java.lang.String[] |
hasHiddenColumns | Specifies whether the task has any hidden columns. | boolean |
HiddenColumns | An array of boolean that indicates that these columns should not be shown by the tool that displays the tasks to the end user. | boolean[] |
HIGHEST_VERSION | Public static final java.lang.String HIGHEST_VERSION | static java.lang.String |
isSufficientlyDone | Specifies whether the task has any required data that is not specified. | boolean |
isTaskDisabled | Specifies whether the task should be shown or changed. | boolean |
isTaskEmpty | Specifies whether the task has any data in it. | boolean |
isValidationEnabled | Specifies whether the task should be validated | boolean |
mutables | An array of boolean indicating if the task data in a specific column index can be changed by the person who is deploying the application. | boolean[] |
name | A unique task name | java.lang.String |
requiredColumns | An array of boolean indicating if a task column must have a non-null value. | boolean[] |
taskData | A 2-dimensional array (table) of strings. The first row of the table contains the column headings for the task (e.g. name of the module, module URI, JNDI name etc). The rest of the rows represent application-specific information. | java.lang.String[] |
taskValidateErrorMessages | The error messages that are generated when a task is validated | java.lang.String[] |
VERSION_HIGHEST | public static final int VERSION_HIGHEST | static int |
The following table lists various task names that are typically created by the AppDeploymentController for a J2EE 1.2, J2EE 1.3, or a Java™ EE 5 or later application. You might notice more tasks if the application contains WebSphere Application Server enterprise extensions.
AppDeploymentTask name | Description | Task column names |
---|---|---|
MapRolesToUsers | Allows you to specify users or groups for a security role. You must map each role that is defined in the application or module to a user or group from the domain user registry. Each row of task data represents a single security role. You can specify multiple users or groups for a single role by separating them with a quotation mark ("). |
|
MapRunAsRolesToUsers | Allows you to specify credentials for a run-as role.. The enterprise beans that you install contain predefined RunAs roles. Enterprise beans that need to run as a particular role for recognition while interacting with another enterprise bean use RunAs roles. Each row of task data represents a single run-as role. |
|
BindJndiForEJBNonMessageBinding | Allows you to specify JNDI names for enterprise java beans (EJBs). This JNDI name is used to look up EJB Homes from client programs. A row of task data specifies a single EJB for which a JNDI name can be supplied. |
|
BindJndiForEJBMessageBinding | Allows you to specify a listener port name or JNDI of an activation specification for message-driven beans (MDBs). Ensure each MDB in your application or module is bound to a listener port name or JNDI of an activation specification. Each row of task data represents a single message-driven bean. |
|
BindJndiForEJBBusiness | Allows you to specify JNDI name bindings for each enterprise bean with a business interface in an EJB module. Each enterprise bean with a business interface in an EJB module must be bound to a JNDI name. A row of task data specifies a single enterprise bean for which a JNDI name can be supplied. |
|
MapEJBRefToEJB | Allows you to specify JNDI names of EJBs that
are bound to ejb-refs. Each row of task data represents a single ejb-ref
defined in a module, An EJB 3.0 module cannot contain container-managed or bean-managed persistence entity beans. Installation fails when a container-managed or bean-managed persistence entity bean is packaged in a EJB 3.0 module of a Java EE application. You can only package container-managed or bean-managed persistence in an EJB 2.1 or earlier module. If the EJB reference is from an EJB 3.0, Web 2.4, or Web 2.5 module, the JNDI name is optional. If the Allow EJB reference targets to resolved automatically option is enabled, the JNDI name is optional for all modules. The runtime provides a container default or automatically resolves the EJB reference if a binding is not provided. |
|
MapResRefToEJB | Allows you to specify JNDI names of resources defined in WebSphere Application Server configuration that are bound to resource-refs. Each row of task data represents a single resource-ref defined in amodule. |
|
MapResEnvRefToRes | Allows you to specify the JNDI names of resources defined in the WebSphere Application Server configuration that are bound to resource-env-refs. Each row of task data represents a single resource-env-ref defined in a module. |
|
MapSharedLibForMod | Allows you to associate defined shared libraries with an application or Web module. A shared library is an external Java archive (JAR) file that is used by one or more applications. Using shared libraries enables multiple applications deployed on a server to use a single library, rather than use multiple copies of the same library. After you associate shared libraries with an application or module, the application or module class loader loads classes represented by the shared libraries and makes those classes available to the application or module. Each row of task data represents a single application or Web module. |
|
SharedLibRelationship | Allows you to specify relationship identifiers and composition unit names for shared libraries that modules in your enterprise application reference. When installing your enterprise application, the product creates a composition unit for each shared library relationship in the business-level application that you specified. Each row of task data represents a single application or Web module. |
|
CtxRootForWebMod | Allows you to specify the context root for Web modules during or after installation of an application onto a WebSphere Application Server deployment target. Each row of task data represents a single Web module. |
|
MapInitParamForServlet | Allows you to specify initial parameter values for servlets in Web modules during or after installation of an application onto a WebSphere Application Server deployment target. The <param-value> values specified in <init-param> statements in the web.xml file of Web modules are used by default. Each row of task data represents a single servlet. |
|
MapEnvEntryForEJBMod | Allows you to configure the environment entries of Enterprise JavaBeans™ (EJB) modules such as entity, session, or message driven beans. Each row of task data represents a single environment entry in an EJB module. |
|
MapEnvEntryForWebMod | Allows you to configure the environment entries of Web modules such as servlets and JavaServer Pages (JSP) files. Each row of task data represents a single environment entry in a Web module. |
|
MapMessageDestinationRefToEJB | Allows you to specify the JNDI name of the J2C administered object to bind the message destination reference to the message driven beans. Each row of task data represents a single message destination reference in a module. |
|
DataSourceFor10EJBModules | Allows you to specify JNDI name of the default data source used for an EJB module that contains EJB1.x beans. Each row of task data represents a single EJB module. |
|
DataSourceFor20EJBModules | Allows you to specify JNDI name of the default connection factory used for an EJB module that contains EJB2.x beans. Each row of task data represents a single EJB module. |
|
DataSourceFor10CMPBeans | Allows you to specify JNDI name of the data source to be used for an EJB1.x bean with container managed persistence. A row of task data represents a single EJB. |
|
DataSourceFor20CMPBeans | Allows you to specify JNDI name of the connection factory to be used for an EJB2.x bean with container managed persistence. A row of task data represents a single EJB. |
|
MapWebModToVH | Allows you to specify virtual hosts for Web modules. Each row of task data represents a Web module in the application for which virtual host information is to be collected. Web modules can be installed on the same virtual host or dispersed among several virtual hosts. Each row of task data represents a single Web module. |
|
EnsureMethodProtectionFor10EJB | Allows you to specify if all unprotected methods of an EJB1.x module should be made inaccessible. Each task row represents a single EJB1.x module. |
|
EnsureMethodProtectionFor20EJB | Allows you to specify protection level for unprotected methods of EJB2.x beans in EJB modules. Each row of task data specifies method protection per EJB module. |
|
AppDeploymentOptions | Allows you to specify various deployment-specific
options. This task has only 2 rows. The first row specifies the option
name and the second row has the corresponding option value. The following
values are the valid values for these options unless otherwise indicated
in the option description:
|
The options names that can be specified are:
|
JSPReloadForWebMod | Allows you to configure the class reloading of Web modules such as JavaServer Pages (JSP) files and to select a JSF implementation to use with this application. Each row of task data represents a single Web module. |
|
EJBDeployOptions | Allows you to specify options for the enterprise bean (EJB) deployment tool. The tool generates code needed to run enterprise bean files. You can specify extra class paths, Remote Method Invocation compiler (RMIC) options, database types, and database schema names to be used while running the EJB deployment tool. |
|
JSPCompileOptions | Allows you to specify various options to be used by the JavaServer Pages (JSP) compiler. |
|
MapModulesToServers | Allows you to specify the target servers or clusters for modules in an application. Each row of task data represents one module in the application. The server target is specified as WebSphere:cell=cellName,node=nodeName,server=serveName, and the cluster target is specified as WebSphere:cell=cellName,cluster=clusterName. Multiple targets can be specified for a given module by delimiting them with "+". Each row of task data represents a single module. |
|
CorrectUseSystemIdentity | Allows you to manage the system identity properties for the Enterprise JavaBeans™ (EJB) method in your application. |
|
CorrectOracleIsolationLevel | Allows you to specify the isolation level for the Oracle type provider for resource references that map to resources that are using an Oracle database that is doing backend processing. Each row represents one resource reference that maps to an Oracle database resource. |
|
ActSpecJNDI | Allow you to provide JNDI names for JCA objects of embedded resource adapter modules. |
|
BackendIdSelection | Allows you to change the backend ID for the enterprise bean Java archive (JAR) modules that have container-managed persistence (CMP) beans. An enterprise bean JAR module can support multiple backend configurations as specified using an application assembly tool. This task is useful if your application has EJB modules for which deployment code has been generated for multiple backend databases using an assembly tool. |
|
MetadataCompleteForModules | Allows each EJB 3.0 module or Web 2.5 module to write out the complete deployment descriptor including deployment information from annotations. Then the system marks the deployment descriptor for the module as complete. Each row of task data represents a single module. |
|
The URI column in various tasks uniquely identifies a module in the application using the format as its value, where moduleURI is the module file name defined in the application's deployment descriptor, and ddURI is the URI of the deployment descriptor within the module (for standard deployment descriptor) or the URI of the alternate deployment descriptor for the module, as defined in the application's deployment descriptor. For example, if an application has a Web module in MyWeb.war and the module uses a standard deployment descriptor, then the value of the URI column in various tasks for this module is MyWeb.war,WEB-INF/web.xml. Thus the URI column value always guarantees a unique identification of a module.
The following code excerpt shows how to obtain tasks from AppDeploymentController:
AppDeploymentTask task =flowController.getFirstTask(); while (task != null) { // manipulate task data as necessary task = flowController.getNextTask(); }
Using task name, task column names, and the J2EE artifact for which binding information is to be supplied, the task data can be modified if the corresponding column is marked as mutable. The following sample code shows how binding information can be supplied for a specific task. In this example, we are specifying users for a security role: consider that the application has a security role named Role1, and that you need to assign users User1 and User2 to that role:
if (task.getName().equals ("MapRolesToUsers") && !task. isTaskDisabled()) { // find out column index for role and user column // refer to the table above to find the column names int roleColumn = -1; int userColumn = -1; String[] colNames = task.getColumnNames(); for (int i=0; i < colNames.length; i++) { if (colNames[i].equals ("role")) roleColumn = i; else if (colNames[i].equals ("role.user")) userColumn = i; } // iterate over task data starting at row 1 as row0 is // column names String[][]data = task.getTaskData(); for (int i=1; i < data.length; i++) { if (data[i][roleColumn].equals ("Role1")) { data[i][userColumn]="User1|User2"; break; } } // now that the task data is changed, save it back task.setTaskData (data); }
Similar logic can be used to specify all other types of binding information, such as JNDI names for EJBs, virtual host names for Web modules, etc., in various tasks. The task information and the sample code above do not allow you to collect binding information for application client modules. You need to use the Client Configuration tool shipped with WebSphere Application Server to configure application clients.
After all the necessary binding information has been supplied in various tasks, the task data should be saved back into the EAR file so that the populated EAR file can be installed into the WebSphere Application Server configuration. In addition to the binding information that is stored in the EAR file, there are several other deployment options that are collected by tasks, such as AppDeploymentOptions, EJBDeployOptions, and MapModulesToServers. These options are not saved in the EAR file but should be passed when the application is installed into the WebSphere Application Server configuration. After the task data is manipulated as necessary and the EAR file is saved, these options can be obtained from AppDeploymentController as a hash table. Alternately, these options can be passed directly during application installation, as explained in the Installing applications section below, and in the javadoc for installApplication API of com.ibm.websphere.management.application.AppManagement interface.
The following code shows how to save the task data into the EAR file and get generated installation options:
// the following line of code saves the task data // in the EAR file specified as earName in step 1 flowController.saveAndClose(); // get the installation options Hashtable options = flowController.getAppDeploymentSavedResults();
Use programming to install the application.
In this information ...Related tasks
| IBM Redbooks, demos, education, and more(Index) Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience. This feature requires Internet access. Most of the following links will take you to information that is not part of the formal product documentation and is provided "as is." Some of these links go to non-IBM Web sites and are provided for your convenience only and do not in any manner serve as an endorsement by IBM of those Web sites, the material thereon, or the owner thereof. |