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.query;
22
23 import java.sql.SQLException;
24 import java.util.List;
25 import java.util.Map;
26
27 import javax.sql.DataSource;
28
29 import org.fosstrak.epcis.model.QueryParams;
30 import org.fosstrak.epcis.model.SubscriptionControls;
31 import org.fosstrak.epcis.model.VocabularyType;
32 import org.fosstrak.epcis.soap.ImplementationExceptionResponse;
33 import org.fosstrak.epcis.soap.QueryTooLargeExceptionResponse;
34
35 /**
36 * The QueryOperationsBackend provides the persistence functionality required by
37 * the QueryOperationsModule. It offers methods to manage query subscriptions
38 * and methods to execute EPCIS queries, i.e., simple event and masterdata
39 * queries. A QueryOperationsSession object which holds the database connection
40 * is required to be passed into each of the methods.
41 *
42 * @author Marco Steybe
43 */
44 public interface QueryOperationsBackend {
45
46 /**
47 * Executes a simple event query with the parameters given in the
48 * SimpleEventQueryDTO. The resulting event list will be available in the
49 * given <code>eventList</code> parameter.
50 *
51 * @param session
52 * The QueryOperationsSession wrapping a database connection.
53 * @param seQuery
54 * The SimpleEventQueryDTO containing the query parameters from
55 * which the database query will be constructed.
56 * @param eventList
57 * A List of events matching the given query parameters.
58 * @throws SQLException
59 * If an error with the database occurred.
60 * @throws ImplementationExceptionResponse
61 * If an implementation specific error occurred.
62 * @throws QueryTooLargeExceptionResponse
63 * If the query is too large to be executed.
64 */
65 public void runSimpleEventQuery(final QueryOperationsSession session, final SimpleEventQueryDTO seQuery,
66 final List<Object> eventList) throws SQLException, ImplementationExceptionResponse,
67 QueryTooLargeExceptionResponse;
68
69 /**
70 * Executes a masterdata query with the parameters given in the
71 * MasterDataQueryDTO. The resulting vocabulary list will be available in
72 * the given <code>vocList</code> parameter.
73 *
74 * @param session
75 * The QueryOperationsSession wrapping a database connection.
76 * @param mdQuery
77 * The MasterDataQueryDTO containing the query parameters from
78 * which the database query will be constructed.
79 * @param vocList
80 * A List of vocabularies matching the given query parameters.
81 * @throws SQLException
82 * If an error with the database occurred.
83 * @throws ImplementationExceptionResponse
84 * If an implementation specific error occurred.
85 * @throws QueryTooLargeExceptionResponse
86 * If the query is too large to be executed.
87 */
88 public void runMasterDataQuery(final QueryOperationsSession session, final MasterDataQueryDTO mdQuery,
89 final List<VocabularyType> vocList) throws SQLException, ImplementationExceptionResponse,
90 QueryTooLargeExceptionResponse;
91
92 /**
93 * Checks if the given subscription ID already exists.
94 *
95 * @param session
96 * The QueryOperationsSession wrapping a database connection.
97 * @param subscriptionID
98 * The subscription ID to be checked.
99 * @return <code>true</code> if the given subscription ID already exists,
100 * <code>false</code> otherwise.
101 * @throws SQLException
102 * If an error with the database occurred.
103 */
104 public boolean fetchExistsSubscriptionId(final QueryOperationsSession session, final String subscriptionID)
105 throws SQLException;
106
107 /**
108 * Fetches all query subscription held in the database, starts them again
109 * and stores everything in a HasMap.
110 *
111 * @param session
112 * The QueryOperationsSession wrapping a database connection.
113 * @return A Map mapping query names to scheduled query subscriptions.
114 * @throws SQLException
115 * If an error with the database occurred.
116 * @throws ImplementationExceptionResponse
117 * If an implementation specific error occurred.
118 */
119 public Map<String, QuerySubscriptionScheduled> fetchSubscriptions(final QueryOperationsSession session)
120 throws SQLException, ImplementationExceptionResponse;
121
122 /**
123 * Stores a query subscription with the given parameters to the database.
124 *
125 * @param session
126 * The QueryOperationsSession wrapping a database connection.
127 * @param queryParams
128 * @param dest
129 * @param subscrId
130 * @param controls
131 * @param trigger
132 * @param newSubscription
133 * @param queryName
134 * @param schedule
135 * @throws SQLException
136 * If an error with the database occurred.
137 * @throws ImplementationExceptionResponse
138 * If an implementation specific error occurred.
139 */
140 public void storeSupscriptions(final QueryOperationsSession session, QueryParams queryParams, String dest,
141 String subscrId, SubscriptionControls controls, String trigger, QuerySubscriptionScheduled newSubscription,
142 String queryName, Schedule schedule) throws SQLException, ImplementationExceptionResponse;
143
144 /**
145 * Deletes a query subscription from the database.
146 *
147 * @param session
148 * The QueryOperationsSession wrapping a database connection.
149 * @param subscrId
150 * The ID of the subscription to delete.
151 * @throws SQLException
152 * If an error with the database occurred.
153 */
154 public void deleteSubscription(final QueryOperationsSession session, String subscrId) throws SQLException;
155
156 /**
157 * Opens a new session for the database transaction.
158 *
159 * @param dataSource
160 * The DataSource object to retrieve the database connection
161 * from.
162 * @return A QueryOperationsSession instantiated with the database
163 * connection retrieved from the given DataSource.
164 * @throws SQLException
165 * If an error with the database occurred.
166 */
167 public QueryOperationsSession openSession(final DataSource dataSource) throws SQLException;
168
169 }