Parameterized Applications contain special parameters (variables) that must be configured before the application starts. Generally, you configure a parameterized application when you deploy the application with the Oracle Stream Analytics EPN shell. After a parameterized applications is configured, it functions as a regular application.
This chapter includes the following sections:
Application parameters define property values that can be set when the user launches an application. You can parameterize properties for adapters, channels, event beans, Spring beans, and Oracle CQL parameterized queries with and without views.
You define application parameters (attributes) by grouping attribute definitions (ADs) into object class definitions (OCDs). You create one OCD for each application component that you want to parameterize. An OCD contains one or more ADs to specify the component properties to parameterize and the prompt text.
Place the OCDs in an XML document (metatype file) in the OSGI-INF/metatype directory within the Oracle Stream Analytics application. The metatype file uses and complies with the schema defined by the specification at: http://www.osgi.org/xmlns/metatype/v1.1.0/metatype.xsd.
See Example metatype File for an example configuration.
Oracle Stream Analytics parameterized applications conform to the OSGi MetaType specification at http://www.osgi.org. See the Apache implementation at http://felix.apache.org/documentation/subprojects/apache-felix-metatype-service.html.
Every OCD requires the name, id, and description parameters. The following example is an OCD with no ADs.
This OCD defines application metadata, but because there are no ADs, the description displays, but the user is not prompted for input. This type of OCD documents the application.
<OCD name="HelloWorld Sample" id="com.oracle.cep.sample.helloworld" description="The helloworld OEP application is a sample application for Oracle Event Processing."> </OCD>
Every AD requires the name, id, and description parameters. The following example is an OCD with two ADs.
The OCD provides a common definition for the channel component and provides parameterized attributes (ADs) for the maximum number of threads and the maximum buffer size of the channel.
When the user runs the application, the application displays the description and the other information that you provided, and waits for the user to enter the requested information and press the Return key.
<OCD name="Channel Configuration" id="com.oracle.cep.channel"
description="The channel definition in the OCEP Application"
ocep:binding="jmx:EventChannel">
<AD name="Max Threads" id=".maxThreads" type="Integer" required="true"
default="0" min="0" max="100"
description="Number of threads generating messages."
ocep:binding="MaxThreads" />
<AD name="Max Size" id=".maxSize" type="Integer" required="true"
default="0" min="0" max="100"
description="The maximum size of the FIFO buffer for this channel."
ocep:binding="MaxSize" />
</OCD>
Note:
To avoid errors, always define Max Threads before Max Size in the metatype file.
For the 12c release, the only supported binding is Java Management Extension (JMX). This means that the AD attributes must be bound to a corresponding JMX attribute. See Targeting.
You can connect an OCD and an application component with the Designate element. The application class definition can then be a target for multiple designates (components of the same type) to enable the reuse of definitions.
To prevent ambiguities, each designate can be associated with one object class definition only.
Oracle Stream Analytics supports the following designates:
Adapter, Oracle CQL Processor, event bean, or Spring bean.
Oracle CQL processor rules such as a query or a view. In the case of a rule, the designate ID must identify the parent component followed by the subcomponent. For example, helloworldProcessor:q1.
Oracle Stream Analytics assigns a parameter to an application component after the call to the afterPropertiesSet life cycle method, but prior to the call to afterConfigurationActive life cycle method. This timing enables an application to treat an application parameter as a proper application configuration and to distinguish an application parameter from a bean property.
An ocep:binding attribute determines how Oracle Stream Analytics assigns the parameter to the application. Put the ocep:binding attribute in the OCD or in the AD. When you put it in the OCD, the meta-object is bound to an implementation object such as JMX ObjectInstance. When you put the OCD in an AD, the meta-attribute is bound to an implementation attribute scoped to the implementation object, such as JMX MBean attribute.
The following code shows the entire metatype file.
<MetaData xmlns="http://www.osgi.org/xmlns/metatype/v1.1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://www.osgi.org/xmlns/metatype/v1.1.0;
http://www.osgi.org/xmlns/metatype/v1.1.0/metatype.xsd">
<OCD name="HelloWorld Sample" id="com.oracle.cep.sample.helloworld"
description="The helloworld OEP application is a sample application
for Oracle Event Processing.">
</OCD>
<OCD name="HelloWorld Channel" id="com.oracle.cep.sample.helloworld.channel" >
<AD name="Max Threads" id="EventChannel.MaxThreads" type="Integer"
required="true" default="0" min="0" max="100"
description="Number of threads generating helloworld messages." />
<AD name="Max Size" id=".maxSize" type="Integer" required="true"
default="0" min="0" max="100" description="The maximum size of the FIFO
buffer for this channel." ocep:binding="MaxSize" />
</OCD>
<OCD name="HelloWorld Message Filtering"
id="com.oracle.cep.sample.helloworld.filter" >
<AD name="Filter" id="CQLProcessor.parameters" type="String"
description="Message filter." />
</OCD>
<Designate pid="helloworld" >
<Object ocdref="com.oracle.cep.sample.helloworld" />
</Designate>
<Designate pid="helloworldInputChannel" >
<Object ocdref="com.oracle.cep.sample.helloworld.channel" />
</Designate>
<Designate pid="helloworldProcessor.helloworldRule" >
<Object ocdref="com.oracle.cep.sample.helloworld.filter" />
</Designate>
</MetaData>
You can use parameterized applications in the following three ways:
The following example documents the com.oracle.cep.parameterizedapp application. The pid attribute of the designate element corresponds to the Bundle-SymbolicName in the MANIFEST.MF.
<OCD name="Parameterized App Testing" id="com.oracle.cep.parameterizedapp" description="The application is for parameterized app testing."> </OCD> <Designate pid="parameterizedapp"> <Object ocdref="com.oracle.cep.parameterizedapp" /> </Designate>
The following example shows how to use an OCD with ADs to configure a channel. The pid attribute of the designate element corresponds to the channel component in the EPN file.
<OCD name="Channel Configuration" id="com.oracle.cep.channel" description="The channel definition in the OCEP Application" ocep:binding="jmx:EventChannel"> <AD name="Max Threads" id=".maxThreads" type="Integer" required="true" default="0" min="0" max="100" description="Number of threads generating messages." ocep:binding="MaxThreads" /> <AD name="Max Size" id=".maxSize" type="Integer" required="true" default="0" min="0" max="100" description="The maximum size of the FIFO buffer for this channel." ocep:binding="MaxSize" /> <AD name="HEARTBEAT" id=".heartbeat" type="Long" required="false" default="5000000000" min="0" max="100000000000" description="The value for the heartbeat timeout on this channel. The default time unit is nanoseconds." ocep:binding="HeartbeatTimeout" /> </OCD> <Designate pid="helloworldInputChannel"> <Object ocdref="com.oracle.cep.channel" /> </Designate> <Designate pid="helloworldOutputChannel"> <Object ocdref="com.oracle.cep.channel" /> </Designate>
The following example shows how to configure an Oracle CQL processor query. The ADs definition correspond to query parameters 1 and 2 in the sequence.
<OCD name="Product Filter" id="com.oracle.cep.solution.product.filter"
ocep:binding="jmx:CQLProcessor" ocep:multi-valued="true">
<AD name="range" id=".range" type="Integer" required="true" min="0"
max="1000000000" default="10"
description="The range scope"
ocep:binding="Parameters" />
<AD name="field" id=".field" type="String" required="true"
default="'remainingQty'"
description="select one field you want to do range controlling"
ocep:binding="Parameters">
<Option label="remainingQty" value="remainingQty" />
<Option label="totalQty" value="totalQty" />
<Option label="price" value="price" />
</AD>
</OCD>
<Designate pid="productProcessor.productRule">
<Object ocdref="com.oracle.cep.solution.product.filter" />
</Designate>
Add a processor element to the config.xml file that defines the productProcessor, as follows. Note that the ADs definitions correspond to query parameters :1 and :2 in the sequence.
<processor>
<name>productProcessor</name>
<rules>
<query id="productRule">
<![CDATA[
IStream (select FROM productInputChannel [RANGE :1 on :2) ]]
>
</query>
</rules>
</processor>
The following example uses the EPN shell with Apache Felix Gogo to deploy the parameterized HellowWorld application. The EPN shell interfaces with OSGi Bundle Repository (OBR) and uses introspection to locate the available metadata and to form the applicable prompts to the user.
The following example shows the HelloWorld application output when it is deployed with the EPN shell.
Note:
Parametrized applications are not supported on a clustered domain. Also you can deploy only through the EPN shell. For this release, parameterized application deployment is not supported in Oracle JDeveloper or in Oracle Stream Analytics Visualizer.
./startwleves.sh -shell
Oracle CEP Shell (using Apache Felix Gogo)
shell>
shell> deployapp file:///Users/myuserid/helloworld.jar
---- HelloWorld Sample ----
The helloworld OEP application is a sample application for Oracle OEP.
Enter Y/N [default is Y] if you would like to set the parameter "Max Threads" :
-- Application parameter "Max Threads"
--Description : Number of threads generating helloworld messages.
Type: Integer
Default value: 2
Enter value for "Max Threads" or empty for default value :
Using default value of "2".
-- Application parameter "Filter"
--Description : Message filter.
Type: String
Options for parameter "Filter" are :
(0) Select all messages starting with 'Hello'
(1) Select all messages starting with 'Hi'Select option by entering number [0,1] or empty for default value :
<Jan 23, 2012 7:20:40 AM EST> <Notice> <Deployment> <BEA-2045000>
<The application bundle "helloworld" was deployed successfully>
<Jan 23, 2012 7:20:41 AM EST> <Notice> <Spring> <BEA-2047000>
<The application context for "helloworld" was started successfully>
Message: HelloWorld - the current time is:7:20:41 AM
Message: HelloWorld - the current time is:7:20:42 AM