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.queryclient;
22
23 import java.util.List;
24
25 import org.fosstrak.epcis.model.Poll;
26 import org.fosstrak.epcis.model.QueryResults;
27 import org.fosstrak.epcis.model.Subscribe;
28 import org.fosstrak.epcis.soap.DuplicateSubscriptionExceptionResponse;
29 import org.fosstrak.epcis.soap.ImplementationExceptionResponse;
30 import org.fosstrak.epcis.soap.InvalidURIExceptionResponse;
31 import org.fosstrak.epcis.soap.NoSuchNameExceptionResponse;
32 import org.fosstrak.epcis.soap.NoSuchSubscriptionExceptionResponse;
33 import org.fosstrak.epcis.soap.QueryParameterExceptionResponse;
34 import org.fosstrak.epcis.soap.QueryTooComplexExceptionResponse;
35 import org.fosstrak.epcis.soap.QueryTooLargeExceptionResponse;
36 import org.fosstrak.epcis.soap.SecurityExceptionResponse;
37 import org.fosstrak.epcis.soap.SubscribeNotPermittedExceptionResponse;
38 import org.fosstrak.epcis.soap.SubscriptionControlsExceptionResponse;
39 import org.fosstrak.epcis.soap.ValidationExceptionResponse;
40
41 /**
42 * @author Marco Steybe
43 */
44 public interface QueryControlInterface {
45
46 /**
47 * Performs a poll operation at the repository's Query Controls Module.
48 *
49 * @param poll
50 * The Poll object including the query name and parameters to be
51 * executed.
52 * @return The QueryResults.
53 * @throws QueryParameterExceptionResponse
54 * @throws NoSuchNameExceptionResponse
55 * @throws ValidationExceptionResponse
56 * @throws SecurityExceptionResponse
57 * @throws QueryTooLargeExceptionResponse
58 * @throws QueryTooComplexExceptionResponse
59 * @throws ImplementationExceptionResponse
60 */
61 QueryResults poll(final Poll poll) throws ImplementationExceptionResponse, QueryTooComplexExceptionResponse,
62 QueryTooLargeExceptionResponse, SecurityExceptionResponse, ValidationExceptionResponse,
63 NoSuchNameExceptionResponse, QueryParameterExceptionResponse;
64
65 /**
66 * Performs a subscribe operation at the repository's Query Controls Module,
67 * i.e. subscribes a query for later execution.
68 *
69 * @param subscribe
70 * The Subscribe object including the query name, the parameters,
71 * and subscription id used for subscribing the query.
72 * @throws QueryParameterExceptionResponse
73 * @throws SubscriptionControlsExceptionResponse
74 * @throws NoSuchNameExceptionResponse
75 * @throws SubscribeNotPermittedExceptionResponse
76 * @throws ValidationExceptionResponse
77 * @throws InvalidURIExceptionResponse
78 * @throws SecurityExceptionResponse
79 * @throws QueryTooComplexExceptionResponse
80 * @throws ImplementationExceptionResponse
81 * @throws DuplicateSubscriptionExceptionResponse
82 */
83 void subscribe(final Subscribe subscribe) throws DuplicateSubscriptionExceptionResponse,
84 ImplementationExceptionResponse, QueryTooComplexExceptionResponse, SecurityExceptionResponse,
85 InvalidURIExceptionResponse, ValidationExceptionResponse, SubscribeNotPermittedExceptionResponse,
86 NoSuchNameExceptionResponse, SubscriptionControlsExceptionResponse, QueryParameterExceptionResponse;
87
88 /**
89 * Perform an unsubscribe operation at the repository's Query Controls
90 * Module, i.e. unsubscribes a previously subscribed query.
91 *
92 * @param subscriptionId
93 * The ID of the query to be unsubscribed.
94 * @throws NoSuchSubscriptionExceptionResponse
95 * @throws ValidationExceptionResponse
96 * @throws SecurityExceptionResponse
97 * @throws ImplementationExceptionResponse
98 */
99 void unsubscribe(final String subscriptionId) throws ImplementationExceptionResponse, SecurityExceptionResponse,
100 ValidationExceptionResponse, NoSuchSubscriptionExceptionResponse;
101
102 /**
103 * Retrieves the names of queries that can be coped with.
104 *
105 * @return A List of query names.
106 * @throws ValidationExceptionResponse
107 * @throws SecurityExceptionResponse
108 */
109 List<String> getQueryNames() throws ImplementationExceptionResponse, SecurityExceptionResponse,
110 ValidationExceptionResponse;
111
112 /**
113 * Retrieves the ID of a subscribed query.
114 *
115 * @param queryName
116 * The name of the query.
117 * @return A List of IDs.
118 * @throws NoSuchNameExceptionResponse
119 * @throws ValidationExceptionResponse
120 * @throws SecurityExceptionResponse
121 * @throws ImplementationExceptionResponse
122 */
123 List<String> getSubscriptionIds(final String queryName) throws ImplementationExceptionResponse,
124 SecurityExceptionResponse, ValidationExceptionResponse, NoSuchNameExceptionResponse;
125
126 /**
127 * Retrieves the standard version implemented by this implementation.
128 *
129 * @return The implemented standard version.
130 * @throws ValidationExceptionResponse
131 * @throws SecurityExceptionResponse
132 * @throws ImplementationExceptionResponse
133 */
134 String getStandardVersion() throws ImplementationExceptionResponse, SecurityExceptionResponse,
135 ValidationExceptionResponse;
136
137 /**
138 * Retrieves the vendor version.
139 *
140 * @return The vendor version.
141 * @throws ValidationExceptionResponse
142 * @throws SecurityExceptionResponse
143 * @throws ImplementationExceptionResponse
144 */
145 String getVendorVersion() throws ImplementationExceptionResponse, SecurityExceptionResponse,
146 ValidationExceptionResponse;
147 }