|
|
The following sections provide information about the capture and query interfaces.
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. 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. |
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:
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:
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.
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:
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 namesgetStandardVersion() : StringgetSubscription (subscriptionID : String) : Subscription
// BEA ExtensiongetSubscriptionIDs(queryName : String) : List // of StringsgetVendorVersion() : Stringpoll(queryName : String, params : QueryParams) : QueryResultssubscribe(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.
Return a List of active subscription IDs: all subscription IDs currently subscribed to the specified named query. See queryName.
|
|
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 to a Query for asynchronous notification. Registers a subscriber for a previously defined query having the specified name.
|
|
This section describes the queryName parameter and the data types used by query methods (excluding such well-known types as List or String):
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)WebLogic RFID Enterprise Server 2.0 supports the following query name:
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 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.
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. |
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.
Defines the periodic schedule on which the query is to be executed. See QuerySchedule. You must specify schedule or trigger, but not both.
|
|
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.
|
|
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"
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.
The following notification URIs can be used as the dest parameter to the subscribe method
In all delivery mechanisms, the content is transferred in XML format as specified by the EPCIS XML Schema definition
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-URLThe following table defines the terms used in the HTTP form.
The message payload is an EPCISQueryDocument instance whose EPCISBody element contains a StandingQueryResults element. For more information, see Query Interface Results.
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.
QueryResults is the return type for the poll method and for standing queries requested by the subscribe method.
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>
Table 6-5 lists possible exceptions for the following methods:
Table 6-6 describes the exceptions.
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.
|