This section contains information on the following subjects:
The role of an adapter is to convert data coming from some stream, such as a market data feed, into WebLogic Event Server events. These events are then passed to other components in the application, such as processors. An adapter is usually the entry point to a WebLogic Event Server application.
The FX example description shows three adapters that read in data from currency data feeds and then pass the data, in the form of a specific event type, to the processors, which are the next components in the network.
You can create adapters of different types, depending on the format of incoming data and the technology you use in the adapter code to do the conversion. The most typical types of adapters are those that:
Adapters are Java classes that implement specific WebLogic Event Server interfaces. You must also program adapter factories that create instances of the adapters. Finally, you must register both the adapter classes, and the adapter factories, in the EPN assembly file that describes your entire application.
You can optionally change the default configuration of the adapter, or even extend the configuration and add new configuration elements and attributes. There are two ways to pass configuration data to the adapter; the method you chose depends on whether you want to dynamically change the configuration after deployment. If you are not going to change the configuration data after the adapter is deployed, then you can configure the adapter in the EPN assembly file. If, however, you do want to be able to dynamically change the configuration elements, then you should put this configuration in the adapter-specific configuration files. Both methods are discussed below.
The following procedure describes the typical steps for creating an adapter:
See Programming the Adapter Class: Guidelines.
See Programming the Adapter Factory Class.
See Updating the EPN Assembly File
In the preceding procedure, it is assumed that the adapter is bundled in the same application JAR file that contains the other components of the event network, such as the processor, streams, and business logic POJO. If you want to bundle the adapter in its own JAR file so that it can be shared among many applications, see Creating an Adapter in Its Own Bundle.
The adapter class reads the stream of incoming data, such as from a market data feed, converts it into a WebLogic Event Server event type that is understood by the rest of the application, and sends the event to the next component in the network.
The following example shows the adapter class of the HelloWorld sample; see the explanation after the example for coding guidelines that correspond to the Java code in bold.
Note: | If you are creating an adapter that listens to JMS-type data, see Additional Programming Guidelines for JMS Adapters for additional guidelines. |
package com.bea.wlevs.adapter.example.helloworld;
import java.text.DateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import com.bea.wlevs.configuration.Activate;
import com.bea.wlevs.configuration.Prepare;
import com.bea.wlevs.configuration.Rollback;
import com.bea.wlevs.ede.api.Adapter;
import com.bea.wlevs.ede.api.EventSender;
import com.bea.wlevs.ede.api.EventSource;
import com.bea.wlevs.ede.api.SuspendableBean;
import com.bea.wlevs.event.example.helloworld.HelloWorldEvent;
import com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig;
public class HelloWorldAdapter implements Runnable, Adapter, EventSource, SuspendableBean {
private static final int SLEEP_MILLIS = 300;
private DateFormat dateFormat;
private String message;
private EventSender eventSender;
private boolean stopped;
public HelloWorldAdapter() {
super();
dateFormat = DateFormat.getTimeInstance();
}
public void run() {
stopped = false;
while (!isStopped()) { // Generate messages forever...generateHelloMessage();
try {
synchronized (this) {
wait(SLEEP_MILLIS);
}
} catch (InterruptedException e) {
e.printStackTrace();
}
}
}
public void setMessage(String message) {
this.message = message;
}
private void generateHelloMessage() {
List eventCollection = new ArrayList();
String message = this.message + dateFormat.format(new Date());HelloWorldEvent event = new HelloWorldEvent();
}
event.setMessage(message);
eventCollection.add(event);
eventSender.sendEvent(eventCollection, null);
@Prepare
public void checkConfiguration(HelloWorldAdapterConfig adapterConfig) {
if (adapterConfig.getMessage() == null
|| adapterConfig.getMessage().length() == 0) {
throw new RuntimeException("invalid message: " + message);
}
}
@Activate
public void activateAdapter(HelloWorldAdapterConfig adapterConfig) {
this.message = adapterConfig.getMessage();
}
@Rollback
public void rejectConfigurationChange(HelloWorldAdapterConfig adapterConfig) {
}
public void setEventSender(EventSender sender) {
eventSender = sender;
}
public synchronized void suspend() throws Exception {
stopped = true;
}
private synchronized boolean isStopped() {
return stopped;
}
}
Follow these guidelines when programming the adapter Java class; code snippets of the guidelines are shown in bold in the preceding example:
import com.bea.wlevs.ede.api.Adapter;
import com.bea.wlevs.ede.api.EventSender;
import com.bea.wlevs.ede.api.EventSource;
import com.bea.wlevs.ede.api.SuspendableBean;
Your adapter is required to implement the Adapter
and EventSource
interfaces; typically, your adapter will also implement the java.lang.Runnable
and SuspendableBean
interfaces to control the starting and stopping of the adapter. The EventSender
interface sends event types to the next component in your application network. For full details of these APIs, see the
Javadoc.
import com.bea.wlevs.event.example.helloworld.HelloWorldEvent
import com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig;
The com.bea.wlevs.event.example.helloworld.HelloWorldEvent
class is a JavaBean that represents the event type used in the application.
The com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig
class represents an intance of the runtime adapter configuration. For details, see Programming Access to the Configuration of an Adapter.
import com.bea.wlevs.configuration.Activate;
import com.bea.wlevs.configuration.Prepare;
import com.bea.wlevs.configuration.Rollback;
See Programming Access to the Configuration of an Adapter for details.
Adapter
and EventSource
interfaces. Typically, your adapter will also implement the SuspendableBean
and java.lang.Runnable
interfaces:public class HelloWorldAdapter implements Runnable, Adapter, EventSource, SuspendableBean {
The Adapter
interface specifies that your Java class is an adapter. The EventSource
interface provides the EventSender
that you use to send events.
The Runnable
and SuspendableBean
interfaces enable WebLogic Event Server to manage the running of the adapter code. An adapter that implements Runnable
should always also implement SuspendableBean
. In the SuspendableBean.suspend()
method, you should put whatever code is needed to stop the running of your adapter. For example, you may set a flag that is checked by the main loop of the Runnable.run()
method which will cause the loop to be exited. You must implement SuspendableBean
in order for your application to be properly stopped when it is undeployed.
java.lang.Runnable
interface, your adapter must then implement the run()
method: public void run() {
...
This is where you should put the code that reads the incoming data, such as from a market feed, and convert it into a WebLogic Event Server event type, and then send the event to the next component in the network. Refer to the documentation of your data feed provider for details on how to read the incoming data. See Accessing Third-Party JAR Files From Your Application for information about ensuring you can access the vendor APIs if they are packaged in a third-party JAR file.
In the HelloWorld example, the adapter itself generates the incoming data using the generateHelloMessage()
private method. This is just for illustrative purposes and is not a real-world scenario. The generateHelloMessage() method also includes the other typical event type programming tasks:
HelloWorldEvent event = new HelloWorldEvent();
event.setMessage(message);
eventCollection.add(event);
eventSender.sendEvent(eventCollection, null);
The HelloWorldEvent
is the event type used by the HelloWorld example; the event type is implemented with a JavaBean and is registered in the EPN assembly file using the <wlevs:event-type-repository>
tag. See Creating the Event Types for details. The setMessage()
method sets the properties of the event; in typical adapter implementations this is how you convert a particular property of the incoming data into an event type property. Finally, the EventSender.sendEvent()
method sends this new event to the next component in the network.
@Prepare
, @Activate
, and @Rollback
annotations specify the methods that WebLogic Event Server invokes when the server prepares, activates, or rolls back the adapter's configuration. For details, see Programming Access to the Configuration of an Adapter.EventSource
, you must implement the setEventSender()
method, which passes in the EventSender
that you use to send events:
public void setEventSender(EventSender sender) { ...
SuspendableBean
, you must implement the suspend()
method that stops the adapter when, for example, the application is undeployed:public synchronized void suspend() throws Exception { ...
Your adapter factory class must implement the com.bea.wlevs.ede.api.AdapterFactory
interface, which has a single method, create()
, in which you code the creation of your specific adapter class.
The following is the adapter factory class for the HelloWorld example:
package com.bea.adapter.wlevs.example.helloworld;
import com.bea.wlevs.ede.api.Adapter;
import com.bea.wlevs.ede.api.AdapterFactory;
public class HelloWorldAdapterFactory implements AdapterFactory {
public HelloWorldAdapterFactory() {
}
public synchronized Adapter create() throws IllegalArgumentException {
return new HelloWorldAdapter();
}
}
For full details of these APIs, see the Javadoc
The adapters and adapter factory must be registered in the EPN assembly file, as discussed in the following sections. If you are using JMS, additional configuration is also required.
For a complete description of the configuration file, including registration of other components of your application, see Creating the EPN Assembly File.
Note: | If you are creating an adapter that listens to JMS-type data, see Additional Configuration for JMS Adapters for additional configuration. |
The adapter factory must be registered as an OSGI service in the EPN assembly file. The scope of the OSGI service registry is the entire WebLogic Event Server. This means that if more than one application deployed to a given server is going to use the same adapter factory, be sure to register the adapter factory only once as an OSGI service.
Add an entry to register the service as an implementation of the com.bea.wlevs.ede.api.AdapterFactory
interface. Provide a property, with the key
attribute equal to type
, and the name by which this adapter provider will be referenced. Finally, add a nested standard Spring <bean>
tag to register the your specific adapter class in the Spring application context
For example, the following segment of the EPN assembly file registers the HelloWorldAdapterFactory
as the provider for type hellomsgs
:
<osgi:service interface="com.bea.wlevs.ede.api.AdapterFactory">
<osgi:service-properties>
<prop key="type">hellomsgs</prop>
</osgi:service-properties>
<bean class="com.bea.adapter.wlevs.example.helloworld.HelloWorldAdapterFactory" />
</osgi:service>
In the EPN assembly file, you use the wlevs:adapter
tag to declare an adapter as a component in the event processor network. You can declare one or more adapters in your network. Use the provider
attribute to point to the name you specified as the type
in your osgi:service
entry; for example:
<wlevs:adapter id="helloworldAdapter" provider="hellomsgs"/>
This means that an adapter will be instantiated by the factory registered for the type hellomsgs
.
You can also use a <wlevs:instance-property>
child tag of <wlevs:adapter>
to set any static properties in the adapter bean. Static properties are those that you will not dynamically change after the adapter is deployed.
For example, if your adapter class has a setPort()
method, you can pass it the port number as shown:
<wlevs:adapter id="myAdapter" provider="myProvider">
<wlevs:instance-property name="port" value="9001" />
</wlevs:adapter>
Each adapter in your application has a default configuration. In particular:
The default adapter configuration is typically adequate for most applications. However, if you want to change this configuration, you must create an XML file that is deployed as part of the WebLogic Event Server application bundle. You can later update this configuration at runtime using the wlevs.Admin utility or manipulating the appropriate JMX Mbeans directly.
If your application has more than one adapter, you can create separate XML files for each adapter, or create a single XML file that contains the configuration for all adapters, or even all components of your application (adapters, processors, and streams). Choose the method that best suits your development environment.
The following procedure describes the main steps to create the adapter configuration file. For simplicity, it is assumed in the procedure that you are going to configure all components of an application in a single XML file
See XSD Schema Reference for Component Configuration Files for the complete XSD Schema that describes the adapter configuration file.
.xml
extension.
The root element of the configuration file is <config>
, with namespace definitions shown in the next step.
<adapter>
child element of <config>
. Uniquely identify each adapter with the <name>
child element. This name must be the same as the value of the id
attribute in the <wlevs:adapter>
tag of the EPN assembly file that defines the event processing network of your application. This is how WebLogic Event Server knows to which particular adapter component in the EPN assembly file this adapter configuration applies. See Creating the EPN Assembly File for details.For example, if your application has two adapters, the configuration file might initially look like:
<?xml version="1.0" encoding="UTF-8"?>
<helloworld:config
xmlns:helloworld="http://www.bea.com/xml/ns/wlevs/example/helloworld">
<processor>
...
</processor>
<adapter>
<name>firstAdapter</name>
...
</adapter>
<adapter>
<name>secondAdapter</name>
...
</adapter>
</helloworld:config>
In the example, the configuration file includes two adapters called firstAdapter
and secondAdapter
. This means that the EPN assembly file must include at least two adapter registrations with the same identifiers:
<wlevs:adapterid="firstAdapter" ...
>
...
</wlevs:adapter>
<wlevs:adapterid="secondAdapter"
...>
...
</wlevs:adapter>
WARNING: | Identifiers and names in XML files are case sensitive, so be sure you specify the same case when referencing the component's identifier in the EPN assembly file. |
monitoring
Boolean attribute of the <adapter>
element to enable or disable monitoring of the adapter; by default monitoring is enabled. When monitoring is enabled, the adapter gathers runtime statistics and forwards this information to an Mbean:<adaptermonitoring="true"
>
<name>firstAdapter</name>
</adapter>
To truly enable monitoring, you must have also enabled the manageability of the component, otherwise setting the monitoring
attribute to true
has no effect. You enable manageability by setting the manageable
attribute of the corresponding adapter component registration in the EPN assembly file to true
, as shown in bold in the following example:
<wlevs:adapter id="firstAdapter" provider="hellomsgs" manageable="true"
>
The following sample XML file shows how to configure two adapters, firstAdapter
and secondAdapter
.
<?xml version="1.0" encoding="UTF-8"?>
<sample:config
xmlns:sample="http://www.bea.com/xml/ns/wlevs/example/sample">
<adapter>
<name>firstAdapter</name>
</adapter>
<adapter monitoring="true">
<name>secondAdapter</name>
</adapter>
</sample:config>
In the procedure described in Creating Adapters: Typical Steps, it is assumed that the adapter and adapter factory are bundled in the same application JAR file that contains the other components of the event network, such as the processor, streams, and business logic POJO.
However, you might sometimes want to bundle the adapter in its own JAR file and then reference the adapter in other application bundles. This is useful if, for example, two different applications read data coming from the same data feed provider and both applications use the same event types. In this case, it makes sense to share a single adapter and event type implementations rather than duplicate the implementation in two different applications.
There is no real difference in how you configure an adapter and an application that uses it in separate bundles; the difference lies in where you put the configuration, as described in the following guidelines:
GlobalAdapter
. GlobalAdapter
bundle:<wlevs:adapter>
tag. You will use this tag in the EPN assembly file of the application bundle that actually uses the adapter.GlobalAdapter
bundle, export the JavaBean class in the MANIFEST.MF
file of the GlobalAdapter
bundle. Use the Export-Package
header, as described in Creating the MANIFEST.MF File.GlobalAdapter
bundle in the usual way, as described in Assembling and Deploying WebLogic Event Server Applications.provider
attribute to specify the OSGI-registered adapter factory, although in this case the OSGI registration happens in a different EPN assembly file (of the GlobalAdapter
bundle) from the EPN assembly file that actually uses the adapter.GlobalAdapter
bundle, you must explicitly import it into the application that is going to use it. You do this by adding the package to the Import-Package
header of the MANIFEST.MF file of the application bundle, as described in Creating the MANIFEST.MF File.
Adapters have default configuration data, as described in Configuring the Adapter and XSD Schema Reference for Component Configuration Files. This default configuration is typically adequate for simple and basic applications.
However, you can also extend this configuration by using XSD Schema to specifying a new XML format of an adapter configuration file that extends the built-in XML type provided by WebLogic Event Server. By extending the XSD Schema, you can add as many new elements to the adapter configuration as you want, with few restrictions other than each new element must have a name
attribute. This feature is based on standard technologies, such as XSD Schema and
Java Architecture for XML Binding (JAXB).
The following procedure describes how to extend the adapter configuration:
See Creating the XSD Schema File for details.
com.sun.tools.xjc.XJCTask
Ant task from Sun's GlassFish reference implementation. This Ant task is included in the WebLogic Event Server distribution for your convenience.
For example, the HelloWorld sample build.xml
file includes the following (only relevant sections shown):
<property name="base.dir" value="." />
<property name="output.dir" value="output" />
<property name="sharedlib.dir" value="${base.dir}/../../../../../modules" />
<property name="wlrtlib.dir" value="${base.dir}/../../../../modules"/>
<path id="classpath">
<pathelement location="${output.dir}" />
<fileset dir="${sharedlib.dir}">
<include name="*.jar" />
</fileset>
<fileset dir="${wlrtlib.dir}">
<include name="*.jar"/>
</fileset>
</path>
<taskdef name="xjc" classname="com.sun.tools.xjc.XJCTask">
<classpath refid="classpath" />
</taskdef>
<target name="generate" depends="clean, init">
<copy file="../../../../xsd/wlevs_base_config.xsd"
todir="src/main/resources/extension" />
<copy file="../../../../xsd/wlevs_application_config.xsd"
todir="src/main/resources/extension" />
<xjc extension="true" destdir="${generated.dir}">
<schema dir="src/main/resources/extension"
includes="helloworld.xsd"/>
<produces dir="${generated.dir}" includes="**/*.java" />
</xjc>
</target>
In the example, the extended XSD file is called helloworld.xsd
. The build process copies the WebLogic Event Server XSD files (wlevs_base_config.xsd
and wlevs_application_config.xsd
) to the same directory as the helloworld.xsd
file because helloworld.xsd
imports the WebLogic Event Server XSD files.
See Assembling a WebLogic Event Server Application: Main Steps for details.
<?xml version="1.0" encoding="UTF-8"?>
<helloworld:config
xmlns:helloworld="http://www.bea.com/xml/ns/wlevs/example/helloworld"
>
<adapter>
<name>helloworldAdapter</name><message>HelloWorld - the current time is:</message>
</adapter>
</helloworld:config>
The new XSD schema file extends the
wlevs_application_config.xsd
XSD schema and then adds new custom information, such as new configuration elements for an adapter. Use standard XSD schema syntax for your custom information.
BEA recommends that you use the XSD schema from the HelloWorld example as a basic template, and modify the content to suit your needs. In addition to adding new configuration elements, other modifications include changing the package name of the generated Java code and the element name for the custom adapter. You can control whether the schema allows just your custom adapter or other components like processors.
Follow these steps when creating the XSD Schema file that describes your extended adapter configuration; see Complete Example of an Extended XSD Schema File for the HelloWorld example:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.bea.com/xml/ns/wlevs/example/helloworld"
xmlns="http://www.bea.com/xml/ns/wlevs/example/helloworld"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:wlevs="http://www.bea.com/xml/ns/wlevs/config/application"
jxb:extensionBindingPrefixes="xjc" jxb:version="1.0"
elementFormDefault="unqualified" attributeFormDefault="unqualified">
...
</xs:schema>
wlevs_application_config.xsd
XSD schema:<xs:import
namespace="http://www.bea.com/xml/ns/wlevs/config/application"
schemaLocation="wlevs_application_config.xsd"/>
The wlevs_application_config.xsd
in turn imports the
wlevs_base_config.xsd
XSD file.
<complexType>
XSD element to describe the XML type of the extended adapter configuration.
The new type must extend the AdapterConfig
type, defined in wlevs_application_config.xsd
. AdapterConfig
extends ConfigurationObject
. You can then add new elements or attributes to the basic adapter configuration as needed. For example, the following type called HelloWorldAdapterConfig
adds a <message>
element to the basic adapter configuration:
<xs:complexType name="HelloWorldAdapterConfig">
<xs:complexContent>
<xs:extension base="wlevs:AdapterConfig">
<xs:sequence>
<xs:element name="message" type="xs:string"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<config>
.
In the definition of the config
element, define a sequence of child elements that correspond to the components in your application. Typically the name of the elements should indicate what component they configure (adapter
, processor
, stream
) although you can name then anything you want.
Each element must extend the ConfigurationObject
XML type, either explicitly using the <xs:extension base="base:ConfigurationObject"/>
XSD tag or by specifying an XML type that itself extends ConfigurationObject
. The ConfigurationObject
XML type, defined in wlevs_base_config.xsd
, defines a single attribute: name
.
The type of your adapter element should be the custom one you created in a preceding step of this procedure.
You can use the following built-in XML types, described in wlevs_application_config.xsd
, for the child elements of <config>
that correspond to processors or streams:
DefaultProcessorConfig
—See Overview of the Complex Event Processer Configuration File for a description of the default processor configuration.DefaultStreamConfig
—See Overview of the Stream Configuration File for a description of the default stream configuration.<xs:element name="config">
<xs:complexType>
<xs:choice maxOccurs="unbounded">
<xs:element name="adapter" type="HelloWorldAdapterConfig"/>
<xs:element name="processor" type="wlevs:DefaultProcessorConfig"/>
</xs:choice>
</xs:complexType>
</xs:element>
<jxb:package>
child element of <jxb:schemaBindings>
to specify the package name of the generated Java code:<xs:annotation>
<xs:appinfo>
<jxb:schemaBindings>
<jxb:package name="com.bea.adapter.wlevs.example.helloworld"/>
</jxb:schemaBindings>
</xs:appinfo>
</xs:annotation>
The following extended XSD file is used in the HelloWorld sample application:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.bea.com/xml/ns/wlevs/example/helloworld"
xmlns="http://www.bea.com/xml/ns/wlevs/example/helloworld"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:wlevs="http://www.bea.com/xml/ns/wlevs/config/application"
jxb:extensionBindingPrefixes="xjc" jxb:version="1.0"
elementFormDefault="unqualified" attributeFormDefault="unqualified">
<xs:annotation>
<xs:appinfo>
<jxb:schemaBindings>
<jxb:package name="com.bea.adapter.wlevs.example.helloworld"/>
</jxb:schemaBindings>
</xs:appinfo>
</xs:annotation>
<xs:import namespace="http://www.bea.com/xml/ns/wlevs/config/application"
schemaLocation="wlevs_application_config.xsd"/>
<xs:element name="config">
<xs:complexType>
<xs:choice maxOccurs="unbounded">
<xs:element name="adapter" type="HelloWorldAdapterConfig"/>
<xs:element name="processor" type="wlevs:DefaultProcessorConfig"/>
<xs:element name="stream" type="wlevs:DefaultStreamConfig"/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:complexType name="HelloWorldAdapterConfig">
<xs:complexContent>
<xs:extension base="wlevs:AdapterConfig">
<xs:sequence>
<xs:element name="message" type="xs:string"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
</xs:schema>
When you deploy your application, WebLogic Event Server maps the configuration of each component (specified in the component configuration XML files) into Java objects using the Java Architecture for XML Binding (JAXB) standard. Because there is a single XML element that contains the configuration data for each component, JAXB in turn also produces a single Java class that represents this configuration data. WebLogic Event Server passes an instance of this Java class to the component (processor, stream, or adapter) at runtime when the component is initialized, and also whenever there is a dynamic change to the component's configuration.
In your adapter implementation, you can use metadata annotations to specify the Java methods that are invoked by WebLogic Event Server at runtime. WebLogic Event Server passes an instance of the configuration Java class to the specified methods; you can then program these methods to get specific runtime configuration information about the adapter. The following example shows how to annotate the activateAdapter()
method with the @Activate
annotation to specify the method invoked when the adapter configuration is first activated:
@Activate
public void activateAdapter(HelloWorldAdapterConfig adapterConfig) {
this.message = adapterConfig.getMessage();
}
By default, the date type of the adapter configuration Java class is com.bea.wlevs.configuration.application.DefaultAdapterConfig
. If, however, you have extended the configuration of your adapter by creating your own XSD file that describes the configuration XMLfile, then you specify the type in the XSD file. In the preceding example, because the HelloWorld sample extends the configuration of its adapter, the data type of the Java configuration object is com.bea.wlevs.example.helloworld.HelloWorldAdapterConfig
.
The metadata annotations provided are as follows:
com.bea.wlevs.management.Activate
—Specifies the method invoked when the configuration is activated. See Activate for additional details about using this annotation in your adapter code.
com.bea.wlevs.management.Prepare
—Specifies the method invoked when the configuration is prepared.See Prepare for additional details about using this annotation in your adapter code.
com.bea.wlevs.management.Rollback
—Specifies the method invoked when the adapter is terminated due to an exception.See Rollback for additional details about using this annotation in your adapter code.
If your adapter accesses an external data feed, the adapter might need to pass login credentials (username and password) to the data feed for user authentication.
The simplest, and least secure, way to do this is to hard-code the non-encrypted login credentials in your adapter Java code. However, this method does not allow you to encrypt the password or later change the login credentials without recompiling the adapter Java code.
The following procedure describes a different method that takes these two issues into account. In the procedure, it is assumed that the username to access the data feed is juliet
and the password is superSecret
.
Configuring the credentials statically in the EPN assembly file is easier, but if the credentials later change you must restart the application for the update to the EPN assembly file to take place. Extending the adapter configuration allows you to change the credentials dynamically without restarting the application, but extending the configuration involves additional steps, such as creating an XSD file and compiling it into a JAXB object.
<wlevs:adapter>
tag that declares your adapter. In particular, add two instance properties that correspond to the username and password of the login credentials. For now, specify the cleartext password value; you will encrypt it in a later step. Also add a temporary <password>
element whose value is the cleartext password. For example:<wlevs:adapter id="myAdapter" provider="myProvider">
<wlevs:instance-property name="user" value="juliet"/>
<wlevs:instance-property name="password" value="superSecret"/>
<password>superSecret</password>
</wlevs:adapter>
java
command to encrypt the value of the <password>
element in the EPN assembly file:prompt> java -jarBEA_HOME
/modules/com.bea.core.bootbundle_3.0.1.0.jar .epn_assembly_file
where BEA_HOME
refers to the main BEA directory into which you installed WebLogic Event Server, such as d:\beahome
. The second argument refers to the directory that contains the EPN assembly file; because this procedure directs you to change to the directory, the example shows "."
. The epn_assembly_file
parameter refers to the name of your EPN assembly file.
After you run the command, the value of the <password>
element of the EPN assembly file will be encrypted.
<password>
element to the value
attribute of the password
instance property. Remove the <password>
element from the XML file. For example:<wlevs:adapter id="myAdapter" provider="myProvider">
<wlevs:instance-property name="user" value="juliet"/>
<wlevs:instance-property name="password"
value="{Salted-3DES}B7L6nehu7dgPtJJTnTJWRA=="
/>
</wlevs:adapter>
<user>
and <password>
, both of type string. For example, if you were extending the adapter in the HelloWorld example, the XSD file might look like the following:
<xs:complexType name="HelloWorldAdapterConfig">
<xs:complexContent>
<xs:extension base="wlevs:AdapterConfig">
<xs:sequence>
<xs:element name="message" type="xs:string"/><xs:element name="user" type="xs:string"/>
</xs:sequence>
<xs:element name="password" type="xs:string"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
See Extending the Configuration of an Adapter for detailed instructions.
<user>
and <password>
elements. For now, specify the cleartext password value; you will encrypt it in a later step. For example:<?xml version="1.0" encoding="UTF-8"?>
<myExample:config
xmlns:myExample="http://www.bea.com/xml/ns/wlevs/example/myExample">
<adapter>
<name>myAdapter</name><user>juliet</user>
</adapter>
<password>superSecret</password>
</myExample:config>
java
command to encrypt the value of the <password>
element in the adapter configuration file:prompt> java -jarBEA_HOME
/modules/com.bea.core.bootbundle_3.0.1.0.jar .adapter_config_file
where BEA_HOME
refers to the main BEA directory into which you installed WebLogic Event Server, such as d:\beahome
. The second argument refers to the directory that contains the adapter configuration file; because this procedure directs you to change to the directory, the example shows "."
. The adapter_config_file
parameter refers to the name of your adapter configuration file file.
After you run the command, the value of the <password>
element will be encrypted.
See Updating the Adapter Code to Access the Login Credential Properties.
MANIFEST.MF
file of the application and add the com.bea.core.encryption
package to the Import-Package
header. See Creating the MANIFEST.MF File.
This section describes how update your adapter Java code to dynamically get the user and password values from the extended adapter configuration, and then use the com.bea.core.encryption.EncryptionService
API to decrypt the encrypted password. The code snippets below build on the HelloWorld adapter Java code, shown in Programming the Adapter Class: Guidelines.
import com.bea.core.encryption.EncryptionService;
import com.bea.core.encryption.EncryptionServiceException;
import com.bea.wlevs.util.Service;
@Service
annotation to get a reference to the EncryptionService
:private EncryptionService encryptionService;
...
@Service
public void setEncryptionService(EncryptionService encryptionService) {
this.encryptionService = encryptionService;
}
@Prepare
callback method, get the values of the user
and password
properties of the extended adapter configuration as usual (only code for the password
value is shown):private String password;
...
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
...
@Prepare
public void checkConfiguration(HelloWorldAdapterConfig adapterConfig) {
if (adapterConfig.getMessage() == null
|| adapterConfig.getMessage().length() == 0) {
throw new RuntimeException("invalid message: " + message);
}this.password= adapterConfig.getPassword();
...
}
See Programming Access to the Configuration of an Adapter for information about accessing the extended adapter configuration.
EncryptionService.decryptStringAsCharArray()
method in the @Prepare
callback method to decrypt the encrypted password:@Prepare
public void checkConfiguration(HelloWorldAdapterConfig adapterConfig) {
if (adapterConfig.getMessage() == null
|| adapterConfig.getMessage().length() == 0) {
throw new RuntimeException("invalid message: " + message);
}
this.password= adapterConfig.getPassword();try {
}
char[] decrypted = encryptionService.decryptStringAsCharArray(password);
System.out.println("DECRYPTED PASSWORD is "+ new String(decrypted));
} catch (EncryptionServiceException e) {
throw new RuntimeException(e);
}
The signature of the decryptStringAsCharArray()
method is as follows:
char[] decryptStringAsCharArray(String encryptedString)
throws EncryptionServiceException