# Understanding the Event, Master Data, and Data Exchange Services

# Capture and Query APIs

The following sections provide information about the capture and query interfaces.

- Capture Interface: The capture API is the simpler of the two, consisting of only one method, `capture()`, which takes a single argument and has no return value. A capture application uses this method to send EPCIS events to an Enterprise Server for insertion into an EPCIS database.
- Query Interface: The query API provides several methods for extracting information from an EPCIS database.

The methods described in these sections constitute the public SOAP API for the WebLogic RFID Enterprise Server. For XSD and WSDL information, see Table 2-2, Schema Filenames and Target Namespace for Events and Master Data, on page 2-7.

Note: | In all API calls, EPCs should be provided in Pure Identity format; if EPCs are specified in tag format, they will be stored in tag format and Pure Identity format.

## Capture Interface

The EPCIS Capture Interface provides the ability to capture and persist EPCIS Events. The capture interface is exposed as JMS, HTTP, and SOAP.

The `capture()` method records EPCIS events:

    capture(event : List<EPCISEvent>) : void

The `capture()` method takes one argument, a List of `EPCISEvent`, and returns no results. Because the argument is a list, you can capture one or more EPCIS Events at a time. The events in the following list are those described in Event Service:

- `EPCISEvent`

Note: | Because `EPCISEvent` is abstract; only events of the following four types can actually be captured.

- `ObjectEvent`
- `AggregationEvent`
- `QuantityEvent`
- `TransactionEvent`

Events can be captured via JMS, SOAP, and HTTP.

Note: | For backwards compatibility with 1.x versions of Enterprise Server, Enterprise Server 2.0 supports the `captureEPCISEvent()` method. The difference between these two capture methods is that `capture()` can record multiple EPCIS events at a time while `captureEPCISEvent()` can record only one EPCIS event at a time. For information about `captureEPCISEvent()`, see the Enterprise Server 1.1 Administrator's Guide at http://download.oracle.com/docs/cd/E13197_01/rfid/rftagaware/pdf/ESAdministratorsGuide1_1.pdf.

Note: | All Enterprise Server 1.x capture and query interfaces are supported via a separate Web service in Enterprise Server 2.0. The 1.1 SOAP API is exposed in the 2.0 release. The URL for the 1.1 SOAP service is:

Note: | `http://[host]:[port]/legacyepcis/LegacyEPCIS`

For SOAP, the inbound-message URL for the WebLogic RFID Enterprise Server 2.0 SOAP service is `http://[host]:[port]/epcis/EPCIS`.

For JMS, three inbound-message queues are provided in WebLogic RFID Enterprise Server 2.0:

- `EPCISMessages` (1.1 messages)
- `EPCISCapture` (2.0 messages)
- `EPCISFailedMessages` (failed messages of all types)

The `EPCISMessages` queue used in version 1.1 is also available in 2.0. Therefore applications that sent messages to this queue in Enterprise Server 1.1 can send continue to send messages to the same queue in Enterprise Server 2.0 without any modifications. This queue should operate seamlessly, assuming that security configurations are compatible between the sending and receiving systems.

The `EPCISCapture` queue is a new queue for capturing messages formatted for Enterprise Server 2.0.

The `EPCISFailedMessages` queue can hold messages of either type. When an error occurs during capture, a message is automatically moved to this queue after the number of retries is exceeded.

For HTTP, the inbound-message URL is `http://[host]:[port]/EPCISServlet`.

## Query Interface

The query interface supports querying the EPCIS event repository by constructing a query and a set of associated query parameters. Query parameters include time constraints, event types, event fields, action, disposition, and master data name/value attributes. Both synchronous and asynchronous queries are supported through polling and subscription mechanisms. The query interface is exposed as a SOAP Service defined by a WSDL and set of XSD files.

The following sections provide information about the query interface:

- Query Interface Methods
- Query Interface Parameters and Data Types
- Query Interface Results
- Query Interface Exceptions

### Query Interface Methods

The query interface provides two basic types of queries for event information: those that poll for an immediate response from the Event Repository, and those that register a query subscription for periodic delivery of information from the Event Repository.

There are several methods for querying the EPCIS database:

