System administration for WebSphere Application Server V7: Part 5: Business-level applications

Business-level applications, introduced in IBM® WebSphere® Application Server V7.0, provide improved management and operational capabilities over standalone Java™ EE applications. A business-level application is a single logical application into which Java EE applications can be grouped, such that a start or stop operation at the so-called business level would trigger a coordinated start or stop on all member applications in the group. Business-level applications also provide better management of shared libraries: shared libraries not contained in a Java EE application archive can be imported into a WebSphere Application Server configuration and added to a business-level application, and Java EE applications added to the same business-level application can be configured to declare a run time dependency on such shared libraries. This article describes general business-level application constructs and explains how to leverage this new capability. This content is part of the IBM WebSphere Developer Technical Journal.

Will Edwards (wme@us.ibm.com), Advisory Software Engineer, IBM

Will Edwards is an advisory software engineer at the IBM lab in Austin, Texas. Will has worked on the WebSphere Application Server product for the past nine years, and on application management for the past two years.



Cindy Schneider (cindysch@us.ibm.com), Advisory Softfware Engineer, IBM

Cindy Schneider is an advisory software engineer at the IBM lab in Austin, Texas. Cindy has worked on the WebSphere Application Server administrative console since Version 6.0.



Ray Clement (rclemen@us.ibm.com), Software Engineer, IBM

Ray Clement is a software engineer at the IBM lab in Austin, Texas. Ray has worked on the WebSphere Application Server system management test team for the past two years. He led the functional testing effort for business-level applications in WebSphere Application Server Version 7.0.



20 May 2009

Also available in Chinese

Introduction

One factor that led to the advent of business-level applications is a limitation in the Java EE packaging model. The notion of a Java EE application is tightly coupled to the packaging structure, such as an EAR file. That is, the contents of an EAR correspond to an application. There is no Java EE application construct that spans EARs, which is limiting because applications are often very large to the extent that it is not practical to package the entire application into a single EAR. What is desirable is some higher level construct that can group EARs together into one logical entity.

A business-level application is that higher level construct. You can use a business-level application to group multiple Java EE applications together and, through this mechanism, start and stop a collection of applications with a single start or stop command. Figure 1 illustrates the compositional structure of a business-level application.

Figure 1. Business-level application conceptual view
Figure 1. Business-level application conceptual view

So, what are some the benefits of business-level applications?

  • Deployable artifacts, such as Java EE archives, can be assembled together to form a composite which comprises the business-level application. In Figure 1, notice that the binaries are separated from the metadata that is necessary to deploy the binaries. This enables a single binary to be deployed multiple times, where each deployment consists of a different set of metadata. Notice also that a business-level application composite can consist of another business-level application, further enhancing the flexibility of the composite model. The composition elements, composition units, and assets are described in more detail later.

  • Another limitation you might encounter is the handling of libraries. Library classes can be packaged into EAR files, but packaging a library inside an EAR can complicate the management of libraries that are shared among multiple EARs. In addition, that packaging scheme does not facilitate sharing in library class loaders (enabling the sharing of singleton library java.lang.Class objects and sharing of singleton library objects among multiple applications). Prior to V7.0, WebSphere Application Server permitted the sharing of libraries, including singleton object instances, but you had to manually deploy those libraries to target nodes. Ideally, you should be able to deploy shared libraries to a WebSphere Application Server cell in much the same way you deploy applications, and configure dependent applications so that an application's class loader resolves shared library classes upon which it is dependent.

    The business-level application design improves the handling of shared libraries. Now, a shared library can be imported into a WebSphere cell and then added to a business-level application along with Java EE applications. Java EE application configuration steps in WebSphere Application Server V7.0 enable you to declare dependencies on imported shared libraries, and the shared library binaries will be distributed to target nodes along with the dependent applications.

  • The Java EE programming model does not provide the means for Web applications to share HTTP session data. Business-level application functionality gives Web modules access to a shared session object, while each also maintains separate, non-shared HTTPSession objects. IBMApplicationSession is a new object that can be shared by all Web modules in a business-level application.

  • Besides addressing limitations related to Java EE applications, business-level applications satisfy another requirement that is more internal in nature. As the capabilities of WebSphere Application Server expand, the types of artifacts (content) that can be deployed to a WebSphere cell must also expand, beyond Java EE artifacts. Furthermore, deployable content must be supported in an extensible way so that knowledge of a particular type of content is not known a priori.

    Business-level application functionality facilitates deployment of non-Java EE artifacts in an extensible way. WebSphere Application Server achieves this through a framework that so-called "content handlers" can be plugged into. One notable example of a content handler that exploits business-level application extensibility is the IBM WebSphere Application Server V7.0 Feature Pack for Service Component Architecture (SCA) 1.0, which enables deployment of SCA contributions to a WebSphere Application Server cell. An SCA contribution can consist of multiple composites. When you deploy an SCA contribution to run, you select one of the composites. The contribution can be deployed a number of times, each time with a different composite selected.

    Business-level application extensibility is also leveraged in the WebSphere Application Server product itself. Version 7.0 uses business-level applications to support the deployment of user-written custom proxy filters as add-ons to extend base proxy functionality. By installing proxy filters as business-level application assets, proxy filters can be deployed to remote proxy servers by the product runtime instead of you having to manually copy the proxy filter JAR to the remote node. In addition, you can stop and restart proxy filters easily at run time by stopping or restarting the parent business-level application from the administrative console or a script.

  • Business-level application functionality enables different supported types of artifacts to be configured as components of the same logical application, that is, the same business-level application.

