Basic Development Concepts

This section describes some basic concepts with which you should become familiar before attempting to develop an adapter or design-time GUI. Specifically, it provides information about the following subjects:

• Run Time Versus Design Time

• Events and Services

• How Adapters Use Logging

• Adapter Logical Name

• Shared Connection Factories

• Enterprise Archive (EAR) Files

• How Adapters Handle Concurrent Requests

 

---

Run Time Versus Design Time

The term adapter activity encompasses both run-time and design-time activity. Run-time activity is the execution of an adapter's processes. Design-time activity, performed by an adapter user, includes the creation, deployment, and testing of an application view.

Run-time and design-time activity are supported by ADK run-time and design-time frameworks, respectively. The run-time framework comprises tools for developing adapters, while the design-time framework includes tools for designing Web-based user interfaces. Both types of activity are discussed in greater detail in the following sections.

Run-Time Framework

The run-time framework is a set of tools you can use to develop event and service adapters. To support event adapter development, the run-time framework provides a basic, extensible event generator. For service adapter development, the run-time framework provides a complete J2EE-compliant adapter.

The classes supplied by the run-time framework provide the following benefits:

• They allow you to focus on EIS details rather than J2EE details.

• They minimize the effort needed to use the ADK logging framework.

• They simplify the J2EE Connector Architecture.

• They minimize redundant code used in multiple adapters.

In addition, the run-time framework provides abstract base classes to help you implement an event generator that can leverage the event support provided by the ADK environment.

A key component of the run-time framework is the run-time engine, which hosts the adapter component responsible for handling service invocations and manages the following WebLogic Server features:

• Physical connections to the EIS

• Login authentication

• Transaction management

All three features comply with the J2EE Connector Architecture standard.

Design-Time Framework

The design-time framework provides tools for building the Web-based GUI that adapter users need to define, deploy, and test their application views. Although each adapter has EIS-specific functionality, all adapters require a GUI for deploying application views. This framework provides two tools that minimize the effort required to create and deploy such a GUI:

• A Web application component that allows you to build an HTML-based GUI by using JSPs. This component is augmented by tools such as the JSP templates, the tag library, and the JavaScript library.

• A deployment helper component that provides a simple API for deploying, undeploying, and editing application views on WebLogic Server.

The design-time interface for each adapter is a J2EE Web application that is bundled as a WAR file. A Web application is a bundle of .jsp files, .html files, image files, and so on. The Web application descriptor is web.xml. The descriptor provides the J2EE Web container with instructions for deploying and initializing the Web application.

Every Web application has a context that is specified during deployment. The context identifies resources associated with the Web application under the Web container's document root.

 

---

Events and Services

With the ADK you can create both event adapters and service adapters. Within the ADK architecture, services and events are defined as self-describing objects (for which a name indicates a business function) that use XML schema to define input and output.

What Are Events?

An event is an XML document published by an application view when an occurrence of interest takes place within an EIS. Clients that want to be notified of events request such notification by registering with an application view. The application view then acts as a broker between the target application and the client. When a client has subscribed to events published by an application view, the application view notifies the client whenever an event of interest occurs in the target application. When an event subscriber is notified that an event of interest has occurred, it is passed an XML document that describes the event. Application views that publish events can also provide clients with the XML schema for publishable events.

Note: An application view represents a business-level interface to a specific function in an application. For more information about this feature, see Introducing Application Integration.

What Are Services?

A service is a business operation in an application that is exposed by an application view. It serves as a request/response mechanism: when an application receives a request to invoke a business service, the application view invokes the service in the target application and then returns (or, responds with) an XML document that describes the results.

To define a service, you must define input requirements, output expectations, and an interaction specification.

A request is submitted in two parts:

• An interaction specification, containing static secondary metadata about the request.

• Basic input, which identifies values for any variables. For example, in a DBMS transaction, the SQL statement is provided in the interaction specification, and the value of the variable is provided in the input requirement The result of the transaction is considered the output expectation.

 

---

How Adapters Use Logging

Logging is an essential feature of an adapter. Most adapters are used to integrate different applications and do not interact with end-users while processing data. Unlike a front-end component, when an adapter encounters an error or warning condition, it cannot stop processing and wait for an end-user to respond.

Moreover, many business applications connected by adapters are mission-critical. For example, an adapter might be required to keep an audit report of every transaction with an EIS. Consequently, adapter components should provide both accurate logging and auditing information. The ADK's logging framework is designed to accommodate both logging and auditing.

Logging Toolkit

The ADK provides a toolkit that allows you to log localized messages to multiple output destinations. The logging toolkit leverages the work of the Apache Log4j open source project.

The logging toolkit wraps the critical classes in Log4j to provide added functionality when you are building J2EE-compliant adapters. The toolkit is provided in the logtoolkit.jar file.

For information about using the logging toolkit, see Using the Logging Toolkit.

Logging Framework

With the ADK, logging of adapter activity is accomplished by implementing the logging framework. This framework gives you the ability to log internationalized and localized messages to multiple output destinations. It provides a range of configuration parameters you can use to tailor message category, priority, format, and destination.

