org.fosstrak.epcis.repository
Interface EpcisQueryControlInterface

All Known Implementing Classes:

QueryOperationsModule

public interface EpcisQueryControlInterface

The EPCIS Query Control Interface provides a general framework by which client applications may query EPCIS data. The interface provides both on-demand queries, in which an explicit request from a client causes a query to be executed and results returned in response, and standing queries, in which a client registers ongoing interest in a query and thereafter receives periodic delivery of results via the EPCIS Query Callback Interface without making further requests. These two modes are informally referred to as "pull" and "push", respectively.

Standing queries are made by making one or more subscriptions to a previously defined query using the subscribe method. Results will be delivered periodically via the Query Callback Interface to a specified destination, until the subscription is canceled using the unsubscribe method. On-demand queries are made by executing a previously defined query using the poll method. Each invocation of the poll method returns a result directly to the caller. In either case, if the query is parameterized, specific settings for the parameters may be provided as arguments to subscribe or poll.

Method Summary

List<String>	getQueryNames() Returns a list of all query names available for use with the subscribe and poll methods.
String	getStandardVersion() Returns a string that identifies what version of the specification this implementation complies with.
List<String>	getSubscriptionIDs(String queryName) Returns a list of all subscriptionIDs currently subscribed to the specified named query.
String	getVendorVersion() Returns a string that identifies what vendor extensions this implementation provides.
QueryResults	poll(String queryName, QueryParams params) Invokes a previously defined query having the specified name, returning the results.
void	subscribe(String queryName, QueryParams params, String dest, SubscriptionControls controls, String subscriptionID) Registers a subscriber for a previously defined query having the specified name.
void	unsubscribe(String subscriptionID) Removes a previously registered subscription having the specified subscriptionID.

Method Detail

subscribe

void subscribe(String queryName,
               QueryParams params,
               String dest,
               SubscriptionControls controls,
               String subscriptionID)
               throws NoSuchNameExceptionResponse,
                      InvalidURIExceptionResponse,
                      DuplicateSubscriptionExceptionResponse,
                      QueryParameterExceptionResponse,
                      QueryTooComplexExceptionResponse,
                      SubscriptionControlsExceptionResponse,
                      SubscribeNotPermittedExceptionResponse,
                      SecurityExceptionResponse,
                      ValidationExceptionResponse,
                      ImplementationExceptionResponse

Registers a subscriber for a previously defined query having the specified name. The params argument provides the values to be used for any named parameters defined by the query. The dest parameter specifies a destination where results from the query are to be delivered, via the Query Callback Interface. The dest parameter is a URI that both identifies a specific binding of the Query Callback Interface to use and specifies addressing information. The controls parameter controls how the subscription is to be processed; in particular, it specifies the conditions under which the query is to be invoked (e.g., specifying a periodic schedule). The subscriptionID is an arbitrary string that is copied into every response delivered to the specified destination, and otherwise not interpreted by the EPCIS service. The client may use the subscriptionID to identify from which subscription a given result was generated, especially when several subscriptions are made to the same destination. The dest argument MAY be null or empty, in which case results are delivered to a pre-arranged destination based on the authenticated identity of the caller. If the EPCIS implementation does not have a destination pre-arranged for the caller, or does not permit this usage, it SHALL raise an InvalidURIException.

Parameters:

queryName - The name of a previously defined query for which the subscriber will be registered.

params - Provides the values to be used for any named parameters defined by the query.

dest - Specifies a destination where results from the query are to be delivered, via the Query Callback Interface. It is a URI that both identifies a specific binding of the Query Callback Interface to use and specifies addressing information. May be null or empty, in which case results are delivered to a pre-arranged destination based on the authenticated identity of the caller.

controls - Controls how the subscription is to be processed; in particular, it specifies the conditions under which the query is to be invoked (e.g., specifying a periodic schedule).

subscriptionID - An arbitrary string that is copied into every response delivered to the specified destination, and otherwise not interpreted by the EPCIS service. The client may use the subscriptionID to identify from which subscription a given result was generated, especially when several subscriptions are made to the same destination.

Throws:

InvalidURIException - If the EPCIS implementation does not have a destination pre-arranged for the caller, or does not permit this usage.

QueryParameterException - Under any of the following circumstances:

• A parameter required by the specified query was omitted or was supplied with an empty value
• A parameter was supplied whose name does not correspond to any parameter name defined by the specified query
• Two parameters are supplied having the same name
• Any other constraint imposed by the specified query is violated. Such constraints may include restrictions on the range of values permitted for a given parameter, requirements that two or more parameters be mutually exclusive or must be supplied together, and so on. The specific constraints imposed by a given query are specified in the documentation for that query.

NoSuchNameExceptionResponse

InvalidURIExceptionResponse

DuplicateSubscriptionExceptionResponse