- `getQueryNames() : List // of names`
- `getStandardVersion() : String`
- `getSubscription (subscriptionID : String) : Subscription
  // BEA Extension`
- `getSubscriptionIDs(queryName : String) : List // of Strings`
- `getVendorVersion() : String`
- `poll(queryName : String, params : QueryParams) : QueryResults`
- `subscribe(queryName : String, params : QueryParams, dest : URI, controls : SubscriptionControls, subscriptionID : String)`

Note: | The query subscription administration console uses the `subscribe()` method.

- `unsubscribe(subscriptionID : String)`

Table 6-1 describes the query methods. Query Interface Parameters and Data Types describes the `queryName` parameter, and the `QueryParams` and `SubscriptionControls` data types.

Table 6-1 Query Methods
Method | Description
--- | ---
`getQueryNames` | Return a List containing the pre-defined query name: `SimpleEventQuery`.
`getSubscription` | Given a `subscriptionID`, return a `Subscription` (BEA extension). A `Subscription` contains: `subscriptionID` `notificationURI` `queryName`
`getSubscriptionIDs` | Return a List of active subscription IDs: all subscription IDs currently subscribed to the specified named query. See queryName.
`getStandardVersion` | Returns the version of the EPCIS specification to which this implementation conforms. This method always returns `1.0`.
`getVendorVersion` | Returns a string that identifies the version of any vendor extensions this implementation provides. This method always returns `http://version.connecterra.com/epcis/1`.
`poll` | Poll for synchronous query response. Invokes a previously defined query having the specified name, returning the results. The `params` argument provides the values to be used for any named parameters embedded in the definition of the query. See queryName, QueryParams, and Query Interface Results.
`subscribe` | Subscribe to a Query for asynchronous notification. Registers a subscriber for a previously defined query having the specified name. `queryName`: a string specifying the name of the query. See queryName. `params` : `QueryParams`: the values used for any named parameters embedded in the definition of the query. See QueryParams. `dest` : `URI`: a URI-specified destination where results from the query are to be delivered. See Notification URIs. `controls` : `SubscriptionControls`: controls how the subscription is to be processed. In particular, it specifies the conditions under which the query is to be invoked; for example, specifying a periodic schedule. See SubscriptionControls. `subscriptionID`: an arbitrary string that is copied into every response delivered to the specified destination, and otherwise not interpreted by the EPCIS service. A client might use the `subscriptionID` to identify from which subscription a given result was generated, especially when several subscriptions are made to the same destination.
`unsubscribe` | Unsubscribe from an existing query. Removes a previously registered subscription having the specified `subscriptionID`.

### Query Interface Parameters and Data Types

This section describes the `queryName` parameter and the data types used by query methods (excluding such well-known types as List or String):

- queryName (used by the `poll` and `subscribe` methods)
- `params` :`` QueryParams (used by the `poll` and `subscribe` methods)
- `controls` :`` SubscriptionControls (used by the `subscribe` method)
- `schedule` :`` QuerySchedule (used by `SubscriptionControls`)
- `initialRecordTime` :`Time` (see SubscriptionControls)
- `dest : URI (`Notification URIs, used by the `subscribe` method)

#### queryName

WebLogic RFID Enterprise Server 2.0 supports the following query name:

- `SimpleEventQuery`

Therefore, when you use `poll()` or `subscribe()`, the String you specify as the `queryName` must be `SimpleEventQuery`. In addition, `getQueryNames()` will return only this name.

Data Exchange Service describes this query and provides tables of the `QueryParam` name/value pairs you can use to define a query request.

#### QueryParams

`QueryParams` is the data type for the `params` argument used by the `poll`() and `subscribe()` methods.

A `QueryParams` instance is a set of `QueryParam` name/value pairs, where the names correspond to parameter names in the query, and the values are the specific values to be used for that invocation of (`poll`) or subscription to (`subscribe`) the query.

      <xsd:complexType name="QueryParam">
        <xsd:sequence>
          <xsd:element name="name" type="xsd:string"/>
          <xsd:element name="value" type="xsd:anyType"/>
        </xsd:sequence>
      </xsd:complexType>

Table 6-2 lists the valid XML types you can use when specifying a value.