Business-level application-related objects are managed through a set of AdminTask commands, executable through the wsadmin scripting tool. The administrative console also contains business-level application management panels that are based on those same commands. See the WebSphere Application Server V7.0 Information Center for detailed documentation on business-level application commands.


Understanding business-level application concepts

Here are some important constructs you need to understand when working with business-level applications:

  • Asset

    An asset is the smallest unit of management for application content in the business-level application architecture. It is a physical binary that implements business logic and has been imported into a WebSphere Application Server cell. Assets are deployed to target servers and clusters by adding them to business-level applications. A file can be imported as an asset only if its contents are recognized by the system as content that can be deployed as part of a business-level application.

    Conceptually, the file format is distinct from the actual content. An asset can be a single file, an archive of files (such as a .zip or JAR file), or an archive of archives (such as a Java EE EAR). Business-level application design enables the range of recognizable content to be expanded by WebSphere stack products and feature packs. Business-level application function includes built-in support for Java EE application archives and generic Java archive files (JARs) for use as shared libraries.

    Regardless of its composition, an asset is always managed as a single entity and should be accessible to every run time environment (such as WebSphere Application Server) that executes business logic embedded in the asset.

  • Deployable unit

    A deployable unit is the smallest portion of an asset that can be individually chosen for deployment (that is, to create a composition unit). Each deployable unit is independently targetable, for example, to some server or cluster.

    By default, there is only one deployable unit in an asset, and it represents the entire asset itself. Content handlers can override the default behavior and specify finer-grained deployable units for an asset during import operations. For example, the deployable units in an EAR file correspond to the modules within the EAR. As another example, for SCA contributions imported as assets, each composite maps to a deployable unit.

    Deployable units are named entities and are included in metadata that is created and saved when an asset is imported into a WebSphere Application Server configuration repository. As the smallest unit of management for deployable content, an asset is not physically split into deployable units during deployment or during distribution to the server runtime.

  • Business-level application

    Business-level applications are collections of zero or more composition units. Grouping components into a single logical application enables common operational control over all of the components through operations performed on the business-level application. For example, starting or stopping a business-level application starts or stops all composition units of that business-level application. Composition units are configured for a specific business-level application and hence cannot be shared among several business-level applications. The business-level application structure is hierarchical in that one business-level application can be added to another business-level application.

  • Composition unit

    The process of deploying an asset by adding it to a business-level application composition requires configuring that asset such that its contents can interact with other business-level application components, as well as with the runtime environment in which the business logic of the asset runs. An asset added to a business-level application is represented by a composition unit. A composition unit based on an asset contains configuration metadata that binds contents of the asset with a specific hosting runtime, and adds the IT layer configuration necessary for that asset to be loaded and executed by the runtime.

    A composition unit must be created from only one asset. However, multiple composition units can share a single asset. This is particularly useful in scenarios where the same application binaries are used with different configurations to provide different runtime behavior. These rules apply to a composition unit:

    • Because a composition unit contains application specific configuration data, it cannot be shared among multiple business-level applications.
    • A composition unit cannot exist without a business-level application. One is always created in the context of a business-level application.

    There are ways to create a composition unit other than by adding an asset to a business-level application. One way is to add a business-level application to another business-level application. This creates a composition unit based on the nested business-level application. Another way is to install a Java EE application using the legacy application management interfaces. These legacy interfaces have been revised to implicitly create a business-level application and composition unit, but the application archive is not actually imported as an asset. (A new optional parameter enables specification of a business-level application name. If a business-level application with the specified name does not exist, one is created.) The resulting composition unit is backed by the actual Java EE application installation structure in the configuration repository rather than a Java EE archive imported as an asset.

    When you deploy a Java EE application, either as an imported asset or through the legacy application management interfaces, the legacy application installation structure is still used. That is, the configuration structure under the cell-level applications directory is created, and the legacy destination directory (default root of profileRootDIR/installedApps) is used.

  • Control operation

    Control operations exist at both the business-level application and composition unit level. Control operations differ from configuration operations in that control operations do not affect the configuration of the business-level application or composition unit. Instead, they typically are used to change or query the run time state of a business-level application or composition unit.

    A control operation defined on a business-level application carries out some action that has meaning in the context of the business-level application itself. Some business-level application control operations drive control operations on a business-level application’s constituent composition units necessary to carry out the control operation. Start and stop are the only pre-defined business-level application control operations and are the only business-level application control operations currently supported. These operations drive start and stop operations on all constituent composition units of the specified business-level application. If a composition unit is backed by a nested business-level application, the control operation is recursively driven down to the nested business-level application's constituent composition units.

    Composition unit control operations map to low level IT operations, such as start and stop. Control operations are useful for IT administrators for controlling a composition unit in a run time environment. Business-level application control operations generally should drive composition unit control operations that affect the run time state. Invoking those operations directly on composition units should be reserved for special situations (for example, an emergency stop), as it may not be possible to recognize the impact of the operation in the context of an entire application composition. As with business-level applications, start and stop operations are the only pre-defined composition unit control operations. Each composition unit must support, at a minimum, start and stop in order to support business-level application start and stop operations.

  • Destination directory

    The run time environment that runs business logic embedded in a given asset often requires that the contents of the asset be extracted to a file system at a location and in a format that is accessible to the run time environment. The destination directory contains the asset in a form required by the run time environment. The destination directory is an attribute of an asset's configuration and is created on each node that contains a target server or cluster member. The default destination directory name is profileRootDir/installedAssets/assetName/BASE. The destination directory for composition units based on Java EE applications is the legacy destination directory specified in the application configuration. The default legacy destination directory path is profileRootDir/installedApps/cellName/applicationArchiveName.

  • Shared library

    You can add an asset to a business-level application as a shared library, and you can configure non-shared-library composition units in the same business-level application to have a dependency relationship on the shared library composition unit. A shared library composition unit cannot depend on another shared library composition unit.

    A shared library is a Java archive imported as an asset. A shared library typically contains classes referenced by application business logic at run time. Some JARs are intended to be used only as shared libraries. Such JAR files are not processed by any content handler when the JAR is processed. The business-level application runtime defines a default deployable unit with the predefined name of DEFAULT. However, it is possible to deploy a JAR as a shared library even though the JAR's content is supported by some content handler.

    Generally, when you add a JAR file asset to a business-level application, you specify which deployable units you want to add to the application. When you specify a deployable unit name of DEFAULT, the resulting composition unit will be, by definition, a shared library composition unit. It does not matter whether the asset actually contains a deployable unit with the name DEFAULT.

    Java EE application configurations can contain shared library dependency declarations. A shared library dependency is expressed as a reference from a non-shared library composition unit to a shared library composition unit. The AdminTask command used to create a composition unit enables you to specify a dependency on an asset or on a shared library composition unit. If the dependency is expressed as a reference to a shared library asset, the system will automatically use an existing shared library composition unit for the asset, or create a composition unit for the shared library if one does not already exist.

    Dependency relationships can exist only between composition units in the same business-level application. A composition unit cannot depend on a composition unit in another business-level application.

    A shared library composition unit must start before any other composition units that depend on it. Set the starting weights (below) of dependent composition units to higher numeric values than the shared library composition unit. Failure to do this can cause class loading errors during run time.

    Dependency relationships on shared libraries are specified at the deployable unit level. However, it is possible to specify that a composition unit is dependent on a shared library. This has the same effect as specifying a dependency relationship for all deployable units in the composition unit.

    Whenever you specify a dependency relationship, you can choose whether or not to match targets. If you choose to match targets, all of the targets for the dependent composition unit are added to the shared library composition unit target list. The "match targets" option is not persistent. That is, the option selection is not stored in the configuration. It is only used when the relationship is initially configured. If you later change the targets for the dependent composition unit, you must change the shared library composition unit targets as required.

    When two Java EE applications in a business-level application have a dependency relationship on the same composition unit, they both use the same class loader to load classes from the shared library. This is often desirable. For example, both applications would "see" the same library static variable values. Also, references to shared library objects could, in principle, be passed from one application to the other. Another option is to configure two composition units for the same library and configure each Java EE application dependency relationship with a different composition unit. Configuring the applications in this way causes each application to load library classes with a separate class loader. This isolates the two applications so that one application's interaction with the library would not be visible to the other. In this configuration, the library binaries themselves are still shared.

    Figure 2 illustrates a configuration where three applications depend on the same shared library binary file: the shared library class loader used by Enterprise Application 1 is different from that used by Enterprise Applications 2 and 3. Enterprise Applications 2 and 3 both load shared library classes with the same shared library class loader.

    Figure 2. Shared library relationships
    Figure 2. Shared library relationships
  • Starting weight

    Starting weight is an attribute on composition units. The starting weight value controls composition unit start or stop sequence when a business-level application is started or stopped. During application server startup and shutdown, all composition units are sorted according to starting weight without regard to their parent business-level applications. The starting weight for a deployed Java EE application is identical to the composition unit to which it maps.