The logging framework uses a categorical hierarchy to allow inheritance of logging configuration by all packages and classes within an adapter. The framework allows parameters to be modified easily during run time.

Internationalization and Localization

The logging framework allows you to internationalize log messages. Internationalized applications are easy to tailor to the idioms and languages of end-users around the world without rewriting the code. Localization is the process of adapting software for a specific region or language by adding locale-specific components and text. The logging framework uses the internationalization and localization facilities provided by the Java platform.

 

---

Adapter Logical Name

Every adapter must have an adapter logical name: a unique identifier that represents an individual adapter and serves as the organizing principle for all adapters. An adapter logical name is the means by which both an individual adapter and the following related items are identified:

• Message bundle

• Logging configuration

• Log categories

An adapter logical name is formed by combining the vendor name, the type of EIS connected to the adapter, and the version number of the EIS. By convention, this information is expressed as vendor_EIS-type_EIS-version. For example, in the adapter logical name BEA_WLS_SAMPLE_ADK:

• BEA_WLS is the vendor and product

• SAMPLE is the EIS type

• ADK is the EIS version

You may use another format for this information, if you prefer, as long as you include the required data.

Where the Adapter Logical Name Is Used

The adapter logical name is used with adapters in the following ways:

• It is used during adapter deployment as part of the WAR, RAR, JAR, and EAR filenames.

• It is used as an organizing principle, as described in Adapter Logical Name Used as an Organizing Principle.

• It is used as a return value to the abstract method getAdapterLogicalName() in com.bea.adapter.web, as described in Adapter Logical Name Used as the Return Value for getAdapterLogicalName().

Use of Adapter Logical Name in Adapter Deployment

To assign an adapter logical name, specify it as the value of the Name attribute of the <Application> element that contains the <ConnectiorComponent> element. This value is the key used by WebLogic Integration to associate an application view with a deployed resource adapter, as shown for a sample adapter in Listing  2-1.

Listing 2-1 Name Attribute of the ConnectorComponent Element

<Application Deployed="true" Name="BEA_WLS_DBMS_ADK"
 Path="<WLI_HOME>/adapters/dbms/lib/BEA_WLS_DBMS_ADK.ear"
 TwoPhase="true">
  <ConnectorComponent Name="BEA_WLS_DBMS_ADK" Targets="myserver"
 URI="BEA_WLS_DBMS_ADK.rar"/>
  <WebAppComponent Name="DbmsEventRouter" Targets="myserver"
 URI="BEA_WLS_DBMS_ADK_EventRouter.war"/>
  <WebAppComponent Name="BEA_WLS_DBMS_ADK_Web" Targets="myserver"
 URI="BEA_WLS_DBMS_ADK_Web.war"/>
</Application>

Note: The use of the adapter logical name as the name of the RAR file is an optional convention; such naming is not required in the URI attribute.

When an application view is deployed, it is associated with a J2EE Connector Architecture CCI connection factory deployment. For example, if a user deploys the abc.xyz application view, WebLogic Integration deploys a new ConnectionFactory and binds it to the following JNDI location:

 com.bea.wlai.connectionFactories.abc.xyz.connectionFactoryInstance

To enhance efficiency, the new connection factory deployment uses the <ra-link-ref> setting in the weblogic-ra.xml deployment descriptor.

Optionally, during application view design, the user can associate an existing, sharable connection factory deployment with an application view. The connection factory must be one that was created using the WebLogic Server Administration Console. For more information, see Shared Connection Factories.

The <ra-link-ref> element allows multiple deployed connection factories to be logically associated with a single deployed adapter to be associated, logically. The specification of the optional <ra-link-ref> element with a value identifying a separately deployed connection factory results in this newly deployed connection factory sharing the adapter which had been deployed with the referenced connection factory. In addition, any values defined in the referenced connection factory's deployment are inherited by this newly deployed connection factory unless otherwise specified. The adapter logical name is used as the value for the <ra-link-ref> element.

Adapter Logical Name Used as an Organizing Principle

Table  2-1 lists the types of functionality that use the adapter logical name as an organizing principle.

Table 2-1 How an Adapter Logical Name Is Used as an Organizing Principle  

In this area of functionality . . .	Adapter logical names are used as follows . . .
Logging	The adapter logical name is used as the base log category name for all log messages that are unique to the adapter. Consequently, the adapter logical name is passed as the value for the RootLogContext parameters in the following XML documents: WLI_HOME/adapters/ADAPTER/src/eventrouter/WEB-INF/web.xml WLI_HOME/adapters/ADAPTER/src/rar/META-INF/ra.xml WLI_HOME/adapters/ADAPTER/src/rar/META-INF/weblogic-ra.xml WLI_HOME/adapters/ADAPTER/src/war/WEB-INF/web.xml In these pathnames, ADAPTER represents the name of your adapter. For example: WLI_HOME/adapters/dbms/src/war/WEB-INF/web.xml In addition, the adapter logical name is used as the base for the name of the Log4J configuration file for the adapter; the name is completed by the addition of the .xml suffix. .xml is appended to the name. For example, the Log4J configuration file for the sample adapter is BEA_WLS_SAMPLE_ADK.xml.
Localization	The logical name of the adapter is used as the base name for message bundles for the adapter. For example, the default message bundle for the sample adapter is BEA_WLS_SAMPLE_ADK.properties. Consequently, the adapter logical name is passed as the value for the MessageBundleBase parameters in the following XML documents: WLI_HOME/adapters/ADAPTER/src/eventrouter/WEB-INF/web.xml WLI_HOME/adapters/ADAPTER/src/rar/META-INF/ra.xml WLI_HOME/adapters/ADAPTER/src/rar/META-INF/weblogic-ra.xml WLI_HOME/adapters/ADAPTER/src/war/WEB-INF/web.xml In these pathnames, the value of ADAPTER is the name of your adapter. For example: WLI_HOME/adapters/dbms/src/war/WEB-INF/web.xml

 