Table 6-2 XML Types for value Elements
Parameter Type | XML type for `value` element
--- | ---
Int | `xsd:integer`
Float | `xsd:double`
Time | `xsd:dateTime`
String | `xsd:string`
List of String | `epcisq:ArrayOfString`

For `poll()` and `subscribe()`, the valid set of name/value pairs are those supported by `SimpleEventQuery.`

See SimpleEventQuery for detailed descriptions of valid name/value pairs

Note: | Although a `QueryParam` is a simple name/value pair, there can be a large matrix of possible pairs that you can specify when constructing a single `params` argument; therein lies both the power and the complexity of creating subscriptions and queries. For example, `SimpleEventQuery` recognizes more than 30 name/value pairs.

Note: | Enterprise Server provides the Query Subscription Administration Console, which is the mechanism you use for creating subscription-based queries.

#### SubscriptionControls

Standing queries are subscribed to via the `subscribe` method. For each subscription, a `SubscriptionControls` instance defines how the query is to be processed.

Table 6-3 describes the fields of a `SubscriptionControls` instance.

Table 6-3 SubscriptionControls
Argument | Description
--- | ---
Name: schedule Data Type: QuerySchedule Required: No | Defines the periodic schedule on which the query is to be executed. See QuerySchedule. You must specify schedule or trigger, but not both.
Name: trigger Data Type: URI Required: No | Specifies a triggering event known to the EPCIS service that will trigger execution of this query. (Available trigger URIs are service-dependent.) You must specify trigger or schedule, but not both.
Name: initialRecordTime Data Type: Time Required: No | Specifies a time that determines which events are considered when processing a standing query for the first time. If omitted, defaults to the time at which the subscription is created. The first time the query is executed for a given subscription, the only events considered are those whose recordTime field is greater than or equal to initialRecordTime specified when the subscription was created. For each subsequent execution of the query, the only events considered are those whose recordTime field is greater than or equal to the time when the query was last executed.
Name: reportIfEmpty Data Type: Boolean Required: Yes | If true, a QueryReports instance is always sent to the subscriber when the query is executed. If false, a QueryReports instance is sent to the subscriber only when the results are non-empty.

#### QuerySchedule

If specified, a `QuerySchedule` defines a periodic schedule for query execution for a specific subscription. The query will be executed each time the current date and time matches the specification in the `QuerySchedule`. Each `QuerySchedule` field is a string, whose value conforms to the following grammar:

    QueryScheduleField ::= Element ( "," Element )*

    Element ::= Number | Range

    Range ::= "[" Number "-" Number "]"

    Number ::= Digit+

    Digit ::= "0" | "1" | "2" | "3" | "4"
            | "5" | "6" | "7" | "8" | "9"

Table 6-4 QuerySchedule
Argument | Description
--- | ---
Name: second Data Type: String Required: No | Specifies that the query time must have a matching seconds value. The range for this parameter is 0 through 59, inclusive.
Name: minute Data Type: String Required: No | Specifies that the query time must have a matching minute value. The range for this parameter is 0 through 59, inclusive.
Name: hour Data Type: String Required: No | Specifies that the query time must have a matching hour value. The range for this parameter is 0 through 23, inclusive, with 0 denoting the hour that begins at midnight, and 23 denoting the hour that ends at midnight.
Name: dayOfMonth Data Type: String Required: No | Specifies that the query time must have a matching day of month value. The range for this parameter is 1 through 31, inclusive. (Values of 29, 30, and 31 will only match during months that have at least that many days.)
Name: month Data Type: String Required: No | Specifies that the query time must have a matching month value. The range for this parameter is 1 through 12, inclusive.
Name: dayOfWeek Data Type: String Required: No | Specifies that the query time must have a matching day of week value. The range for this parameter is 1 through 7, inclusive, with 1 denoting Monday, 2 denoting Tuesday, and so forth, up to 7 denoting Sunday.

The following `QuerySchedule` examples show how various combinations of elements are interpreted:

    QuerySchedule
        second = "0"
        minute = "0"
        all other fields omitted

