Deploying WebLogic Integration Solutions

Administering Environment-Specific Application Integration Information

This section describes how to use the aiConfigurator utility to modify environment-specific information for application view, adapter, and connection factory descriptors.

Note: The aiConfigurator utility should only be run on a domain which has not been started. Do not use this utility on a running domain server. Using the utility on a running domain server can result in unpredictable behavior.

aiConfigurator Utility and Examples

Application views, by using environment variables, can have environment-specific information parameterized and isolated from business-oriented information. With this parameterization comes the need to modify the parameter values to reflect the needs of new environments. Adapter instances and connection factories can also include environment-specific information.

The aiConfigurator utility (based on Java class com.bea.wlai.management.util.Configurator) allows an administrator to modify environment-specific information across application view, adapter, and connection factory descriptors. This allows an administrator to preconfigure application integration resources to deploy correctly in a new target environment. Further tuning of these resources can then be performed using the WebLogic Integration Administration Console. The aiConfigurator utility is located in:

WL_HOME/integration/bin/aiConfigurator.cmd (or .sh)

This utility updates the WebLogic Integration configuration persistent store, and optionally publishes application view EJB contents, to reflect the needs of the new environment. At runtime, the newly tailored information is fetched from the persistent store and applied to the in-memory state of the application view, adapter instance, or connection factory.

Switching Database Type/Instance for DBMS Sample Adapter provides an example of the use of the aiConfigurator utility, and shows how to change database types/instances when using the DBMS sample adapter. For more information on the DBMS sample adapters, see Developing Adapters.

aiConfigurator Usage

The aiConfigurator utility is ordinarily used to override application view environment variables, and adapter or connection factory settings at runtime, leaving the original descriptors intact. This utility also allows for the default values of application view environment variables to be replaced with the values specified, and adapter instance or connection factory settings to be persisted into the original descriptors. The latter capability is useful for samples that the administrator expects users to edit later.

The usage of the aiConfigurator utility is as follows:

aiConfigurator -appName app_name -appFile app_file
-domainRootDir domain_root_dir [-updateDesignTime]

Plus one of the following groups of arguments:

[ -configAppView
  -appViewName app_view_name
  [ -dump |
    < -vars vars|properties_file
      -var name=value
      -eventAdapterName qualified_name
      -serviceAdapterName qualified_name
      -serviceFactoryName name
      -autoSuspendEnabled true|false
      -autoSuspendTimeout integer_seconds
      -suspendedRequestRetryInterval integer_seconds
      -suspendedEventRetryInterval integer_seconds
    >

    ]
  ]

[ -configAdapter
  -appViewName app_view_name
  -adapterName adapter_instance_name
  [ -dump |
    < -props props|properties_file
      -prop name=value
      -inboundMessagingTargets comma-separated_server_names
      -autoSuspendEnabled true|false
      -autoSuspendTimeout integer_seconds
    >
    ]
  ]

[ -configFactory
  -appViewName app_view_name
  -adapterName adapter_instance_name
  -factoryName connection_factory_name
  [ -dump |
    < -props props|properties_file
      -prop name=value
      -minPoolSize integer
      -maxPoolSize integer
    >
    ]
  ]

where:

appName is the name of the application to configure
appFile is the directory or EAR archive containing the application
domainRootDir is the root directory of the domain the application is to be deployed into
updateDesignTime is used to force the changed values back into the design-time artifacts and the WebLogic Integration persistent configuration store. If this argument is not used, all changes are saved adjacent to the unchanged design-time artifacts in the WebLogic Integration persistent configuration store. For application views, the only changes that are persisted back to the design-time descriptor are variable values. All other settings are persisted only to the WebLogic Integration persistent configuration store.
vars and props are in form name=value

For application views, you can update the following types of information:

Note: The only Application View information that can be updated for the design-time descriptor using the -updateDesignTime argument are the environment variables.

Environment variables—Supply name and value pairs with -var arguments or as a properties file given with a -vars argument.
Event adapter—Supply the event adapter name with the -eventAdapterName argument.

Note: Use this option with caution. The name you specify should be fully qualified and must represent an adapter instance you know will already be deployed in the integration server (for example, if another application view uses the adapter instance, and you have guaranteed the other application view will deploy before the current application view based on DeploymentOrder and other settings).

