EPCglobal-epcis-query-1

EPC Implementer	>	EPCIS	>	Query

EPCglobal-epcis-query-1_0

Previous element

Next element

ComplexType

epcisq:QuerySchedule

Definition:

A QuerySchedule may be specified to specify a periodic schedule for query execution for a specific subscription. Each field of QuerySchedule is a string that specifies a pattern for matching some part of the current time. The query will be executed each time the current date and time matches the specification inthe QuerySchedule.

Each QuerySchedule field is a string, whose value must conform 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”

Each Number that is part of the query schedule field value must fall within the legal range for that field as specified in the table below. An EPCIS implementation shall raise a SubscriptionControlsException if any query schedule field value does not conform to the grammar above, or contains a Number that falls outside the legal range, or includes a Range where the first Number is greater than the second Number.

The QuerySchedule specifies a periodic sequence of time values (the “query times”). A query time is any time value that matches the QuerySchedule, according to the following rule:
• Given a time value, extract the second, minute, hour (0 through 23, inclusive), dayOfMonth (1 through 31, inclusive), and dayOfWeek (1 through 7, inclusive,denoting Monday through Sunday). This calculation is to be performed relative to a time zone chosen by the EPCIS Service.
• The time value matches the QuerySchedule if each of the values extracted above matches (as defined below) the corresponding field of the QuerySchedule, for all QuerySchedule fields that are not omitted.
• A value extracted from the time value matches a field of the QuerySchedule if it matches any of the comma-separated Elements of the query schedule field.
• A value extracted from the time value matches an Element of a query schedule field if
       • the Element is a Number and the value extracted from the time value is equal to the Number; or
       • the Element is a Range and the value extracted from the time value is greater than or equal to the first Number in the Range and less than or equal tothe second Number in the Range.

An EPCIS implementation SHALL interpret the QuerySchedule as a client’s statement of when it would like the query to be executed, and should make reasonable efforts to adhere to that schedule. An EPCIS implementation may, however, deviate from the requested schedule according to its own policies regarding server load, authorization, or any other reason. If an EPCIS implementation knows, at the time the subscribe method is called, that it will not be able to honor the specified QuerySchedule without deviating widely from the request, the EPCIS implementation should raise a SubscriptionControlsException instead.

In any case, the automatic handling of recordTime as specified earlier shall be based on the actual time the query is executed, whether or not that exactly matches the QuerySchedule.

Example:

The QuerySchedule, taken literally, specifies the exact timing of query execution down to the second. In practice, an implementation may not wish to or may not be able to honor that request precisely, but can honor the general intent. For example, a QuerySchedule may specify that a query be executed every hour on the hour, while an implementation may choose to execute the query every hour plus or minus five minutes from the top of the hour.

Example 1
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.

Example 2
QuerySchedule
     second = “0”
     minute = “30”
     hour = “2”
     all other fields omitted
This means “run the query once per day, at 2:30 am.”

Example 3
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.”

Example 4
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.