How to Configure Oracle JDBC Data Cartridge Application Context

19 Extending Component Configuration 19-1 19 Extending Component Configuration This chapter describes: ■ Section 19.1, Overview of Extending Component Configuration ■ Section 19.2, Extending Component Configuration ■ Section 19.3, Programming Access to the Configuration of a Custom Adapter or Event Bean

19.1 Overview of Extending Component Configuration

Adapters and event beans have default configuration data. This default configuration is typically adequate for simple and basic applications. However, you can also extend this configuration by using a XML Schema Definition XSD schema to specify a new XML format of an adapter configuration file that extends the built-in XML type provided by Oracle CEP. 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 and Java Architecture for XML Binding JAXB. You can extend component configuration by: ■ Annotating your adapter or event bean Java class with the annotations that javax.xml.bind.annotation specifies. See Section 19.1.1, Extending Component Configuration Using Annotations . ■ Manually generating an XSD. See Section 19.1.2, Extending Component Configuration Using an XSD . ■ Manually generating a custom schema which does not extend the application schema. This allows you to create custom configuration in your own namespace without having to define all the other elements. This mechanism functions like the annotation approach after you generate the schema. For more information, see: ■ Chapter 14, Configuring Custom Adapters ■ Chapter 15, Configuring Custom Event Beans ■ Section B.2, Component Configuration Schema wlevs_application_config.xsd 19-2 Oracle Complex Event Processing Developers Guide

19.1.1 Extending Component Configuration Using Annotations

The simplest and most efficient way to extend component configuration is to annotate your adapter or event bean Java class using the annotations that javax.xml.bind.annotation specifies. Oracle CEP supports the inclusion of multiple namespaces in an EPN configuration file as well as supporting sourcing configuration information from the providing bundle rather than the client bundle. Oracle CEP scans for multiple ObjectFactories in the accessible class-space and each of these will be initialized through createConfig. The schema search takes into account the wlevs:factory element provider-schema child element in adapter bundles. So if you are defining an adapter in its own bundle you can put the schema in that bundle as long as you define the provider-bundle property. Oracle recommends that you use elementFormDefault=unqualified so that locally defined elements will not have a namespace, but global elements will leverage the targetNamespace. This will avoid name clashes across schemas without requiring excessive prefixing. For more information, see http:www.xfront.comHideVersusExpose.html . For more information, see: ■ Section 19.2.1, How to Extend Component Configuration Using Annotations ■ http:java.sun.comjavaee6docsapijavaxxmlbindannotation package-summary.html

19.1.2 Extending Component Configuration Using an XSD

If you require more detailed control over your custom component configuration, you can extend your component configuration by creating your own XSD. For more information, see: ■ Section 19.2.2, How to Extend Component Configuration Using an XSD ■ https:jaxb.dev.java.net

19.2 Extending Component Configuration

You can extend component configuration in either of the following ways: For more information, see Section 19.1, Overview of Extending Component Configuration .

19.2.1 How to Extend Component Configuration Using Annotations