QueryParameterExceptionResponse

QueryTooComplexExceptionResponse

SubscriptionControlsExceptionResponse

SubscribeNotPermittedExceptionResponse

SecurityExceptionResponse

ValidationExceptionResponse

ImplementationExceptionResponse

unsubscribe

void unsubscribe(String subscriptionID)
                 throws NoSuchSubscriptionExceptionResponse,
                        SecurityExceptionResponse,
                        ValidationExceptionResponse,
                        ImplementationExceptionResponse

Removes a previously registered subscription having the specified subscriptionID.

Parameters:

subscriptionID - The subscriptionID of a previously registered subscription.

Throws:

NoSuchSubscriptionExceptionResponse

SecurityExceptionResponse

ValidationExceptionResponse

ImplementationExceptionResponse

poll

QueryResults poll(String queryName,
                  QueryParams params)
                  throws NoSuchNameExceptionResponse,
                         QueryParameterExceptionResponse,
                         QueryTooComplexExceptionResponse,
                         QueryTooLargeExceptionResponse,
                         SecurityExceptionResponse,
                         ValidationExceptionResponse,
                         ImplementationExceptionResponse

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 defined by the query.

Parameters:

queryName - The name of a previously defined query to be invoked.

params - Provides the values to be used for any named parameters defined by the query.

Returns:

The results of the query invocation.

Throws:

QueryParameterException - Under any of the following circumstances:

• A parameter required by the specified query was omitted or was supplied with an empty value
• A parameter was supplied whose name does not correspond to any parameter name defined by the specified query
• Two parameters are supplied having the same name
• Any other constraint imposed by the specified query is violated. Such constraints may include restrictions on the range of values permitted for a given parameter, requirements that two or more parameters be mutually exclusive or must be supplied together, and so on. The specific constraints imposed by a given query are specified in the documentation for that query.

NoSuchNameExceptionResponse

QueryParameterExceptionResponse

QueryTooComplexExceptionResponse

QueryTooLargeExceptionResponse

SecurityExceptionResponse

ValidationExceptionResponse

ImplementationExceptionResponse

getQueryNames

List<String> getQueryNames()
                           throws SecurityExceptionResponse,
                                  ValidationExceptionResponse,
                                  ImplementationExceptionResponse

Returns a list of all query names available for use with the subscribe and poll methods. This includes all pre-defined queries provided by the implementation, including those specified in the EPCIS standard in Section 8.2.7.

Returns:

A list of all query names available for use with the subscribe and poll methods.

Throws:

SecurityExceptionResponse

ValidationExceptionResponse

ImplementationExceptionResponse

getSubscriptionIDs

List<String> getSubscriptionIDs(String queryName)
                                throws NoSuchNameExceptionResponse,
                                       SecurityExceptionResponse,
                                       ValidationExceptionResponse,
                                       ImplementationExceptionResponse

Returns a list of all subscriptionIDs currently subscribed to the specified named query.

Parameters:

queryName - The name of a previously defined query for which the subscriptionIDs should be returned.

Returns:

A list of all subscriptionIDs currently subscribed to the specified named query.

Throws:

NoSuchNameExceptionResponse

SecurityExceptionResponse

ValidationExceptionResponse

ImplementationExceptionResponse

getStandardVersion

String getStandardVersion()
                          throws SecurityExceptionResponse,
                                 ValidationExceptionResponse,
                                 ImplementationExceptionResponse

Returns a string that identifies what version of the specification this implementation complies with. The possible values for this string are defined by EPCglobal. An implementation SHALL return a string corresponding to a version of this specification to which the implementation fully complies, and SHOULD return the string corresponding to the latest version to which it complies. To indicate compliance with this Version 1.0 of the EPCIS specification, the implementation SHALL return the string 1.0.

Returns:

A string that identifies what version of the specification this implementation complies with.

Throws:

SecurityExceptionResponse

ValidationExceptionResponse

ImplementationExceptionResponse

getVendorVersion

String getVendorVersion()
                        throws SecurityExceptionResponse,
                               ValidationExceptionResponse,
                               ImplementationExceptionResponse

Returns a string that identifies what vendor extensions this implementation provides. The possible values of this string and their meanings are vendor-defined, except that the empty string SHALL indicate that the implementation implements only standard functionality with no vendor extensions. When an implementation chooses to return a non-empty string, the value returned SHALL be a URI where the vendor is the owning authority. For example, this may be an HTTP URL whose authority portion is a domain name owned by the vendor, a URN having a URN namespace identifier issued to the vendor by IANA, an OID URN whose initial path is a Private Enterprise Number assigned to the vendor, etc.

Returns:

A string that identifies what vendor extensions this implementation provides.

Throws:

SecurityExceptionResponse

ValidationExceptionResponse

ImplementationExceptionResponse