15 Oracle Java Data Cartridge

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 describes:

For more information, see:

15.1 Understanding the Oracle Java Data Cartridge

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 CEP application.

This section describes:

15.1.1 Data Cartridge Name

The Oracle Java data cartridge uses the cartridge ID com.oracle.cep.cartrdiges.java.

The Oracle Java data cartridge is the default Oracle CEP 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:

<query id="q1"><![CDATA[
    select String(“foo”) …
]]></query>

Note:

To simplify Oracle Java data cartridge type names, you can use aliases as Section 2.8.2, "Defining Aliases Using the Aliases Element" describes.

For more information, see:

15.1.2 Class Loading

The Oracle Java data cartridge supports the following policies for loading the Java classes that your Oracle CQL queries reference:

For more information, see:

15.1.2.1 Application Class Space Policy

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".

15.1.2.2 No Automatic Import 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 CEP 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 CEP 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".

15.1.2.3 Server 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 CEP application:

OCEP_JAVA_CARTRIDGE_CLASS_SPACE: SERVER_CLASS_SPACE

In this mode, Oracle CEP still uses the application's class-space, but Oracle CEP will not attempt to automatically import a package when a package is not specified.

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 CEP 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 CEP 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".

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 CEP Applications

Description of Figure 15-1 follows
Description of "Figure 15-1 Example Oracle CEP 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

  • package1.A

  • privatepackage1.B

  • package2.C

  • package2.C

  • privatepackage2.D

Server Class Space

  • package2.C

  • package2.C


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 …

15.1.3 Method Resolution

An Oracle CQL expression that accesses a Java method uses the following algorithm to resolve the method:

  1. 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.

  2. 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".

15.1.4 Datatype Mapping

The Oracle Java data cartridge applies a fixed, asymetrical 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

BIGINT

longFoot 1 

BOOLEAN

booleanFootref 1

BYTE

byte[]Footref 1

CHAR

java.lang.String

DOUBLE

doubleFootref 1

FLOAT

floatFootref 1

INTEGER

intFootref 1

INTERVAL

longFootref 1

XMLTYPE

java.lang.String


Footnote 1 primitive Java datatype

Table 15-3 Oracle Java Data Cartridge: Java Datatype to Oracle CQL Mapping

Java Datatype Oracle CQL Native Datatype

longFoot 1 

BIGINT

booleanFootref 1

BOOLEAN

byte[]Footref 1

BYTE

java.lang.String

CHAR

doubleFootref 1

DOUBLE

floatFootref 1

FLOAT

intFootref 1

INTEGER

java.sql.Date

java.sql.Timestamp

INTERVAL

java.sql.SQLXML

XMLTYPE


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.2, "Datatypes".

15.1.4.1 Java Datatype String and Oracle CQL Datatype CHAR

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>

15.1.4.2 Literals

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>

15.1.4.3 Arrays

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:

15.1.4.4 Collections

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:

15.1.5 Oracle CQL Query Support for the Oracle Java Data Cartridge

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:

15.2 Using the Oracle Java Data Cartridge

This section describes common use-cases that highlight how you can use the Oracle Java data cartridge in your Oracle CEP applications, including:

For more information, see:

15.2.1 How to Query Using the Java API

This procedure describes how to use the Oracle Java data cartridge in an Oracle CEP application that uses one event type defined as a tuple (Student) that has an event property type defined as a Java class (Address.java).

To query with Java classes:

  1. 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 CEP application, it must be exported in its parent application. For more information, see Section 15.2.2, "How to Query Using Exported Java Classes".

  2. 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.

  3. Assume that an adapter is providing Student events to channel StudentStream as Example 15-3 shows

    Example 15-3 Channel

    <channel id="StudentStream" event-type="Student"/>
    
  4. Assume that the StudentStream is connected to a processor with the Oracle CQL query q1 that Example 15-4 shows.

    Example 15-4 Oracle CQL Query

    <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.

15.2.2 How to Query Using Exported Java Classes

This procedure describes how to use the Oracle Java data cartridge in an Oracle CEP 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 CEP application. It is exported in its parent application to make it accessible to other Oracle CEP applications deployed to the same Oracle CEP server.

To query with Java classes:

  1. Implement the Address.java class as Example 15-1 shows.

    Example 15-5 Address.java Class

    package test;
    
    class Address {
        String street;
        String state;
        String city;
        String [] phones;
    }
    
  2. Export the test package that contains the Address.java class.

    For more information, see "How to Export a Package" in the Oracle Complex Event Processing Developer's Guide for Eclipse.

    The test package may be part of this Oracle CEP application or it may be part of some other Oracle CEP application deployed to the same Oracle CEP server as this application.

  3. Define the event type repository as Example 15-2 shows.

    Example 15-6 Event Type Repository

    <event-type-repository>
        <event-type name="Student">
            <property name="name" type="char"/>
            <property name="address" type="Address"/>
        </event-type>
    <event-type-repository>
    
  4. Assume that an adapter is providing Student events to channel StudentStream as Example 15-3 shows

    Example 15-7 Channel

    <channel id="StudentStream" event-type="Student"/>
    
  5. Assume that the StudentStream is connected to a processor with the Oracle CQL query q1 that Example 15-4 shows.

    Example 15-8 Oracle CQL Query

    <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.