Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Event Processing
11g Release 1 (11.1.1.7) for Eclipse

Part Number E14301-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
PDF · Mobi · ePub

I Oracle Event Processing Metadata Annotation Reference

This appendix provides a reference to Oracle Event Processing Java annotations you can use to specify methods that handle adapter lifecycle stages, a method injected with an OSGi service reference, and to configure resource access at design time.

This appendix includes the following sections:

I.1 Overview of Oracle Event Processing Metadata Annotations

Oracle Event Processing metadata annotations are used to access the configuration of an Oracle Event Processing component. Oracle Event Processing offers the following annotations:

For more information, see:

I.1.1 Adapter Lifecycle Annotations

You use the following annotations to specify the methods of an adapter Java implementation that handle various stages of the adapter's lifecyle: when its configuration is prepared, when the configuration is activated, and when the adapter is terminated due to an exception:

I.1.2 OSGi Service Reference Annotations

Use the com.bea.wlevs.util.Service annotation to specify the method of a component that is injected with an OSGi service reference.

I.1.3 Resource Access Annotations

Use the following annotations to configure resource access at design time and the corresponding deployment XML to override this configuration at deploy time:

  • javax.annotation.Resource

For more information, see Section 1.4.3, "Configuring Oracle Event Processing Resource Access".

I.2 com.bea.wlevs.configuration.Activate

Target: Method

The @Activate annotation is one of the adapter lifecycle annotations that you use in the Java file that implements your custom adapter to explicitly specify the methods that Oracle Event Processing uses to send configuration information to the adapter.

Oracle Event Processing calls methods marked with the @Activate annotation after, and if, the server has called and successfully executed all the methods marked with the @Prepare annotation. You typically use the @Activate method to actually get the adapter's configuration data to use in the rest of the adapter implementation.

The method you annotate with this annotation must have the following signature:

public void methodName(AdapterConfigObject adapterConfig)

where methodName refers to the name you give the method and AdapterConfigObject refers to the Java representation of the adapter's configuration XML file which is deployed with the application. The type of this class is com.bea.wlevs.configuration.application.DefaultAdapterConfig by default; if, however, you have extended the configuration of the adapter, then the type is whatever have specified in the XSD that describes the extended XML file. For example, in the HelloWorld sample, the type is com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig.

At runtime, Oracle Event Processing automatically creates an instance of this class, populates it with data from the actual XML file, and passes the instance to the adapter. The adapter methods annotated with the adapter lifecycle annotations can then use the class to get information about the adapter's configuration.

This metadata annotation does not have any attributes.

I.2.1 Example

Example I-1 shows how to use the @Activate annotation in the adapter component of the HelloWorld example; only relevant code is shown:

Example I-1 @Activate Annotation

package com.bea.wlevs.adapter.example.helloworld;
...
import com.bea.wlevs.configuration.Activate;
import com.bea.wlevs.ede.api.RunnableBean;
import com.bea.wlevs.ede.api.StreamSender;
import com.bea.wlevs.ede.api.StreamSource;
import com.bea.wlevs.event.example.helloworld.HelloWorldEvent;

public class HelloWorldAdapter implements RunnableBean, StreamSource {
...
    @Activate
    public void activateAdapter(HelloWorldAdapterConfig adapterConfig) {
        this.message = adapterConfig.getMessage();
    }
...
}

The com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig class is a Java representation of the adapter's configuration XML file. In the HelloWorld example, the configuration has been extended; this means a custom XSD file describes the XML file. Example I-2 shows this XSD file also specifies the fully qualified name of the resulting Java configuration object, as shown in bold:

Example I-2 HelloWorldAdapterConfig

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns="http://www.bea.com/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/ns/wlevs/config/application"
  targetNamespace="http://www.bea.com/ns/wlevs/example/helloworld"
  elementFormDefault="unqualified" attributeFormDefault="unqualified" 
  jxb:extensionBindingPrefixes="xjc" jxb:version="1.0">
   <xs:annotation>
      <xs:appinfo>
        <jxb:schemaBindings>
          <jxb:package name="com.bea.wlevs.adapter.example.helloworld"/>
        </jxb:schemaBindings>
      </xs:appinfo>
   </xs:annotation>
   <xs:import namespace="http://www.bea.com/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="channel" 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>

Oracle Event Processing automatically creates an instance of this class when the application is deployed. For example, the adapter section of the helloworldAdapter configuration file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
  <helloworld:config
  ...
    <adapter>
      <name>helloworldAdapter</name>
      <message>HelloWorld - the current time is:</message>
    </adapter>
</helloworld:config>

In the Java code of the adapter above, the activateAdapter method is annotated with the @Activate annotation. The method uses the getMessage method of the configuration object to get the value of the message property set in the adapter's configuration XML file. In this case, the value is HelloWorld - the current time is:. This value can then be used in the main part of the adapter implementation file.

I.3 com.bea.wlevs.configuration.Prepare

Target: Method

The @Prepare annotation is one of the adapter lifecycle annotations that you use in the Java file that implements your custom adapter to explicitly specify the methods that Oracle Event Processing uses to send configuration information to the adapter.

Oracle Event Processing calls the method annotated with @Prepare whenever a component's state has been updated by a particular configuration change.

The method you annotate with this annotation must have the following signature:

public void methodName(AdapterConfigObject adapterConfig)

where methodName refers to the name you give the method and AdapterConfigObject refers to the Java representation of the adapter's configuration XML file which is deployed with the application. The type of this class is com.bea.wlevs.configuration.application.DefaultAdapterConfig by default; if, however, you have extended the configuration of the adapter, then the type is whatever have specified in the XSD that describes the extended XML file. For example, in the HelloWorld sample, the type is com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig.