This means "run the query once per hour, at the top of the hour." If the `reportIfEmpty` argument to `subscribe` is false, then this does not necessarily cause a report to be sent each hour - a report would be sent within an hour of any new event data becoming available that matches the query.

    QuerySchedule
        second = "0"
        minute = "30"
        hour = "2"
        all other fields omitted

This means "run the query once per day, at 2:30 am."

    QuerySchedule
        second = "0"
        minute = "0"
        dayOfWeek = "[1-5]"

This means "run the query once per hour at the top of the hour, but only on weekdays."

    QuerySchedule
        hour = "2"
        all other fields omitted

This means "run the query once per second between 2:00:00 and 2:59:59 each day." This example illustrates that it usually not desirable to omit a field of finer granularity than the fields that are specified.

#### Notification URIs

The following notification URIs can be used as the `dest` parameter to the `subscribe` method

- HTTP
- Applicability Statement 2 (AS2)

In all delivery mechanisms, the content is transferred in XML format as specified by the EPCIS XML Schema definition

##### HTTP

The HTTP notification URI provides for delivery of query results in XML via the HTTP protocol using the POST operation.

An HTTP notification URI has the two following forms:

    http://host:port/remainder-of-URL
    http://host/remainder-of-URL

The following table defines the terms used in the HTTP form.

host | The DNS name or IP address of the host where the receiver is listening for incoming HTTP connections.
`port` | The TCP port on which the receiver is listening for incoming HTTP connections. If omitted, the default port for HTTP is 80.
`remainder-of-URL` | The URL to which an HTTP POST operation will be directed.

The message payload is an `EPCISQueryDocument` instance whose `EPCISBody` element contains a `StandingQueryResults` element. For more information, see Query Interface Results.

##### Applicability Statement 2 (AS2)

The AS2 notification URI provides for delivery of query results in XML via AS2.

An AS2 notification URI has the following form:

    as2:remainder-of-URI

The `remainder-of-URI` identifies a specific AS2 communication profile to be used by the EPCIS Service to deliver information to the subscriber. Typically, the value of `remainder-of-URI` is a string naming a particular AS2 communication profile, where the profile implies such things as the HTTP URL to which AS2 messages are to be delivered, the security certificates to use, etc. A client of the EPCIS Query Interface that wants to use AS2 for delivery of standing query results must pre-arrange with the provider of the EPCIS Service the specific value of `remainder-of-URI` to use.

The AS2 message payload is an `EPCISQueryDocument` instance whose `EPCISBody` element contains a `StandingQueryResults` element. For more information, see Query Interface Results. For information on configuring AS2 as a destination for a query subscription, see Configuring Enterprise Server to S end Query Subscription Results to an AS2 Destination in Installing WebLogic RFID Enterprise Server.

### Query Interface Results

`QueryResults` is the return type for the `poll` method and for standing queries requested by the `subscribe` method.

- The `poll` method returns a `PollResult` element of type `OnDemandQueryResults`
- The `subscribe` method returns a `StandingQueryResults` element of type `StandingQueryResults`.

Both results include a `resultsBody` element of type `QueryResultsBody`. The following XSD code fragments illustrate this shared use of `QueryResultsBody`:

    poll:

    <xsd:element name="PollResult" type="epcisq:OnDemandQueryResults"/>
       ...
    <xsd:complexType name="OnDemandQueryResults">
      <xsd:sequence>
        <xsd:element name="resultsBody" type="epcisq:QueryResultsBody"/>
       ...
      </xsd:sequence>
    </xsd:complexType>

    subscribe:

    <xsd:element name="StandingQueryResults"
          type="epcisq:StandingQueryResults"/>
    <xsd:complexType name="StandingQueryResults">
      <xsd:sequence>
        <xsd:element name="queryName" type="xsd:string"/>
        <xsd:element name="subscriptionID" type="xsd:string"/>
        <xsd:element name="resultsBody" type="epcisq:QueryResultsBody"/>
       ...
      </xsd:sequence>
    </xsd:complexType>

    QueryResultsBody:

    <xsd:complexType name="QueryResultsBody">
      <xsd:choice>
        <xsd:element name="eventList" type="epcis:EventListType"/>
        <xsd:element name="vocabularyList" type="epcismd:VocabularyListType"/>
        ...
      </xsd:choice>
    </xsd:complexType>