The simplest and most efficient way to extend component configuration is to annotate your adapter or event bean Java class. Alternatively, you can extend component configuration by creating your own XSD as Section 19.2.2, How to Extend Component Configuration Using an XSD describes. For more information, see Section 19.1.1, Extending Component Configuration Using Annotations . To extend component configuration using annotations: 1. Implement your custom adapter or event bean Java class. Extending Component Configuration 19-3 For more information, see: ■ Section 14.2, Implementing a Custom Adapter ■ Section 15.2, Implementing a Custom Event Bean 2. Annotate the attributes of your custom adapter or event bean to specify the component configuration using the annotations that javax.xml.bind.annotation specifies. Important javax.xml.bind.annotation annotations include: ■ XmlElement: property is an optional part of the component configuration. ■ XmlElementrequired=true: property is a required part of the component configuration. ■ XmlTransient: property is not part of the component configuration. ■ XmlJavaTypeAdapter: property elements annotated with this can specify custom handling to accomodate most Java data types. Example 19–1 shows a custom adapter implementation annotated with javax.xml.bind.annotation annotations to specify: ■ count: not part of the component configuration. ■ doit: required part of the component configuration. ■ size: required part of the component configuration; maps to instance property howBig. Example 19–1 Annotated Custom Adapter Implementation XmlTypename=SampleAdapterConfig, namespace=http:www.oracle.comnscepconfigsample public class SampleAdapterImpl implements Adapter { XmlTransient private int count; XmlElementname=size private int howBig; XmlElementrequired=true private boolean doit; ... public void setDoitboolean doit { this.doit = doit; } public boolean getDoit { return doit; } } Note: If you require extensive use of XmlJavaTypeAdapter, consider defining your own custom schema as Section 19.2.2, How to Extend Component Configuration Using an XSD describes. Note: A property without an annotation is assumed to be an optional configuration property default: XmlElement. 19-4 Oracle Complex Event Processing Developers Guide 3. Within your custom adapter or event bean code, access the extended configuration as Section 19.3, Programming Access to the Configuration of a Custom Adapter or Event Bean describes. 4. Modify the component configuration XML file that describes the custom components of your application. For more information, see Section 14.5, Configuring the Custom Adapter Component Configuration File . 5. When you create the component configuration XML file that describes the components of your application, be sure to use the extended XSD file as its description. In addition, be sure you identify the namespace for this schema rather than the default schema. Example 19–2 shows a component configuration file for the custom adapter in Example 19–1 . Example 19–2 Extended Component Configuration: Annotations ?xml version=1.0 encoding=UTF-8? app:config xmlns:app=http:www.bea.comnswlevsconfigapplication xmlns:sample=http:www.oracle.comnscepconfigsample xmlns:xsi=http:www.w3.org2001XMLSchema-instance xsi:schemaLocation= http:www.bea.comnswlevsconfigapplication http:www.bea.comnswlevsconfigapplicationwlevs_application_config.xsd http:www.oracle.comnscepconfigsample http:www.oracle.comnscepconfigsampleocep_sample_config.xsd processor nameclusterProcessorname rules query id=clusterRule[CDATA[ select from clusterInstream [Now] ]]query rules processor sample:adapter namemyadaptername config size15size -- optional -- doittruedoit -- required -- config sample:adapter app:config 6. Package and deploy your application. For more information, see Chapter 24, Assembling and Deploying Oracle CEP Applications .

19.2.2 How to Extend Component Configuration Using an XSD

You can extend the component configuration of a custom adapter or event bean using your own XSD. Alternatively, you can extend component configuration by annotating your adapter or event bean Java class as Section 19.2.1, How to Extend Component Configuration Using Annotations describes. Note: The extended component configuration schema requires a nested config element as Example 19–5 shows. Extending Component Configuration 19-5 For more information, see Section 19.1.2, Extending Component Configuration Using an XSD . To extend component configuration using an XSD: 1. Create the new XSD Schema file that describes the extended adapter or event bean configuration. This XSD file must also include the description of the other components in your application processors and streams, although you typically use built-in XSD types, defined by Oracle CEP, to describe them. See Section 19.2.2.1, Creating the XSD Schema File . 2. As part of your application build process, generate the Java representation of the XSD schema types using a JAXB binding compiler, such as the com.sun.tools.xjc.XJCTask Ant task from Suns GlassFish reference implementation. This Ant task is included in the Oracle CEP distribution for your convenience. The following sample build.xml file shows how to do this: 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=........xsdwlevs_base_config.xsd todir=srcmainresourcesextension copy file=........xsdwlevs_application_config.xsd todir=srcmainresourcesextension xjc extension=true destdir={generated.dir} schema dir=srcmainresourcesextension 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 Oracle CEP 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 Oracle CEP XSD files. For more information, see https:jaxb.dev.java.netjaxb20-eadocsxjcTask.html . 3. Compile these generated Java files into classes. 4. Package the compiled Java class files in your application bundle. See Section 24.2, Assembling an Oracle CEP Application .