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.capture;
22
23 import java.io.IOException;
24 import java.sql.Connection;
25 import java.sql.SQLException;
26 import java.sql.Timestamp;
27 import java.util.List;
28
29 import javax.sql.DataSource;
30
31 import org.fosstrak.epcis.model.BusinessTransactionType;
32 import org.fosstrak.epcis.repository.model.EventFieldExtension;
33
34 /**
35 * The CaptureOperationsBackend provides the persistence functionality required
36 * by the CaptureOperationsModule. It offers methods to store EPCIS events,
37 * vocabularies, or EPCs to the database; and provides a method to retrieve
38 * already existing vocabularies from the database. A CaptureOperationsSession
39 * object which holds the database connection is required to be passed into each
40 * of the methods.
41 *
42 * @author Marco Steybe
43 */
44 public interface CaptureOperationsBackend {
45
46 /**
47 * Runs the dbreset SQL script.
48 *
49 * @param dbconnection
50 * The JDBC Connection object.
51 * @param dbResetScript
52 * The filename of the SQL script to execute.
53 * @throws SQLException
54 * If an error with the database occurred.
55 * @throws IOException
56 * If an exception reading from the SQL script occurred.
57 */
58 public void dbReset(final Connection dbconnection, final String dbResetScript) throws SQLException, IOException;
59
60 /**
61 * Opens a new session for the database transaction.
62 *
63 * @param dataSource
64 * The DataSource object to retrieve the database connection
65 * from.
66 * @return A CaptureOperationsSession instantiated with the database
67 * connection retrieved from the given DataSource.
68 * @throws SQLException
69 * If an SQL error occurred.
70 */
71 public CaptureOperationsSession openSession(final DataSource dataSource) throws SQLException;
72
73 /**
74 * Inserts a new EPCIS object event into the database.
75 *
76 * @param session
77 * The database session.
78 * @param eventTime
79 * The event's 'eventTime' parameter.
80 * @param recordTime
81 * The event's 'recordTime' parameter.
82 * @param eventTimeZoneOffset
83 * The event's 'eventTimeZoneOffset' parameter.
84 * @param bizStepId
85 * The event's 'BusinessStepID' parameter.
86 * @param dispositionId
87 * The event's 'DispositionID' parameter.
88 * @param readPointId
89 * The event's 'ReadPointID' parameter.
90 * @param bizLocationId
91 * The event's 'BusinessLocationID' parameter.
92 * @param action
93 * The event's 'action' parameter.
94 * @return The database primary key of the inserted EPCIS object event.
95 * @throws SQLException
96 * If an SQL exception occurred.
97 */
98 public Long insertObjectEvent(final CaptureOperationsSession session, final Timestamp eventTime,
99 final Timestamp recordTime, final String eventTimeZoneOffset, final Long bizStepId,
100 final Long dispositionId, final Long readPointId, final Long bizLocationId, final String action)
101 throws SQLException;
102
103 /**
104 * Inserts a new EPCIS transaction event into the database.
105 *
106 * @param session
107 * The database session.
108 * @param eventTime
109 * The event's 'eventTime' parameter.
110 * @param recordTime
111 * The event's 'recordTime' parameter.
112 * @param eventTimeZoneOffset
113 * The event's 'eventTimeZoneOffset' parameter.
114 * @param bizStepId
115 * The event's 'BusinessStepID' parameter.
116 * @param dispositionId
117 * The event's 'DispositionID' parameter.
118 * @param readPointId
119 * The event's 'ReadPointID' parameter.
120 * @param bizLocationId
121 * The event's 'BusinessLocationID' parameter.
122 * @param action
123 * The event's 'action' parameter.
124 * @param parentId
125 * The event's 'ParentID' parameter.
126 * @return The database primary key of the inserted EPCIS transaction event.
127 * @throws SQLException
128 * If an SQL exception occurred.
129 */
130 public Long insertTransactionEvent(final CaptureOperationsSession session, final Timestamp eventTime,
131 final Timestamp recordTime, final String eventTimeZoneOffset, final Long bizStepId,
132 final Long dispositionId, final Long readPointId, final Long bizLocationId, final String action,
133 final String parentId) throws SQLException;
134
135 /**
136 * Inserts a new EPCIS aggregation event into the database.
137 *
138 * @param session
139 * The database session.
140 * @param eventTime
141 * The event's 'eventTime' parameter.
142 * @param recordTime
143 * The event's 'recordTime' parameter.
144 * @param eventTimeZoneOffset
145 * The event's 'eventTimeZoneOffset' parameter.
146 * @param bizStepId
147 * The event's 'BusinessStepID' parameter.
148 * @param dispositionId
149 * The event's 'DispositionID' parameter.
150 * @param readPointId
151 * The event's 'ReadPointID' parameter.
152 * @param bizLocationId
153 * The event's 'BusinessLocationID' parameter.
154 * @param action
155 * The event's 'action' parameter.
156 * @param parentId
157 * The event's 'ParentID' parameter.
158 * @return The database primary key of the inserted EPCIS aggregation event.
159 * @throws SQLException
160 * If an SQL exception occurred.
161 */
162 public Long insertAggregationEvent(final CaptureOperationsSession session, final Timestamp eventTime,
163 final Timestamp recordTime, final String eventTimeZoneOffset, final Long bizStepId,
164 final Long dispositionId, final Long readPointId, final Long bizLocationId, final String action,
165 final String parentId) throws SQLException;
166
167 /**
168 * Inserts a new EPCIS quantity event into the database.
169 *
170 * @param session
171 * The database session.
172 * @param eventTime
173 * The event's 'eventTime' parameter.
174 * @param recordTime
175 * The event's 'recordTime' parameter.
176 * @param eventTimeZoneOffset
177 * The event's 'eventTimeZoneOffset' parameter.
178 * @param bizStepId
179 * The event's 'BusinessStepID' parameter.
180 * @param dispositionId
181 * The event's 'DispositionID' parameter.
182 * @param readPointId
183 * The event's 'ReadPointID' parameter.
184 * @param bizLocationId
185 * The event's 'BusinessLocationID' parameter.
186 * @param epcClassId
187 * The event's 'EpcClassID' parameter.
188 * @param quantity
189 * The event's 'quantity' parameter.
190 * @return The database primary key of the inserted EPCIS quantity event.
191 * @throws SQLException
192 * If an SQL exception occurred.
193 */
194 public Long insertQuantityEvent(final CaptureOperationsSession session, final Timestamp eventTime,
195 final Timestamp recordTime, final String eventTimeZoneOffset, final Long bizStepId,
196 final Long dispositionId, final Long readPointId, final Long bizLocationId, final Long epcClassId,
197 final Long quantity) throws SQLException;
198
199 /**
200 * Inserts the given EPCs into the database and associates them with the
201 * EPCIS event with the given type and ID (primary key).
202 *
203 * @param session
204 * The database session.
205 * @param eventId
206 * The ID (primary key) of the EPCIS event for which the EPCs
207 * should be inserted.
208 * @param eventType
209 * The type of the EPCIS event for which the EPCs should be
210 * inserted.
211 * @param epcs
212 * The List of EPCs to insert.
213 * @throws SQLException
214 * If an SQL error occurred.
215 */
216 public void insertEpcsForEvent(final CaptureOperationsSession session, final long eventId, final String eventType,
217 final List<String> epcs) throws SQLException;
218
219 /**
220 * Retrieves the ID (primary key) of the vocabulary with the given type that
221 * matches the given URI string. If no vocabulary element with the given URI
222 * exists, <code>null</code> will be returned.
223 *
224 * @param session
225 * The database session.
226 * @param vocabularyType
227 * The type of the vocabulary to retrieve. The type determines
228 * from which database table name the primary key will be
229 * retrieved.
230 * @param vocabularyElement
231 * The URI string of the vocabulary element to retrieve.
232 * @return The ID (primary key) of the matching vocabulary element, or
233 * <code>null</code> if none was found.
234 * @throws SQLException
235 * If an SQL error occurred.
236 */
237 public Long getVocabularyElement(final CaptureOperationsSession session, final String vocabularyType,
238 final String vocabularyElement) throws SQLException;
239
240 /**
241 * Inserts the vocabulary of the given type and the given vocabulary element
242 * URI into the database.
243 *
244 * @param session
245 * The database session.
246 * @param vocabularyType
247 * The type of the vocabulary to insert. The type determines to
248 * which database table name the vocabulary will be inserted.
249 * @param vocabularyElement
250 * The URI string of the vocabulary element to insert.
251 * @return The ID (primary key) of the inserted vocabulary element.
252 * @throws SQLException
253 * If an SQL error occurred.
254 */
255 public Long insertVocabularyElement(final CaptureOperationsSession session, final String vocabularyType,
256 final String vocabularyElement) throws SQLException;
257
258 /**
259 * Inserts the BusinessTransactionType and the BusinessTransactionID into
260 * the BusinessTransaction-Table if necessary.
261 *
262 * @param session
263 * The database session.
264 * @param bizTrans
265 * The BusinessTransaction to be inserted.
266 * @param bizTransType
267 * The type of the business transaction to insert.
268 * @return The ID from the BusinessTransaction-table.
269 * @throws SQLException
270 * If an SQL problem with the database occurred.
271 */
272 public Long insertBusinessTransaction(final CaptureOperationsSession session, final String bizTrans,
273 final String bizTransType) throws SQLException;
274
275 public void insertBusinessTransactionsForEvent(final CaptureOperationsSession session, final long eventId,
276 final String eventType, final List<BusinessTransactionType> btts) throws SQLException;
277
278 public void insertExtensionFieldsForEvent(final CaptureOperationsSession session, final long eventId,
279 final String eventType, final List<EventFieldExtension> exts) throws SQLException;
280
281 }