Source code: alice/tuplemedium/TupleSet.java
1 /*
2 * Tuple Centre media - Copyright (C) 2001 deis.unibo.it
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 */
18 package alice.tuplemedium;
19 import java.util.*;
20
21 /**
22 * Specifies the services which must be provided by the component
23 * inside the tuple centre virtual machine collecting and managing
24 * tuples as a multiset
25 *
26 * An important aspect of the component implementing this interface
27 * is the ability to execute transactions, that is execute sequence
28 * of operations that could be commited or asked to be undone.
29 *
30 * @see Tuple
31 * @see TupleTemplate
32 * @see TupleCentreVM
33 *
34 * @author <a href="mailto:aricci@deis.unibo.it">Alessandro Ricci</a>
35 * @version 1.0
36 */
37 public interface TupleSet extends java.io.Serializable {
38
39 /**
40 * Adds a tuple to the multiset
41 *
42 * @param t the tuple to be added
43 */
44 void add(Tuple t);
45
46 /**
47 * Removes a tuple to the multiset
48 *
49 * @param t the tuple to be removed
50 */
51 void sub(Tuple t);
52
53 /**
54 * Gets the number of tuples inside the multiset
55 *
56 * @returns the size of the multiset
57 */
58 int size();
59
60 /**
61 * Tests if the multiset is empty
62 */
63 boolean isEmpty();
64
65 /**
66 * Empties the multiset
67 */
68 void empty();
69
70 /**
71 * Begins a transaction section
72 *
73 * Every operation on multiset can be undone
74 */
75 void beginTransaction();
76
77 /**
78 * Ends a transaction section specifying
79 * if operations must be committed or undone
80 *
81 * @param commit if <code>true</code> the operations are committed, else
82 * they are undone and the multiset is rolled back to the
83 * state before the <code>beginTransaction</code> invocation
84 */
85 void endTransaction(boolean commit);
86
87 /**
88 * Gets (and removes) non-deterministically a tuple of the multiset
89 * matching the template specified
90 *
91 * @param t the tuple template to be used for the matching
92 * @return a tuple matching the template or null if no tuples found
93 */
94 Tuple getMatchingTuple(TupleTemplate t);
95
96 /**
97 * Gets (wtihout removal) non-deterministically a tuple of the multiset
98 * matching the template specified
99 *
100 * @param t the tuple template to be used for the matching
101 * @return a tuple matching the template or null if no tuples found
102 */
103 Tuple readMatchingTuple(TupleTemplate t);
104
105 /**
106 * Checks if exists a tuple inside the tuple set matching the template
107 *
108 * @param t the tuple template to be used for the matching
109 * @return <code>true</code> if a masching is found, <code>false</code> otherwise
110 */
111 boolean hasMatchingTuple(TupleTemplate t);
112
113 /**
114 * Gets an iterator to navigate through tuples of the multiset
115 *
116 * @return the iterator
117 */
118 Iterator getIterator();
119 }
120