1 /* 2 * Copyright (C) 2007 ETH Zurich 3 * 4 * This file is part of Fosstrak (www.fosstrak.org). 5 * 6 * Fosstrak is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License version 2.1, as published by the Free Software Foundation. 9 * 10 * Fosstrak is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public 16 * License along with Fosstrak; if not, write to the Free 17 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 18 * Boston, MA 02110-1301 USA 19 */ 20 21 package org.fosstrak.epcis.repository; 22 23 import java.util.List; 24 25 import org.fosstrak.epcis.model.InvalidURIException; 26 import org.fosstrak.epcis.model.QueryParameterException; 27 import org.fosstrak.epcis.model.QueryParams; 28 import org.fosstrak.epcis.model.QueryResults; 29 import org.fosstrak.epcis.model.SubscriptionControls; 30 import org.fosstrak.epcis.soap.DuplicateSubscriptionExceptionResponse; 31 import org.fosstrak.epcis.soap.ImplementationExceptionResponse; 32 import org.fosstrak.epcis.soap.InvalidURIExceptionResponse; 33 import org.fosstrak.epcis.soap.NoSuchNameExceptionResponse; 34 import org.fosstrak.epcis.soap.NoSuchSubscriptionExceptionResponse; 35 import org.fosstrak.epcis.soap.QueryParameterExceptionResponse; 36 import org.fosstrak.epcis.soap.QueryTooComplexExceptionResponse; 37 import org.fosstrak.epcis.soap.QueryTooLargeExceptionResponse; 38 import org.fosstrak.epcis.soap.SecurityExceptionResponse; 39 import org.fosstrak.epcis.soap.SubscribeNotPermittedExceptionResponse; 40 import org.fosstrak.epcis.soap.SubscriptionControlsExceptionResponse; 41 import org.fosstrak.epcis.soap.ValidationExceptionResponse; 42 43 /** 44 * <p> 45 * The EPCIS Query Control Interface provides a general framework by which 46 * client applications may query EPCIS data. The interface provides both 47 * on-demand queries, in which an explicit request from a client causes a query 48 * to be executed and results returned in response, and standing queries, in 49 * which a client registers ongoing interest in a query and thereafter receives 50 * periodic delivery of results via the EPCIS Query Callback Interface without 51 * making further requests. These two modes are informally referred to as "pull" 52 * and "push", respectively. 53 * </p> 54 * <p> 55 * Standing queries are made by making one or more subscriptions to a previously 56 * defined query using the 57 * {@link subscribe(String, QueryParams, URI, SubscriptionControls, String) 58 * subscribe} method. Results will be delivered periodically via the Query 59 * Callback Interface to a specified destination, until the subscription is 60 * canceled using the {@link #unsubscribe(String) unsubscribe} method. On-demand 61 * queries are made by executing a previously defined query using the 62 * {@link poll(String, QueryParams) poll} method. Each invocation of the 63 * {@link poll(String, QueryParams) poll} method returns a result directly to 64 * the caller. In either case, if the query is parameterized, specific settings 65 * for the parameters may be provided as arguments to 66 * {@link subscribe(String, QueryParams, URI, SubscriptionControls, String) 67 * subscribe} or {@link poll(String, QueryParams) poll}. 68 * </p> 69 */ 70 public interface EpcisQueryControlInterface { 71 72 /** 73 * Registers a subscriber for a previously defined query having the 74 * specified name. The <code>params</code> argument provides the values to 75 * be used for any named parameters defined by the query. The 76 * <code>dest</code> parameter specifies a destination where results from 77 * the query are to be delivered, via the Query Callback Interface. The 78 * <code>dest</code> parameter is a URI that both identifies a specific 79 * binding of the Query Callback Interface to use and specifies addressing 80 * information. The <code>controls</code> parameter controls how the 81 * subscription is to be processed; in particular, it specifies the 82 * conditions under which the query is to be invoked (e.g., specifying a 83 * periodic schedule). The <code>subscriptionID</code> is an arbitrary 84 * string that is copied into every response delivered to the specified 85 * destination, and otherwise not interpreted by the EPCIS service. The 86 * client may use the subscriptionID to identify from which subscription a 87 * given result was generated, especially when several subscriptions are 88 * made to the same destination. The <code>dest</code> argument MAY be 89 * null or empty, in which case results are delivered to a pre-arranged 90 * destination based on the authenticated identity of the caller. If the 91 * EPCIS implementation does not have a destination pre-arranged for the 92 * caller, or does not permit this usage, it SHALL raise an 93 * <code>InvalidURIException</code>. 94 * 95 * @param queryName 96 * The name of a previously defined query for which the 97 * subscriber will be registered. 98 * @param params 99 * Provides the values to be used for any named parameters 100 * defined by the query. 101 * @param dest 102 * Specifies a destination where results from the query are to be 103 * delivered, via the Query Callback Interface. It is a URI that 104 * both identifies a specific binding of the Query Callback 105 * Interface to use and specifies addressing information. May be 106 * <code>null</code> or empty, in which case results are 107 * delivered to a pre-arranged destination based on the 108 * authenticated identity of the caller. 109 * @param controls 110 * Controls how the subscription is to be processed; in 111 * particular, it specifies the conditions under which the query 112 * is to be invoked (e.g., specifying a periodic schedule). 113 * @param subscriptionID 114 * An arbitrary string that is copied into every response 115 * delivered to the specified destination, and otherwise not 116 * interpreted by the EPCIS service. The client may use the 117 * subscriptionID to identify from which subscription a given 118 * result was generated, especially when several subscriptions 119 * are made to the same destination. 120 * @throws InvalidURIException 121 * If the EPCIS implementation does not have a destination 122 * pre-arranged for the caller, or does not permit this usage. 123 * @throws QueryParameterException 124 * Under any of the following circumstances: 125 * <ul> 126 * <li>A parameter required by the specified query was omitted 127 * or was supplied with an empty value</li> 128 * <li>A parameter was supplied whose name does not correspond 129 * to any parameter name defined by the specified query</li> 130 * <li>Two parameters are supplied having the same name</li> 131 * <li>Any other constraint imposed by the specified query is 132 * violated. Such constraints may include restrictions on the 133 * range of values permitted for a given parameter, requirements 134 * that two or more parameters be mutually exclusive or must be 135 * supplied together, and so on. The specific constraints 136 * imposed by a given query are specified in the documentation 137 * for that query.</li> 138 * </ul> 139 */ 140 public void subscribe(String queryName, QueryParams params, String dest, SubscriptionControls controls, 141 String subscriptionID) throws NoSuchNameExceptionResponse, InvalidURIExceptionResponse, 142 DuplicateSubscriptionExceptionResponse, QueryParameterExceptionResponse, QueryTooComplexExceptionResponse, 143 SubscriptionControlsExceptionResponse, SubscribeNotPermittedExceptionResponse, SecurityExceptionResponse, 144 ValidationExceptionResponse, ImplementationExceptionResponse; 145 146 /** 147 * Removes a previously registered subscription having the specified 148 * <code>subscriptionID</code>. 149 * 150 * @param subscriptionID 151 * The <code>subscriptionID</code> of a previously registered 152 * subscription. 153 */ 154 public void unsubscribe(String subscriptionID) throws NoSuchSubscriptionExceptionResponse, 155 SecurityExceptionResponse, ValidationExceptionResponse, ImplementationExceptionResponse; 156 157 /** 158 * Invokes a previously defined query having the specified name, returning 159 * the results. The <code>params</code> argument provides the values to be 160 * used for any named parameters defined by the query. 161 * 162 * @param queryName 163 * The name of a previously defined query to be invoked. 164 * @param params 165 * Provides the values to be used for any named parameters 166 * defined by the query. 167 * @return The results of the query invocation. 168 * @throws QueryParameterException 169 * Under any of the following circumstances: 170 * <ul> 171 * <li>A parameter required by the specified query was omitted 172 * or was supplied with an empty value</li> 173 * <li>A parameter was supplied whose name does not correspond 174 * to any parameter name defined by the specified query</li> 175 * <li>Two parameters are supplied having the same name</li> 176 * <li>Any other constraint imposed by the specified query is 177 * violated. Such constraints may include restrictions on the 178 * range of values permitted for a given parameter, requirements 179 * that two or more parameters be mutually exclusive or must be 180 * supplied together, and so on. The specific constraints 181 * imposed by a given query are specified in the documentation 182 * for that query.</li> 183 * </ul> 184 */ 185 public QueryResults poll(String queryName, QueryParams params) throws NoSuchNameExceptionResponse, 186 QueryParameterExceptionResponse, QueryTooComplexExceptionResponse, QueryTooLargeExceptionResponse, 187 SecurityExceptionResponse, ValidationExceptionResponse, ImplementationExceptionResponse; 188 189 /** 190 * Returns a list of all query names available for use with the subscribe 191 * and poll methods. This includes all pre-defined queries provided by the 192 * implementation, including those specified in the EPCIS standard in 193 * Section 8.2.7. 194 * 195 * @return A list of all query names available for use with the subscribe 196 * and poll methods. 197 */ 198 public List<String> getQueryNames() throws SecurityExceptionResponse, ValidationExceptionResponse, 199 ImplementationExceptionResponse; 200 201 /** 202 * Returns a list of all <code>subscriptionID</code>s currently 203 * subscribed to the specified named query. 204 * 205 * @param queryName 206 * The name of a previously defined query for which the 207 * <code>subscriptionID</code>s should be returned. 208 * @return A list of all <code>subscriptionID</code>s currently 209 * subscribed to the specified named query. 210 */ 211 public List<String> getSubscriptionIDs(String queryName) throws NoSuchNameExceptionResponse, 212 SecurityExceptionResponse, ValidationExceptionResponse, ImplementationExceptionResponse; 213 214 /** 215 * Returns a string that identifies what version of the specification this 216 * implementation complies with. The possible values for this string are 217 * defined by EPCglobal. An implementation SHALL return a string 218 * corresponding to a version of this specification to which the 219 * implementation fully complies, and SHOULD return the string corresponding 220 * to the latest version to which it complies. To indicate compliance with 221 * this Version 1.0 of the EPCIS specification, the implementation SHALL 222 * return the string <code>1.0</code>. 223 * 224 * @return A string that identifies what version of the specification this 225 * implementation complies with. 226 */ 227 public String getStandardVersion() throws SecurityExceptionResponse, ValidationExceptionResponse, 228 ImplementationExceptionResponse; 229 230 /** 231 * Returns a string that identifies what vendor extensions this 232 * implementation provides. The possible values of this string and their 233 * meanings are vendor-defined, except that the empty string SHALL indicate 234 * that the implementation implements only standard functionality with no 235 * vendor extensions. When an implementation chooses to return a non-empty 236 * string, the value returned SHALL be a URI where the vendor is the owning 237 * authority. For example, this may be an HTTP URL whose authority portion 238 * is a domain name owned by the vendor, a URN having a URN namespace 239 * identifier issued to the vendor by IANA, an OID URN whose initial path is 240 * a Private Enterprise Number assigned to the vendor, etc. 241 * 242 * @return A string that identifies what vendor extensions this 243 * implementation provides. 244 */ 245 public String getVendorVersion() throws SecurityExceptionResponse, ValidationExceptionResponse, 246 ImplementationExceptionResponse; 247 }