If your application has certain classes or packages that should only be visible within an @-annotation, you may add these to the annotation imports list. Such classes are only visible when used in an annotation and not elsewhere.

In a XML configuration file the auto-import-annotation configuration may look as below:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <auto-import-annotations import-name="com.mycompany.mypackage.myannotations.*"/>
  </common>
</esper-configuration>

Here is an example of providing annotation-only imports via the API:

Configuration config = new Configuration();
// package import, only visible for annotation use
config.getCommon().addAnnotationImport("com.mycompany.mypackage.myannotations.*");

EPL allows invocations of static Java library functions in expressions, as outlined in Section 10.1, “Single-Row Function Reference”. This configuration item can be set to allow a partial rather than a fully qualified class name in such invocations. The imports work in the same way as in Java files, so both packages and classes can be imported.

select Math.max(priceOne, PriceTwo)
// via configuration equivalent to
select java.lang.Math.max(priceOne, priceTwo)

EPL auto-imports the following Java library packages. Any additional imports that are specified in configuration files or through the API are added to the configuration in addition to the imports below.

In a XML configuration file the auto-import configuration may look as below:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <auto-import import-name="com.mycompany.mypackage.*"/>
    <auto-import import-name="com.mycompany.myapp.MyUtilityClass"/>  
  </common>
</esper-configuration>

Here is an example of providing imports via the API:

Configuration config = new Configuration();
config.getCommon().addImport("com.mycompany.mypackage.*");	// package import
config.getCommon().addImport("com.mycompany.mypackage.MyLib");   // class import

This section is relevant if you want to use regular classes to represent events.

The runtime can process event objects via the sendEventBean(Object event, String eventTypeName) method on the EPEventService interface.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="StockTick" class="com.espertech.esper.example.stockticker.event.StockTick"/>
  </common>
</esper-configuration>

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("StockTick", StockTick.class.getName());

configuration.getCommon().addEventType("StockTick", StockTick.class);

select readValue, myField from MyLegacyEvent

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyLegacyEvent" class="com.mycompany.mypackage.MyLegacyEventClass">
      <legacy-type accessor-style="public"/>
    </event-type>
  </common>
</esper-configuration>

Configuration configuration = new Configuration();
ConfigurationCommonEventTypeBean legacyDef = new ConfigurationCommonEventTypeBean();
legacyDef.setAccessorStyle(AccessorStyle.PUBLIC);
configuration.getCommon().addEventType("MyLegacyEvent", MyLegacyEventClass.class.getName(), legacyDef);

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
      <event-type name="StockTick" class="com.espertech.esper.example.stockticker.event.StockTickEvent">
        <legacy-type accessor-style="javabean" code-generation="enabled">
          <method-property name="price" accessor-method="getCurrentPrice" />
          <field-property name="volume" accessor-field="volumeField" />
       </legacy-type>
    </event-type>
  </common>
</esper-configuration>

select avg(price * volume) from StockTick

Configuration configuration = new Configuration();
ConfigurationCommonEventTypeBean legacyDef = new ConfigurationCommonEventTypeBean();
legacyDef.addMethodProperty("price", "getCurrentPrice");
legacyDef.addFieldProperty("volume", "volumeField");
configuration.getCommon().addEventType("StockTick", StockTickEvent.class.getName(), legacyDef);

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
      <event-type name="MyLegacyEvent" class="com.mycompany.package.MyLegacyEventClass">
        <legacy-type property-resolution-style="case_insensitive"/>
      </event-type>
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyLegacyEvent" class="com.mycompany.package.MyLegacyEventClass">
      <legacy-type factory-method="com.mycompany.myapp.MySampleEventFactory.createMyLegacyTypeEvent" copy-method="myCopyMethod"/>
    </event-type>
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyLegacyEvent" class="com.mycompany.package.MyLegacyEventClass">
      <legacy-type start-timestamp-property-name="startts" end-timestamp-property-name="endts"/>
    </event-type>
  </common>
</esper-configuration>

The runtime can process java.util.Map events via the sendEventMap(Map map, String eventTypeName) method on the EPEventService interface. Entries in the Map represent event properties. Please see the Appendix E, Event Representation: java.util.Map Events section for details on how to use Map events with the runtime.

You can provide an event type name for Map events.

The below snippet of XML configuration configures an event type named MyMapEvent.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyMapEvent">
      <java-util-map>
        <map-property name="carId" class="int"/>
        <map-property name="carType" class="string"/>
        <map-property name="assembly" class="com.mycompany.Assembly"/>    
      </java-util-map>
    </event-type>
  </common>
