1 /*****************************************************************************/
2
3
4
5
6
7
8
9 /*****************************************************************************/
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36 /*****************************************************************************/
37 package org.xvsm.interfaces;
38
39 import java.net.URI;
40 import java.util.List;
41 import java.util.Properties;
42
43 import org.xvsm.core.ContainerRef;
44 import org.xvsm.core.Entry;
45 import org.xvsm.core.aspect.GlobalAspect;
46 import org.xvsm.core.aspect.IPoint;
47 import org.xvsm.core.aspect.LocalAspect;
48 import org.xvsm.core.aspect.LocalIPoint;
49 import org.xvsm.core.notifications.Operation;
50 import org.xvsm.internal.exceptions.XCoreException;
51 import org.xvsm.selectors.Selector;
52 import org.xvsm.transactions.Transaction;
53
54 /***
55 * This interface is the main entry point to the MozartSpaces core.
56 * <p>
57 * The methods in this interface can be used to create and destroy containers
58 * and read or write entries into containers.
59 *
60 * @author Christian Schreiber, Michael Proestler
61 * @version 16. 08. 2007
62 */
63 public interface ICapi {
64
65 /***
66 * Infinite Timeout. Might be used with Transactions, Read, Take, Write,
67 * Destroy Operations.
68 */
69 int INFINITE_TIMEOUT = -1;
70
71 /***
72 * Used to specify the maximal firing amount of notifications.
73 */
74 int INFINITE = -1;
75
76 /***
77 * Shuts down the running MozartSpaces core.
78 *
79 * @param site
80 * the {@link URI} of the remote core where the operation should
81 * be executed. If null, the embedded core will perform the
82 * operation.
83 * @param clearSpace
84 * true if the content of the space should be reset.
85 * @throws XCoreException
86 * if something went wrong during adding the aspect. see
87 * .getCause() for the reason
88 */
89 void shutdown(URI site, boolean clearSpace) throws XCoreException;
90
91 /***
92 * Clears the content of the space.
93 *
94 * @param site
95 * the {@link URI} of the remote core were the operation should
96 * be executed. If null, the embedded core will perform the
97 * operation.
98 * @throws XCoreException
99 * if something went wrong during adding the aspect. see
100 * .getCause() for the reason
101 */
102 void clearSpace(URI site) throws XCoreException;
103
104 /***
105 * Retrieves the container reference for a given name.
106 *
107 * @param tx
108 * the Transaction under which the operation will be performed.
109 * If <code>null</code>, the core will perform the operation.
110 * @param site
111 * the {@link URI} of the remote core were the operation should
112 * be executed. If null, the embedded core will perform the
113 * operation.
114 * @param containerName
115 * specifies the name of the container
116 * @throws XCoreException
117 * if something went wrong during adding the aspect. see
118 * .getCause() for the reason
119 * @return the ContainerRef of the named container
120 */
121 ContainerRef lookupContainer(Transaction tx, URI site, String containerName)
122 throws XCoreException;
123
124 /***
125 * Creates a new container in the space.
126 *
127 * specifies the basic coordination order.
128 *
129 * @param tx
130 * the Transaction under which the operation will be performed.If
131 * <code>null</code>, the core will perform the operation.
132 * @param site
133 * the {@link URI} of the remote core were the operation should
134 * be executed. If null, the embedded core will perform the
135 * operation.
136 * @param name
137 * the Name of the container or <code>null</code> for a unnamed
138 * container.
139 * @param size
140 * specifies the size and/or unboundedness of the container -1
141 * creates an unbounded container
142 * @param coordinators
143 * the coordinators for the new container. if the coordinators
144 * and the selectors do not have the same size
145 * IllegalArgumentException is thrown.
146 *
147 * @return the container reference for the new container.
148 * @throws XCoreException
149 * if something went wrong during adding the aspect. see
150 * .getCause() for the reason
151 */
152 ContainerRef createContainer(Transaction tx, URI site, String name,
153 int size, ICoordinator... coordinators) throws XCoreException;
154
155 public URI createNotification(ContainerRef cref,
156 final NotificationListener listener, Operation... operations);
157
158 /***
159 * Removes the specified container from the space.
160 *
161 * @param tx
162 * the Transaction under which the operation will be performed.If
163 * <code>null</code>, the core will perform the operation.
164 * @param cref
165 * reference to the container.
166 * @throws XCoreException
167 * if something went wrong during adding the aspect. see
168 * .getCause() for the reason
169 */
170 void destroyContainer(Transaction tx, ContainerRef cref)
171 throws XCoreException;
172
173 /***
174 * Reads entries from a container that are matched by the specified
175 * selectors.
176 * <p>
177 * The container is specified using its <Link>ContainerRef</Link>. A list
178 * of <Link>Selector</Link>s specifies which entries must be read. If the
179 * entries that are not available are selected the operation blocks.
180 *
181 * @param cref
182 * reference to the container.
183 * @param timeout
184 * the timeout used for blocking reads
185 * @param tx
186 * the Transaction under which the operation will be performed.If
187 * <code>null</code>, the core will perform the operation.
188 * @param sel
189 * list of selectors to determine which entries
190 *
191 * @throws XCoreException
192 * which can be narrowed to one of the following exceptions:
193 * <ul>
194 * <li>InvalidTransactionException thrown if the transaction
195 * has not been created with {@link ICapi#createTransaction()}
196 * or it already has been commited or rolled back.</li>
197 * <li> UnknownContainerException thrown if the cref is invalid.</li>
198 * </ul>
199 * @return the list of entries that were matched by the selectors.
200 */
201 @SuppressWarnings("unchecked")
202 Entry[] read(ContainerRef cref, long timeout, Transaction tx,
203 Selector... sel) throws XCoreException;
204
205 /***
206 *
207 * /** Takes entries from a container that are matched by the specified
208 * selectors.
209 * <p>
210 * The container is specified using its <Link>ContainerRef</Link>. A list
211 * of <Link>Selector</Link>s specifies which entries must be taken. Taking
212 * an entry from the container removes it from the container. If the entries
213 * that are not available are selected the operation blocks.
214 *
215 * @param cref
216 * reference to the container.
217 * @param timeout
218 * the timeout used for blocking takes
219 * @param sel
220 * list of selectors that specify the entries.
221 * @param tx
222 * the Transaction under which the operation will be performed.If
223 * <code>null</code>, the core will perform the operation.
224 *
225 * @throws XCoreException
226 * which can be narrowed to one of the following exceptions:
227 * <ul>
228 * <li>TimeoutExpiredException when the timeout of a blocking
229 * operation is expired.</li>
230 * <li>InvalidTransactionException thrown if the transaction
231 * has not been created with {@link ICapi#createTransaction()}
232 * or it already has been commited or rolled back.</li>
233 * <li> InvalidContainerException thrown if the cref is invalid.</li>
234 * </ul>
235 *
236 * @return the list of entries that were matched by the selectors.
237 */
238 @SuppressWarnings("unchecked")
239 Entry[] take(ContainerRef cref, long timeout, Transaction tx,
240 Selector... sel) throws XCoreException;
241
242 /***
243 * Removes entries from a container that are matched by the specified
244 * selectors.
245 * <p>
246 * The container is specified using its <Link>ContainerRef</Link>. A list
247 * of <Link>Selector</Link>s specifies which entries must be destroyed.
248 *
249 * @param cref
250 * reference to the container.
251 * @param timeout
252 * the timeout used for blocking detroys
253 * @param sel
254 * list of selectors that specify the entries.
255 * @param tx
256 * the Transaction under which the operation will be performed.If
257 * <code>null</code>, the core will perform the operation.
258 * @throws XCoreException
259 * which can be narrowed to one of the following exceptions:
260 * <ul>
261 * <li>TimeoutExpiredException when the timeout of a blocking
262 * operation is expired.</li>
263 * <li>InvalidTransactionException thrown if the transaction
264 * has not been created with {@link ICapi#createTransaction()}
265 * or it already has been commited or rolled back.</li>
266 * <li> InvalidContainerException thrown if the cref is invalid.</li>
267 * </ul>
268 */
269 void destroy(ContainerRef cref, long timeout, Transaction tx,
270 Selector... sel) throws XCoreException;
271
272 /***
273 * Writes a list of entries into a container that are matched by the
274 * specified selectors.
275 * <p>
276 * The container is specified using its <Link>ContainerRef</Link>. A list
277 * of <Link>Selector</Link>s specify the additional information that must
278 * be written (e.g.: a key or an index). If the container is full or the
279 * additional information is occupied (e.g.: the value for the specified key
280 * already exists), the operation blocks.
281 *
282 * @param cref
283 * the {@link ContainerRef} of the container were the entry
284 * should be stored.
285 * @param timeout
286 * the timeout used for blocking detroys
287 * @param entries
288 * the entries that must be written to the container.
289 * @param tx
290 * the Transaction under which the operation will be performed.If
291 * <code>null</code>, the core will perform the operation.
292 * @throws XCoreException
293 * which can be narrowed to one of the following exceptions:
294 * <ul>
295 * <li>TimeoutExpiredException when the timeout of a blocking
296 * operation is expired.</li>
297 * <li>InvalidTransactionException thrown if the transaction
298 * has not been created with {@link ICapi#createTransaction()}
299 * or it already has been commited or rolled back.</li>
300 * <li> InvalidContainerException thrown if the cref is invalid.</li>
301 * </ul>
302 */
303 @SuppressWarnings("unchecked")
304 void write(ContainerRef cref, long timeout, Transaction tx,
305 Entry... entries) throws XCoreException;
306
307 /***
308 * Writes a list of entries into a container without blocking that are
309 * matched by the specified selectors.
310 * <p>
311 * The container is specified using its <Link>ContainerRef</Link>. A list
312 * of <Link>Selector</Link>s specify the additional information that must
313 * be written (e.g.: a key or an index). If the container is full or the
314 * additional information is occupied (e.g.: the value for the specified key
315 * already exists), the existing entries are shifted out of the container.
316 *
317 * @param cref
318 * the {@link ContainerRef} of the container were the entry
319 * should be stored.
320 * @param entries
321 * list of entries that must be shifted into the container.
322 * @param tx
323 * the Transaction under which the operation will be performed.If
324 * <code>null</code>, the embedded core will perform the
325 * operation.
326 * @throws XCoreException
327 * which can be narrowed to one of the following exceptions:
328 * <ul>
329 * <li>InvalidTransactionException thrown if the transaction
330 * has not been created with {@link ICapi#createTransaction()}
331 * or it already has been commited or rolled back.</li>
332 * <li> InvalidContainerException thrown if the cref is invalid.</li>
333 * </ul>
334 */
335 @SuppressWarnings("unchecked")
336 void shift(ContainerRef cref, Transaction tx, Entry... entries)
337 throws XCoreException;
338
339 /***
340 * Create and start a transaction.
341 *
342 * @param site
343 * the {@link URI} of the remote core were the operation should
344 * be executed. If null, the embedded core will perform the
345 * operation.
346 * @param timeout
347 * the time this transaction stays alive. After
348 * <code>timeout</code> milliseconds a the transaction will be
349 * rolledback and each further use of the tx will cause an
350 * InvalidTransactionException.
351 * @throws XCoreException
352 * if something went wrong during adding the aspect. see
353 * .getCause() for the reason
354 * @return the newly created transaction.
355 */
356 Transaction createTransaction(URI site, long timeout) throws XCoreException;
357
358 /***
359 * Commit a transaction.
360 *
361 * @param txn
362 * the transaction to commit.
363 * @throws XCoreException
364 * which can be narrowed to one of the following exceptions:
365 * <ul>
366 * <li>InvalidTransactionException thrown if the transaction
367 * has not been created with {@link ICapi#createTransaction()}
368 * or it already has been commited or rolled back.</li>
369 * </ul>
370 */
371 void commitTransaction(Transaction txn) throws XCoreException;
372
373 /***
374 * Rollback a transaction.
375 *
376 * @param txn
377 * the transaction to rollback.
378 * @throws XCoreException
379 * which can be narrowed to one of the following exceptions:
380 * <ul>
381 * <li>InvalidTransactionException thrown if the transaction
382 * has not been created with {@link ICapi#createTransaction()}
383 * or it already has been commited or rolled back.</li>
384 * </ul>
385 */
386 void rollbackTransaction(Transaction txn) throws XCoreException;
387
388 /***
389 * Add a local aspect to a container.
390 *
391 * @param cref
392 * The {@link ContainerRef} where the aspect should be added.
393 * @param p
394 * The different integration points {@link LocalIPoint}.
395 *
396 * @param aspect
397 * The aspect itself.
398 * @return The uri of the aspect
399 * @throws XCoreException
400 * if something went wrong during adding the aspect. see
401 * .getCause() for the reason
402 */
403 URI addAspect(ContainerRef cref, List<LocalIPoint> p, LocalAspect aspect)
404 throws XCoreException;
405
406 /***
407 * Removes a local aspect.
408 *
409 * @param cref
410 * The {@link ContainerRef} where the aspect should be removed.
411 * @param p
412 * The {@link LocalIPoint} where the aspect should be removed.
413 * @param uri
414 * the uri of the aspect which shall be removed.
415 * @throws XCoreException
416 * if something went wrong during adding the aspect. see
417 * .getCause() for the reason
418 */
419 void removeAspect(ContainerRef cref, List<LocalIPoint> p, URI uri)
420 throws XCoreException;
421
422 /***
423 * Add a global aspect to a container. *
424 *
425 * @param site
426 * the {@link URI} of the remote core were the operation should
427 * be executed. If null, the embedded core will perform the
428 * operation.
429 * @param p
430 * The different integration points {@link LocalIPoint}.
431 *
432 * @param aspect
433 * The aspect itself.
434 * @return the uri of the aspect
435 * @throws XCoreException
436 * if something went wrong during adding the aspect. see
437 * .getCause() for the reason
438 */
439 URI addAspect(URI site, List<IPoint> p, GlobalAspect aspect)
440 throws XCoreException;
441
442 /***
443 * Removes a global aspect.
444 *
445 * @param site
446 * the {@link URI} of the remote core were the operation should
447 * bed. If null, the embedded core will perform the operation.
448 * @param p
449 * The {@link LocalIPoint} where the aspect should be removed.
450 * @param the
451 * uri of the aspect which shall be removed
452 * @throws XCoreException
453 * if something went wrong during adding the aspect. see
454 * .getCause() for the reason
455 *
456 */
457
458 void removeAspect(URI site, List<IPoint> p, URI uri) throws XCoreException;
459
460 /***
461 * Get the aspect properties.
462 *
463 * @return the aspectContext
464 * @throws XCoreException
465 * if something went wrong during adding the aspect. see
466 * .getCause() for the reason
467 */
468 Properties getAspectContext() throws XCoreException;
469
470 /***
471 * @param aspectContext
472 * the aspectContext to set
473 * @throws XCoreException
474 * if something went wrong during adding the aspect. see
475 * .getCause() for the reason
476 */
477 void setAspectContext(Properties aspectContext) throws XCoreException;
478
479 }