Creating Event Types for Adapters

This topic provides guidelines for creating event types for developing adapters.

Event types are used in the following stages of development:

1. Writing a typed adapter. A typed adapter uses the event type as a generic parameter so that the proper structure is initialized when creating new event objects to be enqueued.

2. Writing a query template. A query template is specified in LINQ on top of a CepStream object, whose definition is based on an event type.

For more general information about events, see Event Structure.

Determine the Event Structure

When the event payload (that is, the number of fields in the payload and their types) is fixed and known in advance, you can create a typed adapter. With a typed adapter, all instances of the adapter produce the same fixed payload format. This is typically the case for event sources with a fixed data structure.

When you create a typed adapter, you define a .NET class or struct that represents the fixed payload, or use a primitive type if your event payload can be represented by a single field. When using structs or classes, you can use only public fields and properties as payload fields. Private fields and properties, and class methods are ignored and cannot be used in the event type. You use this event type declaration to populate the event type in the input adapter and to obtain the result from the typed event type in the output adapter. The following example defines a simple event type that has two payload fields, V1 and V2, of type int.

public class MyPayload  
{  
    public int V1 { get; set; }  
    public int V2 { get; set; }  
}  

Another example shows how to use a nested event type:

public class ComplexPayload  
{  
    public ValueType Value { get; set; }  
    public bool Status  { get; set; }  
}  
  
public class ValueType  
{  
    public double Value { get; set; }  
    public int Quality  { get; set; }  
}  

An untyped adapter is useful when you want the same adapter for a specific source or sink to be configurable so that it can handle multiple event types. The event payload format for these event types is provided to the adapter as part of a configuration specification when the adapter is bound to the query. An example of such a scenario is a .csv file that contains a varying number of fields. The exact set of fields that make up a payload might be determined by the query designer (and not the developer who is building the adapter) only at the time of binding and instantiating the query. Another example is an adapter for SQL tables, where the type of the events that are produced depends on the schema of the table or the query issued against the table. For more information, see Creating Input and Output Adapters.

The specification of a query template is based on a CepStream object with a specific event type, that has to be known at design time. Intermediate CepStream objects along the query template specification can contain new types that are implicitly defined in project clauses ("select" in LINQ), using member init expressions.

Payload Field Requirements

Event types in the StreamInsight server are an ordered list of fields instead of .NET structs, which do not impose an order on its fields. The order of event fields becomes important for untyped adapters. These adapters access fields by ordinal because the fields are not known at adapter design time. As a default convention, a .NET struct, which is used as an event type, orders its fields according to the lexicographic order of their names.

Discoverability of Event Types

Once an event type has been created, the next step is to ensure its discoverability by dependent projects. Note that the .NET environment provides developers with the ability to build modules in a loosely coupled, distributed manner and ship them as assemblies. These assemblies can then be put together to build an integrated application, tested, and deployed to production.

Recall that a runnable StreamInsight query is the result of successfully binding a query template with instances of input and output adapters, based on matching event types at the input and output of the query. Depending on the development environment, you may need to provide access to the event type to others. For example, the adapter developer and the query developer may have to work on their respective modules independently. Consider the following scenarios for event type discoverability:

• If the adapter developer is the publisher of the event type, the adapter developer can write the adapter using the StreamInsight managed API and ship the .NET assembly. Other developers can reflect on the .NET assembly by using ildasm.exe or by referencing the DLL from inside the Visual Studio project and determine the event type. Using this method, access to the StreamInsight server is not required to access the event type.

• If the StreamInsight server administrator is the publisher of the event type, the administrator or developer can deploy the event type in the StreamInsight server. A query developer who has access to the StreamInsight server can then use the applicable object model API calls to inspect metadata items and determine the event type. The adapter developer can also write a typed adapter that supports this event type.

• If the adapter developer and the query developer are actually disconnected -(each working with his or her own representation of a common event type), the validation of a match between their respective event types will occur at query bind time. The bind will be successful if there is a match.

• If the query developer has no access to the adapter assembly or the StreamInsight server in which the adapter is registered, the developer can determine the event type by referring to the product literature for the adapter, or through common knowledge of data transfer protocols specific to that domain (for example, Financial Information Exchange (FIX) or Reuters Market Data System (RMDS) in financial trading).

Supported Data Types

See Event Structure for a description of supported data types.

During adapter development, event timestamps are specified using the DataTimeOffset type. However, only the DateTime type is supported in the definition of the event type payload fields. In scenarios in which you import data of type DateTimeOffset into an event field, you must convert the data to DateTime of kind UTC. For example, a payload field may be filled in from a database or your report server without the permission of the system administrator. database, or by copying the event timestamp fields into payload fields for computation.

See Also

Creating Input and Output Adapters
Event Structure
NIB StreamInsight Server Concepts