</esper-configuration>

For NEsper .NET use util-map instead of java-util-map.

This configuration defines the carId property of MyMapEvent events to be of type int, and the carType property to be of type java.util.String. The assembly property of the Map event will contain instances of com.mycompany.Assembly for the runtime to query.

The valid types for the class attribute are listed in Section 17.8, “Type Names”. In addition, any fully-qualified Java class name that can be resolved via Class.forName is allowed.

You can also use the configuration API to configure Map event types, as the short code snippet below demonstrates:

Map<String, Object> properties = new LinkedHashMap<String, Object>();
properties.put("carId", "int");
properties.put("carType", "string");
properties.put("assembly", Assembly.class.getName());

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("MyMapEvent", properties);

A Map event type may also become a subtype of one or more supertypes that must also be Map event types. The java-util-map element provides the optional attribute supertype-names that accepts a comma-separated list of names of Map event types that are supertypes to the type:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="AccountUpdate">
      <java-util-map supertype-names="BaseUpdate, AccountEvent">
      </java-util-map>
    </event-type>
  </common>
</esper-configuration>

A Map event type may declare a start and end timestamp property name. The XML shown next instructs the compiler that the startts property carries the event start timestamp and the endts property carries the event end timestamp:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="AccountUpdate">
      <java-util-map start-timestamp-property-name="startts" end-timestamp-property-name="endts">
      </java-util-map>
    </event-type>
  </common>
</esper-configuration>

For adding a type at runtime please use create map schema.

The runtime can process Object-array (Object[]) events via the sendEventObjectArray(Object[] array, String eventTypeName) method on the EPEventService interface. Elements in the Object array represent event properties. Please see the Appendix F, Event Representation: Object-Array (Object[]) Events section for details on how to use Object[] events with the runtime.

The below snippet of XML configuration configures an event type named MyObjectArrayEvent.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyObjectArrayEvent">
      <objectarray>
        <objectarray-property name="carId" class="int"/>
        <objectarray-property name="carType" class="string"/>
        <objectarray-property name="assembly" class="com.mycompany.Assembly"/>    
      </objectarray>
    </event-type>
  </common>
</esper-configuration>

This configuration defines the carId property of MyObjectArrayEvent events to be of type int and in the object array first element ([0]). The carType property to be of type java.util.String is expected in the second array element ([1]) . The assembly property of the object array event will contain instances of com.mycompany.Assembly for the runtime to query in element two ([2]).

Note that the runtime does not verify the length and property values of object array events when your application sends object-array events into the runtime. For the example above, the proper object array would look as follows: new Object[] {carId, carType, assembly}.

The valid types for the class attribute are listed in Section 17.8, “Type Names”. In addition, any fully-qualified Java class name that can be resolved via Class.forName is allowed.

You can also use the configuration API to configure Object[] event types, as the short code snippet below demonstrates:

String[] propertyNames = {"carId", "carType", "assembly"};
Object[] propertyTypes = {int.class, String.class, Assembly.class};

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("MyObjectArrayEvent", propertyNames, propertyTypes);

An Object-array event type may also become a subtype of one supertype that must also be an Object-array event type. The objectarray element provides the optional attribute supertype-names that accepts a single name of an Object-array event type that is the supertype to the type:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="AccountUpdate">
      <objectarray supertype-names="BaseUpdate">
      </objectarray>
    </event-type>
  </common>
</esper-configuration>

An Object-array event type may declare a start and end timestamp property name. The XML shown next instructs the compiler that the startts property carries the event start timestamp and the endts property carries the event end timestamp:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="AccountUpdate">
      <objectarray start-timestamp-property-name="startts" end-timestamp-property-name="endts"/>
    </event-type>
  </common>
</esper-configuration>

For adding a type at runtime please use create objectarray schema.

Please use create json schema EPL to define a JSON event type. There is no configuration API to pre-define JSON event types.

The runtime can process Avro GenericData.Record events via the sendEventAvro(GenericData.Record event, String eventTypeName) method on the EPEventService interface. Please see the Appendix H, Event Representation: Avro Events (org.apache.avro.generic.GenericData.Record) section for details on how to use Avro events with the compiler and runtime.

The below snippet of XML configuration configures an event type named MyAvroEvent.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyAvroEvent">
      <avro schema-text='{"type":"record","name":"MyAvroEvent","fields":[{"name":"carId","type":"int"},{"name":"carType","type":{"type":"string","avro.java.string":"String"}}]}'/>
    </event-type>  
  </common>