Deploying a Java EE application to a cell using business-level application constructs

This section illustrates how you can leverage business-level application capability with Java EE applications. This example describes how you would deploy two EAR files, ShoppingCart.ear and UserProfile.ear, as part of one business-level application. In this example:

  • Each EAR file depends on two shared libraries. The first shared library, CommonUtilities.jar, is deployed once, resulting in one composition unit. The second shared library, AppScopedUtilities.jar, is deployed twice, resulting in two composition units.
  • Each application is configured to depend on the single composition unit for CommonUtilities.jar and one of the two composition units for AppScopedUtilities.jar. In addition, both entire applications are dependent on CommonUtilities.jar, while only one module in each application is dependent on AppScopedUtilities.jar.
  • As explained earlier, both applications will load classes from CommonUtilities.jar using the same library class loader. Each application will use a separate library class loader to load classes from AppScopedUtilities.jar.
  • The two EAR files have a run time dependency so that ShoppingCart.ear must be started before UserProfile.ear. You must set the starting weight for the two applications so that ShoppingCart.ear starts before UserProfile.ear, and both of the shared libraries start before either application.

Configuration of the business-level application is shown using both the administrative console and the wsadmin scripting utility.

Console example

This section describes how you would deploy the sample application described above using the administrative console panels.

  1. Import assets

    The first thing you will do is to import the assets you need, including the two EAR files and two shared library JAR files described above. (For brevity, the figures show the console panels for only one of the assets; the others are imported in a similar manner.)

    The list of imported assets can be displayed by selecting Applications => Application Types => Assets in the navigation panel. The initial asset list will be empty, given that no assets have been imported yet. Importing an asset is fairly straightforward. The import asset panels that display in response to clicking the Import button on the asset list panel are described in detail below. (An example of the asset list panel with a list of imported assets is shown in Figure 7.)

    Figure 3 displays when you click on the Import button on the asset list panel. Here, you can select the asset file from your local filesystem or from the filesystem of the host to which the administrative console is connected. In this example, you are selecting from the local filesystem.

    Figure 3. Asset upload panel
    Figure 3. Asset upload panel

    After you have uploaded the asset, you will specify your asset import options (Figure 4):

    • Asset name. Specify a name other than the name of the file that was imported. If x.jar is imported and you change the name to y.jar, the file will be saved as y.jar in the configuration repository. In this example, the original name of the asset file is used.
    • Asset description. Asset configurations include a description of the asset. You can specify any description you want.
    • Asset binaries destination URL. By default, a deployed asset expands into the installedAssets directory, under the profile root directory. You can specify an asset binaries destination directory if you want to expand into some directory other than the default.
    • File permissions. When a deployed asset is expanded into the binaries destination directory, file permissions are set according to this configuration data value. The defaults are shown in Figure 4; you can modify according to your specific requirements. Typically, the content handler for the asset would set a default value appropriate for the asset type.
    • Asset relationships. It is possible for assets to be configured with dependencies on other assets. Typically, dependencies are declared by the content handler for the asset. You can change whatever relationships are declared by default. In this case, there are no dependencies declared at the asset level and none will be added.
    • Validate asset. Content handlers for assets can optionally respond to the Validate asset flag by analyzing the asset contents to ensure they are valid. The flag exists because validation can be quite time consuming, and you might opt to not run validation if the asset is already known to be valid. It is also possible that you might want to import an asset even though it is known to not be valid. In most cases, it doesn't really matter whether the asset is valid until it's deployed. You can update an invalid asset later and then deploy it when it is valid. No validation occurs during asset import of shared library assets or Java EE assets, so no validation is required in this example.
    Figure 4. Asset import options panel
    Figure 4. Asset import options panel

    The next panel (Figure 5) lets you review your selections, go back to edit your selections, or complete the import operation.

    Figure 5. Asset import summary panel
    Figure 5. Asset import summary panel

    After you click Finish, the status panel displays (Figure 6). The progress entries shown in the figure only appear because server tracing was enabled, but content handlers can display progress messages if desired. Once the operation is complete, you can save your changes to the configuration repository.

    Figure 6. Asset import status panel
    Figure 6. Asset import status panel

    As assets are imported, they will appear on the asset list panel (Figure 7).

    Figure 7. Asset list panel
    Figure 7. Asset list panel
  2. Create business-level application

    Once you have imported all of the assets that will comprise your business-level application, you will create the application itself. The panel shown in Figure 8 contains only name and description fields. As with other console panels, you have the option to save changes to the configuration repository when the operation is complete.

    Figure 8. New business-level application creation panel
    Figure 8. New business-level application creation panel
  3. Create composition units

    Next, you will add the assets to the business-level application you just created. Adding an asset to a business-level application creates a composition unit that becomes a member of the business-level application.

    Following are a series of panels for adding a shared library asset to a business-level application. (There are two shared libraries in this example, but only one, AppScopedUtilities.jar, is shown being added. The other shared library composition units are created in a similar manner.)

    To add assets to a business-level application, go to the business-level application list panel by selecting Applications => Application Types => Business-level applications in the navigation panel. Click the name of the business-level application to which you want to add an asset. In the example, you would click OnlineStore and then the Add button (Figure 9).

    As you can see in the figure, you have the option of adding both non-shared library assets and shared library assets. You need to choose because an asset that contains classes that are not strictly library classes can be added to a business-level application to serve as a shared library. Be aware that if you select Add Shared Library, the asset will not be configured to run as a server component, as it would if you selected Add Asset. In this example, the asset is strictly a shared library.

    Figure 9. Add shared library asset panel
    Figure 9. Add shared library asset panel

    Notice that Figure 9 shows a list of composition units that have been added to the subject business-level application. If you want to nest business-level applications, you can select the Add button to add another business-level application to the subject business-level application. Doing this will create a composition unit that essentially links the subject business-level application to the nested business-level application. In this example, you are not nesting business-level applications.

    In Figure 10, you are presented with a list of assets to choose from. Here, you select AppScopedUtilites.jar and click the Continue button.

    Figure 10. Shared library asset selection
    Figure 10. Shared library asset selection

    The next set of panels will vary depending on the type of asset you are adding. Because you are adding a shared library asset, only minimal configuration is required. The configuration options are:

    • Name. A composition unit name is generated for you, but you can change it to another name if you want.
    • Description. Composition unit configuration data includes a description.
    • Starting weight. The value of starting weight controls when the composition unit will be started relative to other composition units. There are two contexts: business-level application start and server process start. When a business-level application is started, its composition units are started according the starting weight value, in ascending order. During server process startup, all composition units are started according to their starting weight, regardless of which business-level application they belong to. The reverse is true for stopping business-level applications and stopping server processes.
    • Start composition unit upon distribution. By default, when the composition unit is saved to the configuration repository, it will not be started. Setting this flag causes it to be started as soon as the composition unit is saved to the repository. It is worth noting that even shared libraries are started. When a shared library is started, a class loader for it is created.
    • Restart behavior on update. By default, composition units for assets are restarted, if required, when either the asset is updated or the composition unit configuration data is changed. You can override that default behavior by selecting NONE, in which case no restart action takes place.
    Figure 11. Shared library composition unit options panel
    Figure 11. Shared library composition unit options panel

    A composition unit must have a target before it can be run. The panel shown in Figure 12 lets you specify the target (or targets) for the composition unit. In this example, a standalone profile is being used, so there is only one target to select.

    Figure 12. Composition unit target selection panel
    Figure 12. Composition unit target selection panel

    After you complete the composition unit configuration data entry, you will see the summary panel (Figure 13). From there you can go back and make changes or finish the operation.

    Figure 13. Add composition unit summary panel
    Figure 13. Add composition unit summary panel

    After you click Finish, you will see the progress panel shown in Figure 14. Those progress entries you see in the panel that start with a timestamp only appear because server tracing is enabled. Otherwise, they will not display. Content handlers can display progress messages if desired. Once the operation has completed successfully, you can save the changes to the configuration repository.

    Figure 14. Add composition unit status panel
    Figure 14. Add composition unit status panel

    For this example to be complete, you need to add AppScopedUtilities.jar to the OnlineStore business-level application again, and you need to add CommonUtilities.jar to the business-level application. The panels for these tasks are not shown because they are similar to those shown above.

    Next, you need to add the Java EE application assets to the business-level application, starting with UserProfile.ear. You will start the procedure in exactly the same way as you did to add the shared library asset, except this time you select Add Asset instead of Add Shared Library. You then select ShoppingCart.ear from the list of assets, as shown in Figure 15.

    Figure 15. Java EE asset selection
    Figure 15. Java EE asset selection

    You will notice that the next panels look quite different from those for a shared library asset. That is because the Java EE content handler must obtain a number of application configuration options from the user. If you are familiar with the Java EE application installation panels from previous versions of WebSphere Application Server, then these will look very familiar to you. As indicated in Figure 16, choose to show all installation options and parameters.

    Figure 16. Fast path / detailed selection panel
    Figure 16. Fast path / detailed selection panel

    Many of the panels deal with enterprise application options and parameters not related to business-level applications. Therefore, only those panels that contain business-level application-specific options are shown here.

    Figure 17 contains one business-level application related option. Notice the Business-level application name field near the bottom of the panel. You will notice that the field is not editable. This is because you have already selected the business-level application that you are adding the application to. If you install an application using the legacy installation panels, located by navigating to Applications => Application Types => WebSphere enterprise applications, you will see exactly the same set of panels. However, an application added through the legacy interface is not being added in the context of any particular business-level application. For that reason, the field is editable. If you specify a name, it will be added to that business-level application if it exists. If no business-level application with name name exists, one with that name is created. By default, the system creates a business-level application with the same name as the application, and the application is added to the business-level application. When you install an application through the legacy panels, no Java EE asset is imported. The only copy of the application binary in the configuration repository is located in the area used for deployed applications, which existed in previous versions of WebSphere Application Server and is still used in Version 7.0.

    Figure 17. Business-level application name option
    Figure 17. Business-level application name option

    The panel in Figure 18 is new for WebSphere Application Server V7.0. This panel enables you to specify shared library dependency relationships on shared library composition units in the same business-level application. In this example, you need to configure dependencies on the composition units for CommonUtilities.jar and AppScopedUtilities.jar, as described earlier. For each dependency you need to configure, select the application (or the specific modules with the dependency) and click on the Reference shared libraries button.

    Figure 18. Map shared library relationships panel
    Figure 18. Map shared library relationships panel

    Notice the Match target column in the table displayed in Figure 18. Checking this box adds the respective module or application targets to the shared libraries you select via the Reference shared libraries button. It is important to know that Match target is not a configuration attribute on the shared libraries you select. The option is used to add shared library targets when the relationship is initially declared. If you later change the target of a module, for example, the targets of any shared library composition units on which it depends are not similarly updated. You need to update the shared library targets yourself.

    Figure 19 displays when you click the Reference shared libraries button in Figure 18. Select the shared library composition units to add as a dependency.

    Figure 19. Shared library selection panel
    Figure 19. Shared library selection panel

    Figure 20 is what the Map shared library relationships panel looks like after you have configured an application-level dependency on the composition unit, CommonUtilities_0001.jar, which is the composition unit you created when you added CommonUtilites.jar to the business-level application. Per the application description earlier, you need to select User Shopping Cart and add a dependency on one of the composition units you created for AppScopedUtilities.jar. (Those panels are not shown here, but you specify the shared library dependency relationship in a similar manner.)

    Figure 20. Module to shared library mapping list panel
    Figure 20. Module to shared library mapping list panel

    To set the starting weight, go back to edit the composition unit. and select Startup behavior to display Figure 21. For ShoppingCart.ear, the starting weight is set to 2.

    Figure 21. Java EE startup order setting panel
    Figure 21. Java EE startup order setting panel

    All Java EE applications are listed in the enterprise applications list, which you can get to by navigating to Applications => Application Types => WebSphere enterprise applications, regardless of whether the application was deployed through that panel or by adding an imported Java EE asset to a business-level application. You can also set the starting weight of the application through this path. You will see the same set of panels and links from this path as when you edit the composition unit.

    To add UserProfile.ear to the business-level application, you will perform virtually the same steps you took to add ShoppingCart.ear to the business-level application. Two differences are:

    • You must choose the other composition unit for AppScopedUtilities.jar when configuring the shared library dependency relationship.
    • You need to set the starting weight to 3 so that it starts after ShoppingCart.ear.
  4. Start business-level application

    Now that your business-level application is created, you need to save it to the configuration repository, if you have not already done so. A business-level application cannot be started until is has been saved. Also, be sure that all changes have been distributed to the target nodes if the cell is a distributed cell. Similarly, starting a business-level application will only start the composition units that have also been saved.

    The business-level application list panel is shown in Figure 22. To start a business-level application, select the checkbox associated with the application and click the Start button. You are essentially starting a Web application, and so the process is the same; that the application is part of a business-level application does not change the external behavior of the application.

    Figure 22. Business-level application start panel
    Figure 22. Business-level application start panel

    For more information on business-level application console usage, see the WebSphere Application Server V7.0 Information Center.