Adapter Logical Name Used as the Return Value for getAdapterLogicalName()

Lastly, the adapter logical name is used as the return value to the abstract method getAdapterLogicalName() on the com.bea.adapter.web. AbstractDesignTimeRequestHandler. This return value is used during the deployment of application views as the value of the RootLogContext for a connection factory.

 

---

Shared Connection Factories

You can associate an existing, sharable connection factory deployment with an application view. The connection factory must be one that was created using the WebLogic Server Administration Console. Sharable connection factories and their JNDI locations are identified using ConnectorComponentMbeans. The JNDI location is written into the application view property connectionFactoryJNDIName. The application view deployer uses this property during deployment.

Referencing Connection Factories at Startup

All sharable connection factories are referenced during the startup process. The user must ensure that the connection factories deployed using the WebLogic Administration Console are available for the deployment process. If a connection factory is not found, the deployment of the application view fails.

 

---

Enterprise Archive (EAR) Files

The ADK uses Enterprise Archive files, orEAR files, for deploying adapters. A single .ear file contains the WAR and RAR files necessary to deploy an adapter. An example of an EAR file is shown in Listing  2-2.

Listing 2-2 EAR File Structure

adapter.ear
     META-INF
          application.xml
     sharedJar.jar
     adapter.jar
     adapter.rar
          META-INF
               ra.xml
               weblogic-ra.xml
               MANIFEST.MF
     designtime.war
          WEB-INF
               web.xml
          META-INF
               MANIFEST.MF

The EAR file for the sample adapter is shown in Listing  2-3.

Listing 2-3 Sample Adapter EAR File

sample.ear
    META-INF
        application.xml
    adk.jar (shared .jar between .war and .rar)
    bea.jar (shared .jar between .war and .rar)

        BEA_WLS_SAMPLE_ADK.jar (shared .jar between .war and .rar)

        BEA_WLS_SAMPLE_ADK.war (Web application with
           META-INF/MANIFEST.MF entry Class-Path: 
           BEA_WLS_SAMPLE_ADK.jar adk.jar bea.jar log4j.jar 
            logtoolkit.jar xcci.jar xmltoolkit.jar)

        BEA_WLS_SAMPLE_ADK.rar (Resource Adapter 
           with META-INF/MANIFEST.MF entry Class-Path: 
           BEA_WLS_SAMPLE_ADK.jar adk.jar bea.jar log4j.jar 
            logtoolkit.jar xcci.jar xmltoolkit.jar)

	log4j.jar (shared .jar between .war and .rar)
       logtoolkit.jar (shared .jar between .war and .rar)
       xcci.jar (shared .jar between .war and .rar)
       xmltoolkit.jar (shared .jar between .war and .rar)

Notice that neither the RAR nor WAR files include any shared JAR files; rather, both refer to the shared JAR files located in the root directory of the EAR file.

For more information about using EAR files to deploy adapters, see Deploying Adapters.

 

---

How Adapters Handle Concurrent Requests

As an adapter designer, you must understand how WebLogic Integration handles multiple concurrent requests for an adapter in terms of connections and threads.

An application view uses a Stateless Session EJB to talk to the adapter. All execution within an adapter is carried out within the scope of a WebLogic Server execute thread. Thus, the number of concurrent requests is limited by the following factors:

• The number of WebLogic Server execute threads

• The number of connections in the pool associated with the connection factory for the RAR deployment of the connector.

Adapters, as specified in the J2EE Connector Specification, Version 1.0 from Sun Microsystems, Inc., do not create their own threads. If either WebLogic Server execute threads or the connections in the pool are exhausted, throughput decreases. Exceeding the available resources has the following affects:

• Running out of WebLogic Server execute threads forces new calls to ApplicationView.invokeService() to block until a free execute thread is obtained. You can control the number of execute threads for a server using the WebLogic Server Administration Console.

• Running out of connections in the connection pool causes an ApplicationView.invokeService() to sleep for a short time, then try again to get a connection. The application view retries a maximum of 60 times at an interval of 1 second. This retry logic eliminates the vast majority of pool empty exceptions a client would otherwise need to handle. This is because in most cases, the pool empty condition is short-lived, and eventually a connection becomes available. In cases where connections are held for an inordinate amount of time (EIS hang or overload), the pool empty conditions are passed back to the client.