</esper-configuration>

The sample Avro schema above in pretty-print is:

{
  "type" : "record",
  "name" : "MyAvroEvent",
  "fields" : [ {
    "name" : "carId",
    "type" : "int"
  }, {
    "name" : "carType",
    "type" : {
      "type" : "string",
      "avro.java.string" : "String"
    }
  } ]
}

This schema defines:

Note that the runtime does not verify that Avro events are valid or that they actually match the schema provided for the Avro event type.

You can also use the configuration API to configure Avro event types, as the short code snippet below demonstrates:

Configuration configuration = new Configuration();
ConfigurationCommonEventTypeAvro avroType = new ConfigurationCommonEventTypeAvro();
avroType.setAvroSchema(schema);
configuration.getCommon().addEventTypeAvro("MyAvroType", avroType);

For adding a type at runtime please use create avro schema.

An Avro event type may also become a subtype of one supertype that must also be an Avro event type. The avro element provides the optional attribute supertype-names that accepts a single name of an Avro event type that is the supertype to the type:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyAvroEvent">
      <avro supertype-names="BaseUpdate"/>
    </event-type>  
  </common>
</esper-configuration>

An Avro event type may declare a start and end timestamp property name. The XML shown next instructs the compiler that the startts property carries the event start timestamp and the endts property carries the event end timestamp:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyAvroEvent">
      <avro start-timestamp-property-name="startts" end-timestamp-property-name="endts"/>
    </event-type>  
  </common>
</esper-configuration>

Via this configuration item, or using create xml schema, the runtime can natively process org.w3c.dom.Node instances, i.e. XML document object model (DOM) nodes. Please see the Appendix I, Event Representation: org.w3c.dom.Node XML Events section for details on how to use Node events with the compiler and runtime.

EPL allows configuring XPath expressions as event properties. You can specify arbitrary XPath functions or expressions and provide a property name by which their result values will be available for use in expressions. Use the @XMLSchemaField annotation with create xml schema.

For XML documents that follow a XML schema, the compiler and runtime can load and interrogate your schema and validate event property names and types against the schema information.

Nested, mapped and indexed event properties are also supported in expressions against org.w3c.dom.Node events. Thus XML trees can conveniently be interrogated using the existing event property syntax for querying JavaBean objects, JavaBean object graphs or java.util.Map events.

In the simplest form, the compiler only requires a configuration entry containing the root element name and the event type name in order to process org.w3c.dom.Node events:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="MyXMLNodeEvent">
      <xml-dom root-element-name="myevent" />
    </event-type>
  </common>
</esper-configuration>

You can also use the configuration API to configure XML event types, as the short example below demonstrates. In fact, all configuration options available through XML configuration can also be provided via setter methods on the ConfigurationEventTypeXMLDOM class.

Configuration configuration = new Configuration();
ConfigurationCommonEventTypeXMLDOM desc = new ConfigurationCommonEventTypeXMLDOM();
desc.setRootElementName("myevent");
desc.addXPathProperty("name1", "/element/@attribute", XPathConstants.STRING);
desc.addXPathProperty("name2", "/element/subelement", XPathConstants.NUMBER);
configuration.getCommon().addEventType("MyXMLNodeEvent", desc);

The equivalent to above configuration is declaring the schema via create xml schema:

@XMLSchema(rootElementName='myevent')
@XMLSchemaField(name='name1', xpath='/element/@attribute', type='string')
@XMLSchemaField(name='name2', xpath='/element/subelement', type='number')
create xml schema MyXMLNodeEvent()

The next example presents configuration options in a sample configuration entry.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type name="AutoIdRFIDEvent">
      <xml-dom root-element-name="Sensor" schema-resource="data/AutoIdPmlCore.xsd" 
         default-namespace="urn:autoid:specification:interchange:PMLCore:xml:schema:1">
        <namespace-prefix prefix="pmlcore" 
           namespace="urn:autoid:specification:interchange:PMLCore:xml:schema:1"/>
        <xpath-property property-name="countTags" 
           xpath="count(/pmlcore:Sensor/pmlcore:Observation/pmlcore:Tag)" type="number"/>
      </xml-dom>
    </event-type>
  </common>
</esper-configuration>

The equivalent to above configuration is declaring the schema via create xml schema:

@XMLSchema(rootElementName='Sensor' schemaResource='data/AutoIdPmlCore.xsd', 
  defaultNamespace='urn:autoid:specification:interchange:PMLCore:xml:schema:1')