Scripting example

Now, let's see how you would deploy the sample application using the wsadmin scripting utility.

All business-level application function is exposed as a set of AdminTask commands. In this example, all of the commands are executed in batch mode, where all of the required input is provided on the command invocation. You can run any command in interactive mode, which will prompt you for all options. Before command execution begins, the batch mode version of the command is displayed. This is a good way to learn the proper batch mode form of a command, because some of them can be fairly complex.

The steps you need to take are basically the same as those you performed through the console.

  1. Import assets

    Figure 23 shows the importing of ShoppingCart.ear. All the other files in this example are imported in the same way. You can only import files accessible from the local filesystem; you cannot import from the server's filesystem as you can through the console.

    Figure 23. importAsset scripting command
    Figure 23. importAsset scripting command
  2. Create business-level application

    After you import the assets, create the business-level application as shown in Figure 24.

    Figure 24. createbusiness-level application scripting command
    Figure 24. createbusiness-level application scripting command
  3. Create composition units

    Here, the scripting process differs from the console because you are leveraging capabilities that the console does not provide. When you declare a shared library dependency relationship, the script interface provides the option to specify a shared library asset instead of a shared library composition unit. If the shared library asset has already been added to the business-level application, its composition unit will be used for the dependency relationship. If a composition unit for the shared library does not already exist, one is created for you. You leverage that capability for CommonUtilities.jar. For that reason, you will not see steps where you explicitly add CommonUtilities.jar to the business-level application. You want each EAR to depend on a separate composition unit for AppScopedUtilities.jar, and so you create the composition units for it beforehand, as illustrated by the commands shown in Figures 25 through 28.

    Figure 25. Creating first composition unit from shared library asset
    Figure 25. Creating first composition unit from shared library asset
    Figure 26. Creating second composition unit from shared library asset
    Figure 26. Creating second composition unit from shared library asset
    Figure 27. addCompUnit scripting command for ShoppingCart.ear
    Figure 27. addCompUnit scripting command for ShoppingCart.ear
    Figure 28. addCompUnit scripting command for UserProfile.ear
    Figure 28. addCompUnit scripting command for UserProfile.ear

    As with the console, the starting weight cannot be set on Java EE assets when they are added to a business-level application. The starting weight must be set separately (Figures 29 and 30).

    Figure 29. Script command to set starting weight for ShoppingCart.ear
    Figure 29. Script command to set starting weight for ShoppingCart.ear
    Figure 30. Script command to set starting weight for UserProfile.ear
    Figure 30. Script command to set starting weight for UserProfile.ear
  4. Save to configuration repository

    As before, you must save the business-level application to the configuration repository before you can start it (Figure 31).

    Figure 31. Script command to save changes to configuration repository
    Figure 31. Script command to save changes to configuration repository
  5. Distribute configuration changes to target nodes

    If the cell is a distributed cell, you must distribute to all target nodes. Run the command shown in Figure 32 for each target node.

    Figure 32. Script command to distribute configuration changes to a target node
    Figure 32. Script command to distribute configuration changes to a target node
  6. Start business-level application

    With the configuration changes saved, you can start the business-level application (Figure 33).

    Figure 33. startbusiness-level application scripting command
    Figure 33. startbusiness-level application scripting command

