Thank you for your feedback!This chapter describes how to use the Oracle Java Data Cartridge, an extension of Oracle Continuous Query Language (Oracle CQL) with which you can write CQL code that seamlessly interacts with Java classes in your Oracle Event Processing application.
This chapter describes the types, methods, fields, and constructors that the Oracle Java data cartridge exposes. You can use these types, methods, fields, and constructors in Oracle CQL queries and views as you would Oracle CQL native types.
This chapter includes the following sections:
For more information, see:
The Oracle Java data cartridge is a built-in Java cartridge which allows you to write Oracle CQL queries and views that seamlessly interact with the Java classes in your Oracle Event Processing application.
This section describes:
The Oracle Java data cartridge uses the cartridge ID com.oracle.cep.cartrdiges.java.
The Oracle Java data cartridge is the default Oracle Event Processing data cartridge.
For types under the default Java package name or types under the system package of java.lang, you may reference the Java type in an Oracle CQL query unqualified by package or data cartridge name:
Sign In
<query id="q1"><![CDATA[
select String(“foo”) …
]]></query>
Note:
To simplify Oracle Java data cartridge type names, you can use aliases as Section 2.7.2, "Defining Aliases Using the Aliases Element"
describes.
For more information, see:
The Oracle Java data cartridge supports the following policies for loading the Java classes that your Oracle CQL queries reference:
For more information, see:
"How to Export a Package" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.
This is the default class loading policy.
In this mode, the Oracle Java data cartridge uses the class-space of the application in scope when searching for a Java class.
This is only applicable when a type is specified only by its local name, that is, there is a single identifier, and no other identifiers are being used for its package. That is:
select String(“foo”) …
And not:
select java.lang.String(“foo”) …
In this case the procedure is as follows:
Attempt to load the class defined by the single identifier (call it ID1) using the application's class-space as usual; if this fails then:
Verify if the application defines any class within its bundle's internal class-path whose name matches ID1, independent of the package; if this fails then:
Verify if application specifies an Import-Package MANIFEST header statement which in conjunction with ID1 can be used to load a Java class.
For an example, see Section 15.1.2.4, "Class Loading Example".
This is an optional class loading policy. To use this policy, you must include the following MANIFEST header entry in your Oracle Event Processing application:
OCEP_JAVA_CARTRIDGE_CLASS_SPACE: APPLICATION_NO_AUTO_IMPORT_CLASS_SPACE
This mode is similar to the application class space policy except that Oracle Event Processing will not attempt to automatically import a package when a package is not specified.
For more information, see Section 15.1.2.1, "Application Class Space Policy".
This is an optional class loading policy. To use this policy, you must include the following MANIFEST header entry in your Oracle Event Processing application:
OCEP_JAVA_CARTRIDGE_CLASS_SPACE: SERVER_CLASS_SPACE
An Oracle CQL query can reference any exported Java class, regardless of the application or module that is exporting it.
The query can also access all classes visible to the OSGi framework's parent class-loader, which includes the runtime JDK classes.
This means that an Oracle CQL application may contain an Oracle CQL query that references classes defined by other Oracle Event Processing applications, as long as they are exported. This behavior facilitates the creation of Java-based cartridges whose sole purpose is to provide new Java libraries.
Note:
You may only reference a Java class that is part of the internal class-path of an Oracle Event Processing application if it is exported, even if a processor within this application defines the Oracle CQL query.
For an example, see Section 15.1.2.4, "Class Loading Example".
Consider the example that Figure 15-1 shows: application B1 imports package mypackage3 that application B2 exports.
Figure 15-1 Example Oracle Event Processing Applications
Table 15-1 summarizes which classes these two different applications can access depending on whether they are running in the application class space or server class space.
Table 15-1 Class Accessibility by Class Loading Policy
| Class Loading Policy | Application B1 | Application B2 |
|---|---|---|
|
Application Class Space |
|
|
|
Server Class Space |
|
|
In application B1, you can use any of the Java classes A, B, and C in your Oracle CQL queries:
select A … select B … select C …
However, in application B2, you cannot use Java classes A and B in your Oracle CQL queries. You can only use Java classes C and D:
select C … select D …
An Oracle CQL expression that accesses a Java method uses the following algorithm to resolve the method:
All parameter types are converted to Java types as Section 15.1.4, "Datatype Mapping" describes.
For example, an Oracle CQL INTEGER is converted to a Java primitive int.
Standard Java method resolution rules are applied as the Java Language Specification, Third Edition, Section 15.12, "Method Invocation Expressions" describes.
Note:
Variable arity methods are not supported. For more information, see the Java Language Specification, Third Edition, Section 12.12.2.4.
As an example, consider the following Oracle CQL expression:
attribute.methodA(10)
Where attribute is of type mypackage.MyType which defines the following overloaded methods:
methodA(int)
methodA(Integer)
methodA(Object)
methodA(long)
As the literal 10 is of the primitive type int, the order of precedence is:
methodA(int)
methodA(long)
methodA(Integer)
methodA(Object)
For more information, see Section 15.1.2, "Class Loading".
The Oracle Java data cartridge applies a fixed, asymmetrical mapping between Oracle CQL native datatypes and Java datatypes.
Table 15-2 lists the mappings between Oracle CQL native datatypes and Java datatypes.
Table 15-3 lists the mappings between Java datatypes and Oracle CQL native datatypes.
Table 15-2 Oracle Java Data Cartridge: Oracle CQL to Java Datatype Mapping
| Oracle CQL Native Datatype | Java Datatype |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Footnote 1 primitive Java datatype
Table 15-3 Oracle Java Data Cartridge: Java Datatype to Oracle CQL Mapping
| Java Datatype | Oracle CQL Native Datatype |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Footnote 1 primitive Java datatype
All other Java classes are mapped as a complex type.
For more information on these datatype mappings:
For more information on Oracle CQL native datatypes and their implicit and explicit datatype conversion, see Section 2.1, "Datatypes".
Oracle CQL datatype CHAR is mapped to java.lang.String and java.lang.String is mapped to Oracle CQL datatype CHAR. This means you can access java.lang.String member fields and methods for an attribute defined as Oracle CQL CHAR. For example, if a1 is declared as type Oracle CQL CHAR, then you can write a query like this:
<query id="q1"><![CDATA[
select a1.substring(1,2)
]]></query>
You cannot access member fields and methods on literals, even Oracle CQL CHAR literals. For example, the following query is not allowed:
<query id="q1-forbidden"><![CDATA[
select "hello".substring(1,2)
]]></query>
Java arrays are converted to Oracle CQL data cartridge arrays, and Oracle CQL data cartridge arrays are converted to Java arrays. This applies to both complex types and simple types.
You can use the data cartridge TABLE clause to access the multiple rows returned by a data cartridge function in the FROM clause of an Oracle CQL query.
For more information, see:
Typically, the Oracle Java data cartridge converts an instance that implements the java.util.Collection interface to an Oracle CQL complex type.
An Oracle CQL query can iterate through the members of the java.util.Collection.
You can use the data cartridge TABLE clause to access the multiple rows returned by a data cartridge function in the FROM clause of an Oracle CQL query.
For more information, see:
You may use Oracle Java data cartridge types in expressions within a SELECT clause and WHERE clause.
You may not use Oracle Java data cartridge types in expressions within an ORDER BY clause.
For more information, see:
This section describes common use-cases that highlight how you can use the Oracle Java data cartridge in your Oracle Event Processing applications, including:
For more information, see:
This procedure describes how to use the Oracle Java data cartridge in an Oracle Event Processing application that uses one event type defined as a tuple (Student) that has an event property type defined as a Java class (Address.java).
Implement the Address.java class as Example 15-1 shows.
Example 15-1 Address.java Class
package test;
class Address {
String street;
String state;
String city;
String [] phones;
}
In this example, assume that the Address.java class belongs to this application.
If the Address.java class belonged to another Oracle Event Processing application, it must be exported in its parent application. For more information, see Section 15.2.2, "How to Query Using Exported Java Classes".
Define the event type repository as Example 15-2 shows.
Example 15-2 Event Type Repository
<event-type-repository>
<event-type name="Student">
<properties>
<property name="name" type="char"/>
<property name="address" type="Address"/>
</properties>
</event-type>
<event-type name="Address">
<class-name>test.Address</class-name>
</event-type>
<event-type-repository>
Because the test.Address class belongs to this application, it can be declared in the event type repository. This automatically makes the class globally accessible within this application; its package does not need to be exported.
Assume that an adapter is providing Student events to channel StudentStream as Example 15-3 shows
Assume that the StudentStream is connected to a processor with the Oracle CQL query q1 that Example 15-4 shows.
<processor>
<rules>
<query id="q1"><![CDATA[
select
name,
address.street as street,
address.phones[0] as primary_phone
from
StudentStream
]]></query>
</rules>
</processor>
The Oracle Java data cartridge allows you to access the address event property from within the Oracle CQL query using normal Java API.
This procedure describes how to use the Oracle Java data cartridge in an Oracle Event Processing application that uses one event type defined as a tuple (Student) that has an event property type defined as a Java class (Address.java). In this procedure, the Address.java class belongs to a separate Oracle Event Processing application. It is exported in its parent application to make it accessible to other Oracle Event Processing applications deployed to the same Oracle Event Processing server.
Implement the Address.java class as Example 15-1 shows.
Export the test package that contains the Address.java class.
For more information, see "How to Export a Package" in the Oracle Fusion Middleware Developer's Guide for Oracle Event Processing for Eclipse.
The test package may be part of this Oracle Event Processing application or it may be part of some other Oracle Event Processing application deployed to the same Oracle Event Processing server as this application.
Define the event type repository as Example 15-2 shows.
Assume that an adapter is providing Student events to channel StudentStream as Example 15-3 shows
Assume that the StudentStream is connected to a processor with the Oracle CQL query q1 that Example 15-4 shows.
<processor>
<rules>
<query id="q1"><![CDATA[
select
name,
address.street as street,
address.phones[0] as primary_phone
from
StudentStream
]]></query>
</rules>
</processor>
The Oracle Java data cartridge allows you to access the address event property from within the Oracle CQL query using normal Java API.