@XMLSchemaNamespacePrefix(prefix='pmlcore', namespace='urn:autoid:specification:interchange:PMLCore:xml:schema:1')" +
@XMLSchemaField(name='countTags', xpath='count(/pmlcore:Sensor/pmlcore:Observation/pmlcore:Tag)', type='number')
create xml schema AutoIdRFIDEvent()

This example configures an event property named countTags whose value is computed by an XPath expression. The namespace prefixes and default namespace are for use with XPath expressions and must also be made known to the compiler and runtime in order for the compiler/runtime to compile XPath expressions. Via the schema-resource attribute you can instruct the compiler/runtime to load a schema file. You may also use schema-text instead to provide the actual text of the schema.

desc.addXPathProperty("name", "/element/sub", XPathConstants.STRING, "long");

@XMLSchemaField(name='name', xpath='/element/sub', type='string', castToType='long')

<xpath-property property-name="name"  xpath="/element/sub" type="string" cast="long"/>

select request, request.symbol from GetQuote

Configuration configuration = new Configuration();
ConfigurationCommonEventTypeXMLDOM desc = new ConfigurationCommonEventTypeXMLDOM();
desc.setRootElementName("GetQuote");
desc.setDefaultNamespace("http://services.samples/xsd");
desc.setRootElementNamespace("http://services.samples/xsd");
desc.addNamespacePrefix("m0", "http://services.samples/xsd");
desc.setXPathResolvePropertiesAbsolute(false);
configuration.getCommon().addEventType("GetQuote", desc);

@XMLSchema(rootElementName = 'GetQuote', defaultNamespace='http://services.samples/xsd',
  rootElementNamespace='http://services.samples/xsd', xpathResolvePropertiesAbsolute=false)
@XMLSchemaNamespacePrefix(prefix='m0', namespace='http://services.samples/xsd')
create xml schema GetQuote()

ConfigurationCommonEventTypeXMLDOM desc = new ConfigurationCommonEventTypeXMLDOM();
desc.setXPathFunctionResolver(MyXPathFunctionResolver.class.getName());
desc.setXPathVariableResolver(MyXPathVariableResolver.class.getName());

@XMLSchema(xpathFunctionResolver='class name here', xpathVariableResolver='class name here')

ConfigurationCommonEventTypeXMLDOM desc = new ConfigurationCommonEventTypeXMLDOM();
desc.setAutoFragment(false);