For more information on business-level application scripting, see WebSphere Application Server V7.0 Information Center.


Legacy application management installation interfaces

All Java EE applications deployed to a cell must be a member of a business-level application. Interfaces available in WebSphere Application Server prior to V7.0 still function in V7.0 as before, except that a business-level application and composition unit for the application are created implicitly. However, the application is not implicitly imported as an asset. New options have been added that enable you to specify a business-level application name and to declare dependencies on shared library composition units so that you can leverage business-level application functions.

New install options added to the legacy installation interface include:

  • blaname: Name of the business-level application to which you want to add the application. If a business-level application by that name does not exist, one is created.
  • SharedLibRelationship: List of shared library asset IDs or shared library composition unit IDs. If an asset ID is specified, an existing shared library composition unit for the asset is used, if possible. Otherwise, a shared library composition unit is created. Separate each ID with a plus (+) character. The format for asset IDs is WebSphere:assetname=<asset name>. The format for composition unit IDs is WebSphere:cuname=<composition unit name>.

Here is an example that shows how you can use these new options: Assume that you have created a business-level application named "Mybusiness-level application" and added two shared libraries, SL1.jar and SL2.jar, to the business-level application, yielding composition units SL1_0001.jar and SL2_0001.jar. Suppose you want to install a Java EE application and add it to Mybusiness-level application. The Java EE application depends on the two shared libraries in the business-level application. All modules in the Java EE application depend on SL1_0001.jar. Therefore, you want to declare an application-wide dependency on SL1_0001.jar. In addition, the Web module, MyWebApplication.war, depends on SL2_0001.jar, and so you want to declare a dependency on SL2_0001.jar by MyWebApplication.war. The AdminApp command below shows the options you would need to include to specify the business-level application and shared library dependency relationships. For clarity, only the new options are shown.