At runtime, Oracle Event Processing automatically creates an instance of this class, populates it with data from the actual XML file, and passes the instance to the adapter. The adapter methods annotated with the adapter lifecycle annotations can then use the class to get information about the adapter's configuration.

This metadata annotation does not have any attributes.

I.3.1 Example

Example I-3, from the adapter component of the HelloWorld example, shows how to use the @Prepare annotation; only relevant code is shown:

Example I-3 @Prepare Annotation

package com.bea.wlevs.adapter.example.helloworld;
...
import com.bea.wlevs.configuration.Prepare;
import com.bea.wlevs.ede.api.RunnableBean;
import com.bea.wlevs.ede.api.StreamSender;
import com.bea.wlevs.ede.api.StreamSource;
import com.bea.wlevs.event.example.helloworld.HelloWorldEvent;

public class HelloWorldAdapter implements RunnableBean, StreamSource {
...
    @Prepare
    public void checkConfiguration(HelloWorldAdapterConfig adapterConfig) {
        if (adapterConfig.getMessage() == null
                || adapterConfig.getMessage().length() == 0) {
            throw new RuntimeException("invalid message: " + message);
        }
    }
...
}

The com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig class is a Java representation of the adapter's configuration XML file; Oracle Event Processing automatically creates an instance of this class when the application is deployed. In the HelloWorld example, the adapter configuration has been extended. See the example in Appendix I, "com.bea.wlevs.configuration.Activate" for additional details.

In the Java code of the adapter above, the checkConfiguration method is annotated with the @Prepare annotation, which means this method is called when the adapter's configuration changes in some way. The example further shows that the method checks to make sure that the message property of the adapter's configuration (set in the extended adapter configuration file) is not null or empty; if it is, then the method throws an exception.

I.4 com.bea.wlevs.configuration.Rollback

Target: Method

The @Rollback annotation is one of the adapter lifecycle annotations that you use in the Java file that implements your custom adapter to explicitly specify the methods that Oracle Event Processing uses to send configuration information to the adapter.

Oracle Event Processing calls the method annotated with @Rollback whenever a component whose @Prepare method was called but threw an exception. The server calls the @Rollback method for each component for which this is true.

The method you annotate with this annotation must have the following signature:

public void methodName(AdapterConfigObject adapterConfig)

where methodName refers to the name you give the method and AdapterConfigObject refers to the Java representation of the adapter's configuration XML file which is deployed with the application. The type of this class is com.bea.wlevs.configuration.application.DefaultAdapterConfig by default; if, however, you have extended the configuration of the adapter, then the type is whatever have specified in the XSD that describes the extended XML file. For example, in the HelloWorld sample, the type is com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig.

At runtime, Oracle Event Processing automatically creates an instance of this class, populates it with data from the actual XML file, and passes the instance to the adapter. The adapter methods annotated with the adapter lifecycle annotations can then use the class to get information about the adapter's configuration.

This metadata annotation does not have any attributes.

I.4.1 Example

Example I-4, sample code from the adapter component of the HelloWorld example, shows how to use the @Rollback annotation; only relevant code is shown:

Example I-4 @Rollback Annotation

package com.bea.wlevs.adapter.example.helloworld;
...
import com.bea.wlevs.configuration.Rollback;
import com.bea.wlevs.ede.api.RunnableBean;
import com.bea.wlevs.ede.api.StreamSender;
import com.bea.wlevs.ede.api.StreamSource;
import com.bea.wlevs.event.example.helloworld.HelloWorldEvent;

public class HelloWorldAdapter implements RunnableBean, StreamSource {
...
    @Rollback
    public void rejectConfigurationChange(HelloWorldAdapterConfig adapterConfig) {
    }

The com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig class is a Java representation of the adapter's configuration XML file; Oracle Event Processing automatically creates an instance of this class when the application is deployed. In the HelloWorld example, the adapter configuration has been extended. See the example in Appendix I, "com.bea.wlevs.configuration.Activate" for additional details.

In the example, the rejectConfigurationChange method is annotated with the @Rollback annotation, which means this is the method that is called if the @Prepare method threw an exception. In the example above, nothing actually happens.

I.5 com.bea.wlevs.util.Service

Target: Method

Specifies that the annotated method, typically a JavaBean setter method, requires an OSGi service reference.

I.5.1 Attributes

Table I-1 describes the attributes of the com.bea.wlevs.util.Service JWS annotation.

Table I-1 Attributes of the com.bea.wlevs.util.Service JWS Annotation Tag

Name Description Data Type Required?

serviceBeanName

The name of the bean that backs the injected service. May be null.

String

No.

cardinality

Valid values for this attribute are:

  • ServiceCardinality.C0__1

  • ServiceCardinality.C0__N

  • ServiceCardinality.C1__1

  • ServiceCardinality.C1__N

Default value is ServiceCardinality.C1__1.

enum

No.

contextClassloader

Valid values for this attribute are:

  • ServiceClassloader.CLIENT

  • ServiceClassloader.SERVICE_PROVIDER

  • ServiceClassloader.UNMANAGED

Default value is ServiceClassloader.CLIENT.

enum

No.

timeout

Timeout for service resolution in milliseconds.

Default value is 30000.

int

No.

serviceType

Interface (or class) of the service to be injected

Default value is Service.class.

Class

No.

filter

Specifies the filter used to narrow service matches. Value may be null.

String

No.


I.5.2 Example

Example I-5 shows how to use the @Service annotation.

Example I-5 @Service Annotation

@Service(filter = "(Name=StockDs)")
public void setDataSourceService(DataSourceService dss) {
    initStockTable(dss.getDataSource());
}

For another example, see Section 9.4, "Accessing the Event Type Repository".