@XMLSchema(autoFragment=false

ConfigurationCommonEventTypeXMLDOM desc = new ConfigurationCommonEventTypeXMLDOM();
desc.setXPathPropertyExpr(true);

@XMLSchema(xpathPpropertyExpr=true

ConfigurationCommonEventTypeXMLDOM desc = new ConfigurationCommonEventTypeXMLDOM();
desc.setEventSenderValidatesRoot(false);

@XMLSchema(eventSenderValidatesRoot=false

ConfigurationCommonEventTypeXMLDOM desc = new ConfigurationCommonEventTypeXMLDOM();
desc.setStartTimestampPropertyName("startts");
desc.setEndTimestampPropertyName("endts");

Via this configuration an application can make the Java package or packages that contain an application's Java event classes known. Thereby an application can use create schema name as simple-classname and the compiler can find the class.

The XML configuration for defining the Java packages that contain Java event classes is:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <event-type-auto-name package-name="com.mycompany.order.event"/>
  </common>
</esper-configuration>

The same configuration but using the Configuration class:

Configuration config = new Configuration();
config.getCommon().addEventTypeAutoName("com.mycompany.order.event");
// ... or ...
config.getCommon().addEventTypeAutoName(MyEvent.getPackage().getName());

Method invocations are allowed in the from clause in EPL, such that your application may join event streams to the data returned by a web service, or to data read from a distributed cache or object-oriented database, or obtain data by other means. A local cache may be placed in front of such method invocations through the configuration settings described herein.

The LRU cache is described in detail in Section 17.4.12.6.1, “LRU Cache”. The expiry-time cache documentation can be found in Section 17.4.12.6.2, “Expiry-Time Cache”

The next XML snippet is a sample cache configuration that applies to methods provided by the classes 'MyFromClauseLookupLib' and 'MyFromClauseWebServiceLib'. The XML and API configuration understand both the fully-qualified Java class name, as well as the simple class name:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <method-reference class-name="com.mycompany.MyFromClauseLookupLib">
      <expiry-time-cache max-age-seconds="10" purge-interval-seconds="10" ref-type="weak"/>
    </method-reference> 	
    <method-reference class-name="MyFromClauseWebServiceLib">
      <lru-cache size="1000"/>
    </method-reference>
  </common>
</esper-configuration>

For NEsper .NET also see Section J.17, “.NET Configurations - Relational Database Access”.

EPL has the capability to join event streams against historical data sources, such as a relational database. This section describes the configuration entries that the compiler or runtime require to access data stored in your database. Please see Section 5.13, “Accessing Relational Data via SQL” for information on the use of EPL queries that include historical data sources.

EPL queries that poll data from a relational database specify the name of the database as part of the statement. The compiler and runtime use the configuration information described here to resolve the database name in the statement to database settings. The required and optional database settings are summarized below.

Some of the settings can have important performance implications that need to be carefully considered in relationship to your database software, JDBC driver and runtime environment. This section attempts to outline such implications where appropriate.

The sample XML configuration file in the "etc" folder can be used as a template for configuring database settings. All settings are also available by means of the configuration API through the classes Configuration and ConfigurationDBRef.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb1">
      <datasource-connection context-lookup-name="java:comp/env/jdbc/mydb">
        <env-property name="java.naming.factory.initial" value ="com.myclass.CtxFactory"/>
        <env-property name="java.naming.provider.url" value ="iiop://localhost:1050"/>
      </datasource-connection>
    </database-reference>
  </common>
</esper-configuration>

if (envProperties.size() > 0) {
  initialContext = new InitialContext(envProperties);
}
else {
  initialContext = new InitialContext();
}
DataSource dataSource = (DataSource) initialContext.lookup(lookupName);
Connection connection = dataSource.getConnection();

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb3">
      <!-- For a complete list of properties see Apache DBCP. -->
      <!-- NOTE: "dbcp2" applies to api-2.0 of DBCP, use "dbcp" otherwise. -->
      <datasourcefactory-connection class-name="org.apache.commons.dbcp2.BasicDataSourceFactory">	
        <env-property name="username" value ="myusername"/>
        <env-property name="password" value ="mypassword"/>
        <env-property name="driverClassName" value ="com.mysql.jdbc.Driver"/>
        <env-property name="url" value ="jdbc:mysql://localhost/test"/>
        <env-property name="initialSize" value ="2"/>
        <env-property name="validationQuery" value ="select 1 from dual"/>
      </datasourcefactory-connection>
      <connection-lifecycle value="pooled"/>
    </database-reference>
  </common>
</esper-configuration>

Properties props = new Properties();
props.put("username", "myusername");
props.put("password", "mypassword");
props.put("driverClassName", "com.mysql.jdbc.Driver");
props.put("url", "jdbc:mysql://localhost/test");
props.put("initialSize", 2);
props.put("validationQuery", "select 1 from dual");

ConfigurationCommonDBRef configDB = new ConfigurationCommonDBRef();
// BasicDataSourceFactory is an Apache DBCP import
configDB.setDataSourceFactory(props, BasicDataSourceFactory.class.getName());
configDB.setConnectionLifecycleEnum(ConfigurationCommonDBRef.ConnectionLifecycleEnum.POOLED);

Configuration configuration = new Configuration();;
configuration.getCommon().addDatabaseReference("mydb3", configDB);

configDB.setDataSourceFactory(props, MyOwnDataSourceFactory.class.getName());
...
class MyOwnDataSourceFactory {
  public static DataSource createDataSource(Properties properties) {
    return new MyDataSourceImpl(properties);
  }
}

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb2">
      <drivermanager-connection class-name="my.sql.Driver" 
            url="jdbc:mysql://localhost/test?user=root&amp;password=mypassword" 
            user="myuser" password="mypassword">
        <connection-arg name="user" value ="myuser"/>
        <connection-arg name="password" value ="mypassword"/>
        <connection-arg name="somearg" value ="someargvalue"/>
      </drivermanager-connection>
    </database-reference>
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb2">
    <!-- ... configure data source or driver manager settings... -->
      <connection-settings auto-commit="true" catalog="mycatalog" 
          read-only="true" transaction-isolation="1" />
    </database-reference>
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb2">
    <!-- ... configure data source or driver manager settings... -->
        <connection-lifecycle value="pooled"/>
    </database-reference>
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb">
    <!-- ... configure data source or driver manager settings... -->
      <lru-cache size="1000"/>
    </database-reference>  
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb">
    <!-- ... configure data source or driver manager settings... -->
        <expiry-time-cache max-age-seconds="60" purge-interval-seconds="120" />
    </database-reference>
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb">
    <!-- ... configure data source or driver manager settings... -->
        <expiry-time-cache max-age-seconds="60" purge-interval-seconds="120" ref-type="hard"/>
    </database-reference>
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb">
    <!-- ... configure data source or driver manager settings... -->
      <column-change-case value="lowercase"/>
    </database-reference>
  </common>
</esper-configuration>

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <database-reference name="mydb">
    <!-- ... configure data source or driver manager settings... -->
      <sql-types-mapping sql-type="2" java-type="int" />
    </database-reference>
  </common>
</esper-configuration>

Variables can be created dynamically in EPL via the create variable syntax but can also be configured.

A variable is declared by specifying a variable name, the variable type, an optional initialization value and an optional boolean-type flag indicating whether the variable is a constant (false by default). The initialization value can be of the same or compatible type as the variable type, or can also be a String value that, when parsed, is compatible to the type declared for the variable. Declare each variable a constant to achieve the best performance.

In a XML configuration file the variable configuration may look as below.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <variable name="var_threshold" type="long" initialization-value="100"/>
    <variable name="var_key" type="string"/>
    <variable name="test" type="int" constant="true"/>  
  </common>
</esper-configuration>

Please find the list of valid values for the type attribute in Section 17.8, “Type Names”.

A variant stream is a predefined stream into which events of multiple disparate event types can be inserted, and which can be selected from in patterns and the from clause.

The name of the variant stream and, optionally, the type of events that the stream may accept, are part of the stream definition. By default, the variant stream accepts only the predefined event types. The compiler validates your insert into clause which inserts into the variant stream against the predefined types.

A variant stream can be set to accept any type of event, in which case all properties of the variant stream are effectively dynamic properties. Set the type variance flag to ANY to indicate the variant stream accepts any type of event.

The following XML configuration defines a variant stream by name OrderStream that carries only PartsOrder and ServiceOrder events:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <common>
    <variant-stream name="OrderStream">
      <variant-event-type name="PartsOrder"/>
      <variant-event-type name="ServiceOrder"/>
    </variant-stream>
  </common>
</esper-configuration>

This code snippet sets up a variant stream by name OutgoingEvent:

Configuration config = new Configuration();
ConfigurationCommonVariantStream variant = new ConfigurationCommonVariantStream();
variant.setTypeVariance(ConfigurationCommonVariantStream.TypeVariance.ANY);
config.getCommon().addVariantStream("OutgoingEvent", variant);

If specifying variant event type names, make sure such names have been configured for JavaBean, Map or XML events.

Locale-dependence in the compiler can be present in the sort order of string values by the order by clause and by the sort window.

By default, the runtime sorts string values using the compare method that is not locale dependent. To enable local dependent sorting you must set the configuration flag as described below.

The XML configuration sets the locale dependent sorting as shown below:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <compiler>
    <language sort-using-collator="true"/>
  </compiler>
</esper-configuration>

The API to change the setting:

Configuration config = new Configuration();
config.getCompiler().getLanguage().setSortUsingCollator(true);

You may configure a default script dialect as described herein. The default script dialect is js which stands for JavaScript, since most JVM ship with an integrated JavaScript execution runtime.

The default value for the enabled setting is true thus the compiler allows scripts. By setting enabled to false the compiler disallows script use entirely.

A sample XML configuration for this setting is shown below:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <compiler>
    <scripts default-dialect="js" enabled="true"/>
  </compiler>
</esper-configuration>

A sample code snippet that sets a new script dialect is:

Configuration config = new Configuration();
config.getCompiler().getScripts().setDefaultDialect("js");
config.getCompiler().getScripts().setEnabled(true);

The settings related to serializers and deserializers (serdes) are only relevant when using high-availability with EsperHA. These settings are not relevant when not using EsperHA. Please see the EsperHA documentation for information.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <compiler>
    <serde-settings/>
  </compiler>
</esper-configuration>

Please set the flag as described herein to have the runtime report key counters and other processing information through the JMX mbean platform server. By default JMX is not enabled. For NEsper .NET this section does not apply and there is currently no equivalent.

A sample XML configuration is shown below:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <runtime>
    <metrics-reporting jmx-runtime-metrics="true"/>
  </runtime>
</esper-configuration>

A sample code snippet to set this configuration via the API follows:

Configuration configuration = new Configuration();
configuration.getRuntime().getMetricsReporting().setJmxRuntimeMetrics(true);

This section explains how to enable and configure metrics reporting, which is by default disabled. Please see Section 16.12, “Runtime and Statement Metrics Reporting” for more information on the metrics data reported to your application.

The flag that enables metrics reporting is global to a Java virtual machine. If metrics reporting is enabled, the overhead incurred for reporting metrics is carried by all runtime instances per Java VM.

Metrics reporting occurs by a runtime-controlled separate daemon thread that each runtime instance starts at runtime initialization time, if metrics reporting and threading is enabled (threading enabled is the default).

Runtime and statement metric intervals are in milliseconds. A negative or zero millisecond interval value may be provided to disable reporting.

To control statement metric reporting for individual statements or groups of statements, the runtime provides a facility that groups statements by statement name. Each such statement group may have different reporting intervals configured, and intervals can be changed at runtime through runtime configuration. A statement group is assigned a group name at configuration time to identify the group.

Metrics reporting configuration is part of the runtime settings. All configuration options are also available via the Configuration API.

A sample XML configuration is shown below:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <runtime>
    <metrics-reporting enabled="true" runtime-interval="1000" statement-interval="1000" 
        threading="true"/>
  </runtime>
</esper-configuration>

The runtime-interval setting (defaults to 10 seconds) determines the frequency in milliseconds at which the runtime reports runtime metrics, in this example every 1 second. The statement-interval is for statement metrics. The threading flag is true by default since reporting takes place by a dedicated runtime thread and can be set to false to use the external or internal timer thread instead.

The next example XML declares a statement group: The statements that have statement names that fall within the group follow a different reporting frequency:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <runtime>
    <metrics-reporting enabled="true" statement-interval="0">
      <stmtgroup name="MyStmtGroup" interval="2000" default-include="true" num-stmts="100" 
           report-inactive="true">
        <exclude-regex>.*test.*</exclude-regex>
      </stmtgroup>
    </metrics-reporting>
  </runtime>
</esper-configuration>

The above example configuration sets the statement-interval to zero to disable reporting for all statements. It defines a statement group by name MyStmtGroup and specifies a 2-second interval. The example sets the default-include flag to true (by default false) to include all statements in the statement group. The example also sets report-inactive to true (by default false) to report inactive statements.

The exclude-regex element may be used to specify a regular expression that serves to exclude statements from the group. Any statement whose statement name matches the exclude regular expression is not included in the group. In the above example, all statements with the characters 'test' inside their statement name are excluded from the group.

Any statement not belonging to any of the statement groups follow the configured statement interval.

There are additional elements available to include and exclude statements: include-regex, include-like and exclude-like. The latter two apply SQL-like matching. All patterns are case-sensitive.

Here is a further example of a possible statement group definition, which includes statements whose statement name have the characters @REPORT or @STREAM, and excludes statements whose statement name have the characters @IGNORE or @METRICS inside.

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <runtime>
    <metrics-reporting enabled="true">
      <stmtgroup name="MyStmtGroup" interval="1000">
        <include-like>%@REPORT%</include-like>
        <include-regex>.*@STREAM.*</include-regex>
        <exclude-like>%@IGNORE%</exclude-like>
        <exclude-regex>.*@METRICS.*</exclude-regex>
      </stmtgroup>
    </metrics-reporting>
  </runtime>
</esper-configuration>

Use the settings as described here to register an exception handler factory class that provides an exception handler. The runtime invokes exception handlers in the order they are listed to handle a continues-query unchecked exception, as further described in Section 16.10, “Exception Handling”. Please provide the full-qualified class name of each class that implements the com.espertech.esper.common.client.hook.exception.ExceptionHandlerFactory interface in the runtime configuration as below.

By default, during a module undeploy when the runtime encounters a runtime exception for any of the statements it logs such exceptions as warnings. You can set the undeploy-rethrow-policy flag to rethrow_first instead have the runtime rethrow the first runtime exception.

The XML configuration is as follows:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <runtime>
    <exceptionHandling undeploy-rethrow-policy="warn">
      <handlerFactory class="my.company.cep.MyCEPRuntimeExceptionHandlerFactory"/>
    </exceptionHandling>
  </runtime>
</esper-configuration>

The API calls to register an exception handler factory are as follows:

Configuration config = new Configuration();
config.getRuntime().getExceptionHandling().addClass(MyCEPRuntimeExceptionHandlerFactory.class);
config.getRuntime().getExceptionHandling().setUndeployRethrowPolicy(UndeployRethrowPolicy.RETHROW_FIRST);

For reference, we include the default exception handling code here:

if (exceptionHandlers.isEmpty()) {
  StringWriter writer = new StringWriter();
  if (type == ExceptionHandlerExceptionType.PROCESS) {
    writer.append("Exception encountered processing ");
  } else {
    writer.append("Exception encountered performing instance stop for ");
  }
  writer.append("deployment-id '");
  writer.append(deploymentId);
  writer.append("' ");
  writer.append("statement '");
  writer.append(statementName);
  writer.append("'");
  if (optionalEPL != null) {
    writer.append(" expression '");
    writer.append(optionalEPL);
    writer.append("'");
  }
  writer.append(" : ");
  writer.append(t.getMessage());
  String message = writer.toString();

  if (type == ExceptionHandlerExceptionType.PROCESS) {
    log.error(message, t);
  } else {
    log.warn(message, t);
  }
  return;
}

ExceptionHandlerContext context = new ExceptionHandlerContext(runtimeURI, t, deploymentId, statementName, optionalEPL, type, optionalCurrentEvent);
for (ExceptionHandler handler : exceptionHandlers) {
  handler.handle(context);
}

Use the settings as described here to register a condition handler factory class that provides a condition handler. The runtime invokes condition handlers in the order they are listed to indicate conditions, which is the term used for notification when certain predefined limits are reached, as further described in Section 16.11, “Condition Handling”.

Please provide the full-qualified class name of each class that implements the com.espertech.esper.common.client.hook.condition.ConditionHandlerFactory interface in the runtime configuration as below.

The XML configuration is as follows:

<esper-configuration xmlns="http://www.espertech.com/schema/esper">
  <runtime>
    <conditionHandling>
      <handlerFactory class="my.company.cep.MyCEPRuntimeConditionHandlerFactory"/>
    </conditionHandling>
  </runtime>
</esper-configuration>

The API calls to register a condition handler factory are as follows:

Configuration config = new Configuration();
config.getRuntime().getConditionHandling().addClass(MyCEPRuntimeConditionHandlerFactory.class);

Assuming your application has a service myLocalService instance, the example code is:

Configuration configuration = new Configuration();
HashMap<String, Object> transients = new HashMap<String, Object>();
transients.put(SERVICE_NAME, myLocalService); // SERVICE_NAME is a well-known string value defined elsewhere
configuration.getCommon().setTransientConfiguration(transients);

EPRuntime runtime = EPRuntimeProvider.getDefaultRuntime(configuration);

A sample listener that receives a service from transient configuation is:

public class MyListener implements UpdateListener {
  public void update(EventBean[] newEvents, EventBean[] oldEvents, EPStatement statement, EPRuntime runtime) {
    MyLocalService service = (MyLocalService) runtime.getConfigurationTransient().get(SERVICE_NAME);
    // use the service here
  }
}

An alternative means to obtain application services is to define a constant variable.

By default, when resolving a fully-qualified class name to a Class, the com.espertech.esper.common.client.util.ClassForNameProviderDefault uses:

ClassLoader cl = Thread.currentThread().getContextClassLoader();
return Class.forName(className, true, cl);

Your application can implement the com.espertech.esper.common.client.util.ClassForNameProvider interface to provide an alternate implementation.

For example, this provider prevents the System class from being available in EPL:

runtime.getConfigurationTransient().put(ClassForNameProvider.NAME,
  new ClassForNameProvider() {
    public Class classForName(String className) throws ClassNotFoundException {
      if (className.equals(System.class.getName())) { // prevent the System class from loading
        return null;
      }
      return Class.forName(className, true, Thread.currentThread().getContextClassLoader());
   }
});

By default, to obtain a class loader, the com.espertech.esper.common.client.util.ClassLoaderProviderDefault uses Thread.currentThread().getContextClassLoader().

Your application can implement the com.espertech.esper.common.client.util.ClassLoaderProvider interface to provide an alternate implementation.

For example, this provider returns a pre-determined classloader:

ClassLoader classLoader = new CustomClassLoader();
runtime.getConfigurationTransient().put(ClassLoaderProvider.NAME,
  new ClassLoaderProvider() {
    public ClassLoader classloader() {
      return classLoader;
    }
});

Log4j is the default logging component. Please find additional information for Log4j configuration and extension in http://logging.apache.org/log4j.

The easiest way to configure Log4j is by providing a Log4J configuration file, similar to the log4j.xml file shipped in the etc folder of the distribution.

Add the log4j.configuration system property to the java command line and provide the file name of the Log4j configuration file, making sure your classpath also includes the directory of the file:

java -Dlog4j.configuration=log4j.xml ...