An Oracle Stream Analytics EPN has two types of configuration files: assembly files and component configuration files. The assembly file is a context file that describes the EPN diagram stages and structure. The configuration file describes component configuration and the dynamic parameters of the EPN stages. Dynamic parameters are parameters that can be changed at runtime through the Oracle Stream Analytics Visualizer or programmatically through the JMX APIs.
This chapter includes the following sections:
Oracle Stream Analytics application configuration settings are stored in XML files that are based on standard schemas. When you install Oracle Stream Analytics, the XSD files for the schemas are installed in the Oracle/Middleware
/oep/xsd
directory.
By default, Oracle JDeveloper generates one assembly file named <Project-Name>.context.xml
, and one default configuration file named processor.xml.
An application can have one or more assembly files and one or more configuration files. You decide how many configuration files to use and what to name them when you build the EPN. Your project must have one configuration file named prcessor.xml
to contain the Oracle CQL processor configuration settings.
When you create components such as adapters, the processor.xml
file displays as the default configuration file in the new component wizard. If you take the default, the component configuration information is stored in the default procesor.xml
. To put all of your adapter configurations in one file named adapter.xml
, change processor.xml
to adapters.xml
in the wizard.
In the component configuration wizard, if you specify a new file name such as adapters.xml
, but use only default settings, Oracle JDeveloper does not generate the new file because there are no configuration settings to store in it. You can either create the component again with a custom setting or use the File menu to create a new empty configuration file. See Create a Component Configuration File in Getting Started with Event Processing for Oracle Stream Analytics.
The assembly and configuration files are stored in the following locations within your project:
Assembly files: <Project-Name>/META-INF/spring/*.xml
.
Configuration files: <Project-Name>/META-INF/wlevs/*.xml
.
You can modify the configuration by editing the application assembly file or by editing the component configuration file. You can edit anything you want in the files, but you have to be careful to keep the assembly file ID value consistent with the configuration file name value. If you change the ID value in the assembly file, you have to change the name value in the configuration file to match, and vice versa. You can change any other information in one file only. Oracle JDeveloper uses the ID and name value pairing to keep the information in the application assembly and component configuration files synchronized.
The following components have a configuration file that defaults to processor.xml
. Oracle CQL patterns must be placed in the processor.xml
file, but all other components in this list can use a configuration file by another name.
All adapters
Channels
Oracle CQL Patterns
Local Cache System
Cache
RMIOutbound extension
The Coherence Cache System has a default coherence-cache-
file. You can change the name of this file.
Component configuration files are deployed as part of the Oracle Stream Analytics application bundle. You can later update this configuration at runtime using Oracle Stream Analytics Visualizer, the wlevs.Admin
utility, or by manipulating the appropriate JMX MBeans.
The spring-wlevs-v12_1_3_0.xsd
schema file describes the EPN assembly file structure.
This schema file is installed in the Oracle/Middleware
/oep/xsd
directory. See EPN Assembly Schema in Schema Reference for Oracle Stream Analytics.
The EPN assembly file has a top-level root element named beans
that contains a sequence of sub-elements. Each individual sub-element contains the configuration data for an Oracle Stream Analytics component.
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:osgi="http://www.springframework.org/schema/osgi" xmlns:wlevs="http://www.bea.com/ns/wlevs/spring" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://www.springframework.org/schema/osgi http://www.springframework.org/schema/osgi/spring-osgi.xsd http://www.bea.com/ns/wlevs/spring http://www.bea.com/ns/wlevs/spring/spring-wlevs-v12_1_3_0.xsd"> <wlevs:event-type-repository> <wlevs:event-type type-name="HelloWorldEvent"> <wlevs:class>com.bea.wlevs.event.example.helloworld.HelloWorldEvent</wlevs:class> </wlevs:event-type> </wlevs:event-type-repository> <wlevs:adapter id="helloworldAdapter" class="com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapter" > <wlevs:instance-property name="message" value="HelloWorld - the current time is:"/> </wlevs:adapter> <wlevs:channel id="helloworldInputChannel" event-type="HelloWorldEvent" > <wlevs:listener ref="helloworldProcessor"/> <wlevs:source ref="helloworldAdapter"/> </wlevs:channel> <wlevs:processor id="helloworldProcessor" /> <wlevs:channel id="helloworldOutputChannel" event-type="HelloWorldEvent" advertise="true"> <wlevs:listener> <bean class="com.bea.wlevs.example.helloworld.HelloWorldBean"/> </wlevs:listener> <wlevs:source ref="helloworldProcessor"/> </wlevs:channel> </beans>
When you define a child stage within a parent stage in an EPN, the child stage is said to be nested. Only the parent stage can specify the child stage as a listener.
The following example shows the EPN assembly source in which HelloWorldBean
is nested within the helloworldOutputChannel
. Only the parent helloworldOutputChannel
may specify the nested bean as a listener.
<wlevs:adapter id="helloworldAdapter" class="com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapter" > <wlevs:instance-property name="message" value="HelloWorld - the current time is:"/> </wlevs:adapter> <wlevs:channel id="helloworldInputChannel" event-type="HelloWorldEvent" > <wlevs:listener ref="helloworldProcessor"/> <wlevs:source ref="helloworldAdapter"/> </wlevs:channel> <wlevs:processor id="helloworldProcessor" /> <wlevs:channel id="helloworldOutputChannel" event-type="HelloWorldEvent" advertise="true"> <wlevs:listener> <bean class="com.bea.wlevs.example.helloworld.HelloWorldBean"/> </wlevs:listener> <wlevs:source ref="helloworldProcessor"/> </wlevs:channel>
Alternatively, you can define this EPN so that all stages are nested as Example 2-1 shows. The helloworldAdapter
, the outermost parent stage, is the only stage accessible to other stages in the EPN.
Example 2-1 EPN Assembly File with All Stages Nested
<wlevs:adapter id="helloworldAdapter" class="com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapter" > <wlevs:instance-property name="message" value="HelloWorld - the current time is:"/> <wlevs:listener> <wlevs:channel id="helloworldInputChannel" event-type="HelloWorldEvent" > <wlevs:listener> <wlevs:processor id="helloworldProcessor"> <wlevs:listener> <wlevs:channel id="helloworldOutputChannel" event-type="HelloWorldEvent"> <wlevs:listener> <bean class="com.bea.wlevs.example.helloworld.HelloWorldBean"/> </wlevs:listener> </wlevs:channel> </wlevs:listener> </wlevs:processor> </wlevs:listener> </wlevs:channel> </wlevs:listener> </wlevs:adapter>
You can refer to a stage that is in another Oracle Stream Analytics application. A stage from another application is considered a foreign stage. You do this by id
attribute when you define both the source and target stage in the same application.
Note:
You cannot connect an Oracle CQL processor stage to a channel that is a foreign stage.
To refer to a stage you define in a different application, you use the following syntax:
FOREIGN-APPLICATION-NAME:FOREIGN-STAGE-ID
Where FOREIGN-APPLICATION-NAME
is the name of the application in which you defined the foreign stage and FOREIGN-STAGE-ID
is the id
attribute of the foreign stage.
The following example shows how the reference in application1
to the foreign stage HelloWorldBeanSource
that you define in application application2
.
<wlevs:stream id="helloworldInstream" > <wlevs:listener ref="helloworldProcessor"/> <wlevs:source ref="application2:HelloWorldBeanSource"/> </wlevs:stream>
<wlevs:event-bean id="HelloWorldBeanSource" class="com.bea.wlevs.example.helloworld.HelloWorldBeanSource" advertise="true"/>
The following stages cannot be foreign stages:
Cache
When creating Oracle Stream Analytics applications with foreign stages, you must consider foreign stage dependencies when assembling, deploying, and redeploying your application. For more information, see Reference Foreign Stages.
The wlevs_application_config.xsd
schema file describes the structure of component configuration files.
When you install Oracle Stream Analytics, XSD files such as this one are included in the directory Oracle/Middleware/oep/xsd
.
This XSD schema imports the following schemas:
wlevs_base_config.xsd
: Defines common elements that are shared between application configuration files and the server configuration file
wlevs_eventstore_config.xsd
: Defines event store-specific elements.
wlevs_diagnostic_config.xsd
: Defines diagnostic elements.
See Schema Component Configuration in Schema Reference for Oracle Stream Analytics.
The structure of application configuration files is as follows. There is a top-level root element named config
that contains a sequence of sub-elements. Each individual sub-element contains the configuration data for an Oracle Stream Analytics component (Oracle CQL processor, channel, or adapter). For example:
<?xml version="1.0" encoding="UTF-8"?> <n1:config xmlns:n1="http://www.bea.com/ns/wlevs/config/application" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <processor> <name>helloworldProcessor</name> <rules> <query id="helloworldRule"> <![CDATA[ select * from helloworldInputChannel [Now] > </query> </rules> </processor> <channel> <name>helloworldInputChannel</name> <max-size>10000</max-size> <max-threads>2</max-threads> </channel> <channel> <name>helloworldOutputChannel</name> <max-size>10000</max-size> <max-threads>2</max-threads> </channel> </n1:config>
Use the ConfigurationPropertyPlaceholderConfigurer
class to reference existing configuration file properties, in both component configuration and server configuration files, using a symbolic placeholder.
This allows you to define a value in one place and refer to that one definition rather than hard-coding the same value in many places.
You might want to do this if you want to configure Java Message Service (JMS) without hard-coding JMS information such as the factory name in the assembly file for your Oracle Stream Analytics application.
Use the com.bea.wlevs.spring.support.ConfigurationPropertyPlaceholderConfigurer
class, to create a JMS adapter and provide placeholders for the server connection factory name, user name, password, and the location to a separate file that contains the actual factory name, user name, and password values. The ConfigurationPropertyPlaceholderConfigurer
class is implemented on top of the Spring framework.
The server configuration file is used by Oracle Stream Analytics server administrators. This file contains configuration information that is specific to a domain, and is located in /Oracle/Middleware/my_oep/user_projects/domains/<domain_name>/<server_name>/config/
.
To use reference existing configuration file properties, insert a ConfigurationPropertyPlaceholderConfigurer
bean in the assembly file for your project as shown below.
<bean class="com.bea.wlevs.spring.support.ConfigurationPropertyPlaceholderConfigurer"/>
For complete details, see the com.bea.wlevs.spring.support.ConfigurationPropertyPlaceholderConfigurer
class in the Java API Reference for Oracle Stream Analytics.
Because Oracle Stream Analytics applications are low latency high-performance event-driven applications, they run on a lightweight container and are developed with a POJO-based programming model.
In POJO (Plain Old Java Object) programming, business logic is implemented in the form of POJOs, and then injected with the services they need. This is popularly called dependency injection. The injected services can range from those provided by Oracle Stream Analytics services, such as configuration management, to those provided by another Oracle product such as Oracle Kodo, to those provided by a third party.
By using Oracle Stream Analytics and standard Java annotations and deployment XML, you can configure the Oracle Stream Analytics Spring container to inject resources (such as data sources or persistence managers, and so on) into your Oracle Stream Analytics application components.
The Spring container typically injects resources during component initialization. However, it can also inject and re-inject resources at runtime and supports the use of JNDI lookups at runtime.
Oracle Stream Analytics supports the following types of resource access:
In the following sections, consider the example resource that Example 2-2 shows. This is a data source resource named StockDS
that you specify in the Oracle Stream Analytics server file.
Example 2-2 Sample Resource: Data Source StockDS
<config ...> <data-source> <name>StockDs</name> ... <driver-params> <url>jdbc:derby:</url> ... <driver-params> </data-source> ... </config>
Use the javax.annotation.Resource
(@Resource)
annotation to configure resource access at design time and the corresponding deployment XML to override this configuration at deploy time.
Static resource injection refers to the injection of resources during the initialization phase of the component life cycle. Once injected, resources are fixed, or static, while the component is active or running.
You can configure static resource injection using:
When you configure static resource injection using static resource names, the resource name you use in the @Resource
annotation or Oracle Stream Analytics assembly XML file must exactly match the name of the resource as you defined it. The resource name is static in the sense that you cannot change it without recompiling.
To configure static resource injection using static resource names at design time, you use the standard javax.annotation.Resource
annotation as shown in the example below.
To override design time configuration at deploy time, you use Oracle Stream Analytics assembly file XML.
In the following examples the resource name StockDs
exactly matches the name of the data source in the Oracle Stream Analytics server file.
< wlevs:event-bean id="simpleBean" class="...SimpleBean"/> <wlevs:resource property="dataSource" name="StockDs"/> </wlevs:event-bean>
If the name of the EventBean set method matches the name of the resource, then the @Resource
annotation name
attribute is not needed. Similarly, in this case, the wlevs:resource
element name
attribute is not needed.
import javax.annotation.Resource; public class SimpleBean implements EventBean { ... @Resource () public void setStockDs (DataSource dataSource){ this.dataSource = dataSource; } }
< wlevs:event-bean id="simpleBean" class="...SimpleBean"/> <wlevs:resource property="dataSource"/> </wlevs:event-bean>
Example 2-3 Static Resource Injection Using Static Resource Names: Annotations
import javax.annotation.Resource; public class SimpleBean implements EventBean { ... @Resource (name="StockDs") public void setDataSource (DataSource dataSource){ this.dataSource = dataSource; } }
A dynamic resource name is one that is specified as part of the dynamic or external configuration of an application. Using a dynamic resource name, the deployer or administrator can change the resource name without requiring that the application developer modify the application code or the Spring application context.
To add a dynamic resource name to a component, such as an adapter or POJO, you must first specify custom configuration for your component that contains the resource name.
<simple-bean> <name>SimpleBean</name> <trade-datasource>StockDs</trade-datasource> </simple-bean>
To configure static resource injection using dynamic resource names at design time, use the standard javax.annotation.Resource
annotation.
To override design time configuration at deploy time, you use Oracle Stream Analytics assembly file XML.
import javax.annotation.Resource; public class SimpleBean implements EventBean { ... @Resource (name="trade-datasource") public void setDataSource (DataSource dataSource){ this.dataSource = dataSource; } }
< wlevs:event-bean id="simpleBean" class="...SimpleBean"/> <wlevs:resource property="dataSource" name="trade-datasource"/> </wlevs:event-bean>
Dynamic resource injection refers to the injection of resources dynamically while the component is active in response to a dynamic configuration change using Spring container method injection.
To configure dynamic resource injection at design time, use the standard javax.annotation.Resource
annotation as Example 2-4 shows.
The component calls the getDataSource
method at runtime whenever it needs to retrieve a new instance of the resource that the resource name trade-datasource
refers to.
Typically, the component calls the getDataSource
method during the @Prepare
or @Activate
methods when dynamic configuration changes are handled.
Another strategy is to always call the getDataSource
prior to using the data source. That is, the application code does not store a reference to the data source as a field in the component.
Example 2-4 Dynamic Resource Injection: Annotations
import javax.annotations.Resource; public class SimpleBean implements EventBean { ... @Resource ("trade-datasource") public abstract DataSource getDataSource (); ... }
Oracle Stream Analytics supports the use of JNDI to look up resources dynamically.
import javax.naming.InitialContext; public class SimpleBean implements EventBean { ... public abstract void getDataSource () throws Exception { InitialContext initialContext= new InitialContext (); return initialContext.lookup ("StockDs"); } }
The JNDI name StockDs
must exactly match the name of the data source in the Oracle Stream Analytics server file.
Note:
You must disable security when starting the Oracle Stream Analytics server in order to use JNDI. Oracle does not recommend the use of JNDI for this reason.
For more information, see Administering Oracle Stream Analytics.
Oracle Stream Analytics server resolves resource names by examining the naming scopes that Table 2-1 lists.
Table 2-1 Resource Name Resolution
|
Each naming scope contains a set of unique names. The name resolution behavior is specific to a naming scope. Some naming scopes resolve names by simple matching. Other scopes resolve names by mapping the name used to do the lookup into a new name. Once a name is mapped, lookup proceeds recursively beginning with the current scope.