You can use an XML schema definition (XSD) or Java Architecture for XML Binding (JAXB) annotations to extend the default configuration for adapters and event beans.
This chapter includes the following sections:
The simplest and most efficient way to extend component configuration is to annotate your custom adapter or event bean JavaBean class with the annotations provided in the JAXB javax.xml.bind.annotation package. For more information, see http://docs.oracle.com/javaee/7/api/javax/xml/bind/annotation/package-summary.html and https://jaxb.java.net/.
Extend Component Configuration with Annotations
You can extend an adapter or an event bean configuration with an XML Schema Definition (XSD) file. Add as many custom elements to the XSD file as you need with few restrictions other than each new element must have a name attribute.
When you set up the name spaces, Oracle recommends that you use elementFormDefault="unqualified" so that locally defined elements do not have a names pace, but global elements leverage the targetNamespace. This avoids name clashes across schemas without requiring excessive prefixing. For more information, see http://www.xfront.com/HideVersusExpose.html.
You can also manually generate a custom schema that does not extend the application schema. This allows you to create custom configuration in your own name space without having to define all of the other elements. This mechanism functions like the annotation approach after you generate the schema.
The new XSD file extends the wlevs_application_config.xsd XSD and adds new custom information, such as new configuration elements for an adapter. Use standard XSD syntax for your custom information.
Oracle recommends that you use the XSD in Complete Example of an XSD Schema File 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.
Create a New XSD File
Use the following extended XSD file as a template:
<?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/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/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>
When you deploy your application, Oracle Stream Analytics maps the configuration of each component specified in the component configuration files into Java objects that adhere to the JAXB standard. Because there is a single XML element that contains the configuration data for each component, JAXB also produces a single Java class that represents the configuration data. Oracle Stream Analytics passes an instance of this Java class to the component (processor, channel, or adapter) at runtime when the component initializes and whenever a dynamic change to the component configuration occurs.
You can access this component configuration at run time in the following ways:
With resource injection as Resource Injection describes.
This is the simplest and most efficient way to access component configuration at runtime.
With callbacks as Life Cycle Callbacks.
This is the most flexible way to access component configuration at run time. Consider this option if resource injection does not meet your needs.
Note:
Clients that need to use a schema from a provider must import the appropriate package from the provider bundle so the provider's ObjectFactory is visible to the client bundle.
By default Oracle Stream Analytics configures adapters and event beans by direct injection of their JavaBean properties followed by configuration callbacks.
Consider the annotated custom adapter implementation.
@XmlType(name="SampleAdapterConfig", namespace="http://www.oracle.com/ns/cep/config/sample/")
public class SampleAdapterImpl implements Adapter {
private boolean doit;
public void setDoit(boolean doit) {
this.doit = doit;
}
public boolean getDoit() {
return doit;
}
}
Consider the configuration file for an instance of this custom adapter.
<?xml version="1.0" encoding="UTF-8"?>
<app:config
xmlns:app="http://www.bea.com/ns/wlevs/config/application"
xmlns:sample="http://www.oracle.com/ns/cep/config/sample/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.bea.com/ns/wlevs/config/application
http://www.bea.com/ns/wlevs/config/application/wlevs_application_config.xsd
http://www.oracle.com/ns/cep/config/sample
http://www.oracle.com/ns/cep/config/sample/ocep_sample_config.xsd">
<processor>
<name>clusterProcessor</name>
<rules>
<query id="clusterRule"><![CDATA[ select * from clusterInstream [Now] ></query>
</rules>
</processor>
<sample:adapter>
<name>myadapter</name>
<config>
<doit>true</doit>
</config>
</sample:adapter>
</app:config>
At runtime Oracle Stream Analytics calls the setDoIt method of the adapter instance and passes the value true as the argument value.
Note:
The extended component configuration schema requires a nested config element.
In your adapter or event bean implementation, you can use metadata annotations to specify the Java methods to be invoked by Oracle Stream Analytics at runtime. Oracle Stream Analytics passes an instance of the configuration Java class to these specified methods. You can program these methods to get specific run time configuration information about the adapter or event bean.
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 data type of the adapter configuration Java class is com.bea.wlevs.configuration.application.DefaultAdapterConfig. If you have extended the configuration of the adapter (or event bean) by creating your own XSD file that describes the configuration XML file, then you specify the type in the XSD file. In the preceding example, the data type of the Java configuration object is com.bea.wlevs.example.helloworld.HelloWorldAdapterConfig.
You can use the following metadata annotations to specify life cycle callback methods:
com.bea.wlevs.management.Activate: Specifies the method invoked when the configuration is activated.
com.bea.wlevs.management.Prepare: Specifies the method invoked when the configuration is prepared. See Getting Started with Event Processing for Oracle Stream Analytics 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.
Oracle Stream Analytics uses the following life cycle to create adapter and event beans.
Create the adapter or event bean instance.
Inject static properties.
Call the afterPropertiesSet method.
Prepare phase:
If @Prepare with one or more configuration arguments is present, call it. Otherwise, directly inject configuration properties.
If @Prepare without arguments is present, call it.
Activate phase:
If @Activate with one or more configuration arguments is present, call it.
If @Activate without arguments is present, call it.
Call afterConfigurationActive.
Continue with other configuration.