AdminApp.install('MyApp.ear', '[ ... -blaname WebSphere:blaname=Mybusiness-level 
application -SharedLibRelationship [[ MyApp.ear META-INF/application.xml WebSphere:cuname
=SL1_0001.jar "" AppDeploymentOption.Yes ][ "My Web Application" MyWebApplication.war,
WEB-INF/web.xml WebSphere:cuname=SL2_0001.jar "" AppDeploymentOption.Yes ]]]' )

The value “AppDeploymentOption.Yes” is essentially a TRUE value for the match targets option. The empty string that occurs after the library specification is the name of the composition unit for the shared library. This value only applies when the library specification is a reference to an asset. The value specifies the composition unit name to use, should one need to be created. If an empty name is specified, a name will be constructed for you. When the library specification is a reference to a composition unit, this value is not used.


Summary

Business-level application functionality in WebSphere Application Server V7.0 provides improved management of Java EE applications and proxy filters. Extensibility of deployable content provided through business-level applications is exploited by the WebSphere Application Server V7.0 Feature Pack for Service Component Architecture (SCA) 1.0. SCA contributions are deployed to WebSphere cells using business-level application constructs. Hopefully, the information in this article will help you begin leveraging this new technology.


Acknowledgments

Thanks to Ajay Apte, Chuck Lucier, Annie Nguyen, and Lavena Chan for reviewing this article and providing helpful comments.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=390048
ArticleTitle=System administration for WebSphere Application Server V7: Part 5: Business-level applications
publish-date=05202009