Developing Adapters
|
 |
 |
|
|
 |
 |
This section describes some basic concepts with which you should become familiar before attempting to develop an adapter or design-time graphical user interface (GUI). Specifically, it provides information about the following subjects:
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.
The run-time framework is a set of tools you can use to develop event and service connections. To support event connection development, the run-time framework provides a basic, extensible event generator. For service connection development, the run-time framework provides a complete J2EE-compliant adapter.
The classes supplied by the run-time framework provide the following benefits:
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:
All three features comply with the J2EE Connector Architecture standard.
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:
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.
With the ADK you can create both event connections and service connections. 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.
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.
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 service request and response consists of:
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.
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.
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.
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.
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:
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:
You may use another format for this information, if you prefer, as long as you include the required data.
The adapter logical name is used with adapters in the following ways:
getAdapterLogicalName() in com.bea.adapter.web, as described in Adapter Logical Name Used as the Return Value for getAdapterLogicalName.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
Table 2-1 lists the types of functionality that use the adapter logical name as an organizing principle.
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.
The ADK uses Enterprise Archive files, or EAR 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
shared.jar (shared .jar between .war and .rar)
BEA_WLS_SAMPLE_ADK.war (Web application with
META-INF/MANIFEST.MF entry Class-Path: shared.jar
BEA_WLS_SAMPLE_ADK.rar (Resource Adapter
META-INF/MANIFEST.MF entry Class-Path: shared.jar
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.
|
|
|