1 /**
2 * Copyright (c) 2011, University of Konstanz, Distributed Systems Group
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of the University of Konstanz nor the
13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19 * DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
20 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28 package org.treetank.api;
29
30 import java.util.concurrent.Future;
31
32 import org.treetank.access.conf.ResourceConfiguration;
33 import org.treetank.exception.TTException;
34 import org.treetank.exception.TTIOException;
35
36 /**
37 * Each <code>IStorage</code> contains multiple resources. To each resource, one {@link ISession} can be
38 * bound.
39 *
40 * Transactions can then be started from this instance. There can only be one {@link IBucketWriteTrx} at the
41 * time.
42 * However, multiple {@link IBucketReadTrx} can coexist concurrently:
43 *
44 * * <code>
45 * //Ensure, storage and resources are created
46 * final IStorage storage = Storage.openStorage(FILE);
47 * final ISession session =
48 * storage.getSession(new SessionConfiguration(RESOURCENAME, KEY));
49 * final IBucketReadTrx pRtx = session.beginBucketRtx(REVISION);
50 * final IBucketWriteTrx pWtx = session.beginBucketWtx();
51 * </code>
52 *
53 */
54 public interface ISession {
55
56 /**
57 * Deregisters a registered bucket transaction.
58 *
59 * @param pTrx
60 * to be deregistered.
61 * @return true if successful, false otherwise
62 */
63 boolean deregisterBucketTrx(final IBucketReadTrx pTrx) throws TTIOException;
64
65 /**
66 * Getting the resource configuration
67 *
68 * @return the config of the resource
69 */
70 ResourceConfiguration getConfig();
71
72 /**
73 * Getting the most recent version from the storage.
74 *
75 * @return the most recent version
76 */
77 long getMostRecentVersion() throws TTIOException;
78
79 /**
80 * Begin exclusive write transaction on the bucket layer
81 *
82 *
83 * @return a {@link IBucketReadTrx} instance
84 * @throws TTException
85 */
86 IBucketWriteTrx beginBucketWtx() throws TTException;
87
88 /**
89 * Begin exclusive write transaction on the bucket layer with fixed revisions.
90 *
91 * @param pRevToRepresent
92 * @return a {@link IBucketReadTrx} instance
93 * @throws TTException
94 */
95 IBucketWriteTrx beginBucketWtx(final long pRevToRepresent) throws TTException;
96
97 /**
98 * Begin exclusive read transaction on the bucket layer
99 *
100 * @param pRevKey
101 * revision key for the revision ask
102 * @return a {@link IBucketReadTrx} instance
103 * @throws TTException
104 */
105 IBucketReadTrx beginBucketRtx(final long pRevKey) throws TTException;
106
107 /**
108 * Safely close session and immediately release all resources. If there are
109 * running transactions, they will automatically be closed.
110 *
111 * This is an idempotent operation and does nothing if the session is
112 * already closed.
113 *
114 * @return true if successful, false otherwise
115 * @throws TTException
116 * If can't close session.
117 */
118 boolean close() throws TTException;
119
120 /**
121 * Truncating the resource where this {@link ISession} is bound to. Note that the session must be closed
122 * first.
123 *
124 * @return true if successful, false otherwise
125 * @throws TTException
126 * if anything weird happens.
127 */
128 boolean truncate() throws TTException;
129
130 /**
131 * Waiting and blocking for running commit. Necessary before new commits are triggered or new transactions
132 * are started.
133 *
134 * @throws TTIOException
135 * if something goes weird
136 */
137 void waitForRunningCommit() throws TTIOException;
138
139 /**
140 * Setting running commit to session.
141 *
142 * @param pRunningCommit
143 * to be set
144 */
145 void setRunningCommit(Future<Void> pRunningCommit);
146
147 }