Thus, both methods return a `QueryResultsBody` (with a subscription you also receive the queryName and the subscriptionID). In essence, a query returns either a list of events or a list of master data information.

Event information is in an `eventList` element of type EventListType, which contains zero or more instances of the supported event types:

    <xsd:complexType name="EventListType">
       <xsd:choice maxOccurs="unbounded">
            <xsd:element name="ObjectEvent" type="epcis:ObjectEventType"
                 maxOccurs="unbounded"/>
            <xsd:element name="AggregationEvent"
                 type="epcis:AggregationEventType" maxOccurs="unbounded"/>
            <xsd:element name="QuantityEvent" type="epcis:QuantityEventType"
                 maxOccurs="unbounded"/>
            <xsd:element name="TransactionEvent"
                 type="epcis:TransactionEventType" maxOccurs="unbounded"/>
            <xsd:element name="extension"
                 type="epcis:EPCISEventListExtensionType"/>
            <xsd:any namespace="##other" processContents="lax"/>
       </xsd:choice>
    </xsd:complexType>

Master data information is in a `vocabularyList` element of type VocabularyListType, which eventually devolves to zero or more instances of a `VocabularyElementType`:

    <xsd:complexType name="VocabularyElementType">
      <xsd:sequence>
        <xsd:element name="attribute" type="epcismd:AttributeType"
             minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="children" type="epcismd:IDListType" minOccurs="0"/>
        ...
        </xsd:sequence>
        <xsd:attribute name="id" type="xsd:anyURI" use="required"/>
        <xsd:anyAttribute processContents="lax"/>
      </xsd:complexType>

    <xsd:complexType name="AttributeType">
       ...
        <xsd:attribute name="id" type="xsd:anyURI" use="required"/>
       ...
    </xsd:complexType>

    <xsd:complexType name="IDListType">
       ...
        <xsd:element name="id" type="xsd:anyURI" minOccurs="0"
             maxOccurs="unbounded"/>
       ...
    </xsd:complexType>

### Query Interface Exceptions

Table 6-5 lists possible exceptions for the following methods:

- `getQueryNames`
- getSubscription
- `getSubscriptionIDs`
- `poll`
- `subscribe`
- `unsubscribe`

Table 6-6 describes the exceptions.

Table 6-5 Query Method Exceptions
Query Method | Exception
--- | ---
`getQueryNames` | `SecurityException ImplementationException`
`getSubscription` | `NoSuchNameException SecurityException SecurityException`
`getSubscriptionIDs` | `NoSuchNameException SecurityException ImplementationException`
`poll` | `NoSuchNameException QueryParameterException QueryTooComplexException QueryTooLargeException SecurityException ImplementationException`
`subscribe` | `NoSuchNameException InvalidURIException DuplicateSubscriptionException QueryParameterException QueryTooComplexException SubscriptionControlsException SubscribeNotPermittedException SecurityException ImplementationException`
`unsubscribe` | `NoSuchSubscriptionException SecurityException ImplementationException`

In addition, an attempt to execute a standing query might result in a `QueryTooLarge` exception being sent to a subscriber instead of a normal query result. In this case, the `QueryTooLargeException` includes, in addition to the reason string, the query name and the `subscriptionID` as specified in the `subscribe` call that created the standing query.

Table 6-6 Query Exception Descriptions
Exception | Description
--- | ---
`DuplicateSubscriptionException` | The specified SubscriptionID is identical to a previous subscription that was created and not yet unsubscribed.
`ImplementationException` | Implementation-specific exception.
`InvalidURIException` | The URI specified for the subscriber cannot be parsed.
`NoSuchNameException` | The specified query does not exist.
`NoSuchSubscriptionException` | The specified SubscriptionID does not exist.
`QueryParameterException` | One or more query parameters are invalid.
`QueryTooComplexException` | Either the query or the query parameters exceeded the abilities of the implementation.
`SecurityException` | Access control violation.
`SubscriptionControlsException` | Invalid SubscriptionControls.
`SubscribeNotPermittedException` | The specified query is not supported with subscribe, only poll.