Service adapter—Supply the service adapter name with the -serviceAdapterName argument.

Service connection factory—Supply the connection factory name with the -serviceFactoryName argument.

Note: The name you give must be the name of a connection factory within the adapter instance used for services on this application view (-serviceAdapterName argument).

Enable or disable the auto-suspend feature—You can enable or disable the auto-suspend feature by setting the -autoSuspendEnabled argument to true or false.
Auto-suspend timeout—Supply the number of seconds for the auto-suspend timeout using the -autoSuspendTimeout argument.
Suspended-request retry interval—Supply the suspended-request retry interval (in seconds) with the -suspendedRequestRetryInterval argument.
Suspended-event retry interval—Supply the suspended-event retry interval (in seconds) with the -suspendedEventRetryInterval argument.

Note: Currently, the suspended event retry interval value is not used by the aiConfigurator utility, and the AppViewDeploymentMBean does not define a setSuspendedEventRetryInterval() method. The suspended request retry interval value is used for both asynchronous service request and event retry intervals.

For adapter instances you can update the following information:

Note: The only adapter instance information that can be updated for the design-time descriptor using the -updateDesignTime argument are the event generation properties.

Event generation properties—Supply name and value pairs or a properties file with a -props argument.
Inbound messaging target—Supply a comma-separated list of machines to which inbound messaging is targeted using the -inboundMessagingTargets argument.
Enable or disable the auto suspend feature—You can enable or disable the auto-suspend feature by setting the -autoSuspendEnabled argument to true or false.
Auto suspend timeout—Supply the number of seconds for the auto-suspend timeout using the -autoSuspendTimeout argument.

For connection factories you can update the following information:

Note: The only connection factory information that can be updated for the design-time descriptor using the -updateDesignTime argument are the service invocation properties.

Service invocation properties—Supply name and value pairs or a properties file with -prop arguments.
Pool size—Supply the minimum and maximum pool size for connections with the -minPoolSize and -maxPoolSize arguments.

You can determine the current settings for each application integration artifact type by passing the -dump argument after the -config* argument. This is useful if the environment-specific configuration occurs in steps, or changes over time.

Switching Database Type/Instance for DBMS Sample Adapter

As an example of how to use the aiConfigurator utility, this section discusses the WebLogic Integration sample application and how to configure the samples in this application to execute on an Oracle database as opposed to the PointBase database.

To configure the samples, run the aiConfigurator utility against each application integration artifact that needs to be reconfigured. The current sampleApp/ApplicationIntegration directory contains two application views (FunctionDemo.CustomerMgmt and InsertBasedEvents). These application views each use a single adapter instance, and a single connection factory within this adapter instance. The aiConfigurator utility is run against each of these artifacts in turn.

For each application view, update its variable set to reflect the new Oracle environment. For the DBMS sample adapter, this means setting the catalog and schema qualifiers for the tables that are used in events and services.

For the application integration samples, we've defined three variables:

myCatalog—The catalog containing the schema that contains the CUSTOMER_TABLE used for the insert and update events in CustomerMgmt and InsertBasedEvents, respectively.
mySchema—The schema containing the CUSTOMER_TABLE.
myTableQualifiers—A variable combining catalog and schema to form a prefix for table names in SQL queries.

For the adapter instances, the event generation properties need to be updated to reflect the correct catalog and schema for the event staging tables.

For the connection factories, the DB type, JDBC driver URL, and other properties specific to the original PointBase environment need to be updated. These properties are changed using the switchDB script for your platform. This script uses the -updateDesignTime argument of the aiConfigurator utility to force updates back into the design-time artifacts, thus allowing edits of these artifacts from within the Oracle design-time environment.

In summary, to switch databases used by the application integration samples and the samples domain, do the following:

Change the JDBCConnectionPool elements in the domain's config.xml file to point to the Oracle instance. This involves specifying the JDBC driver class name and JDBC URL, and setting the pool properties user/password for the new database instance. See your WebLogic Server documentation for details.

Run the switchDb script specific to your operating system within the WL_HOME/samples/integration/sampleApp/ApplicationIntegration directory. This updates the application view, adapter, and connection factory descriptors contained in the sampleApp to reflect the new database type/instance. Note that usage for the switchDb utility is:

Usage: switchDb (db_type) (db_server) (db_name) (db_user) (db_password)