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.io.File;
31
32 import org.treetank.access.conf.ResourceConfiguration;
33 import org.treetank.access.conf.SessionConfiguration;
34 import org.treetank.exception.TTException;
35 import org.treetank.exception.TTIOException;
36
37 /**
38 *
39 * This interface describes storage-instances handled by Treetank. A {@link IStorage} is a persistent place
40 * where all data is stored.
41 *
42 * Resources must be created within this {@link IStorage} with the help of {@link ResourceConfiguration}s.
43 *
44 *
45 * <code>
46 * //Creating the Storage
47 * Storage.createDatabase(new StorageConfiguration(FILE));
48 * final IStorage storage = Storage.openStorage(FILE);
49 *
50 * //Getting a ResourceConfiguration over Guice.
51 * storage.createResource(mResourceConfig);
52 *
53 * </code> The access to the data is done with the help of {@link ISession}s:
54 *
55 * <code>
56 * //Ensure, storage and resources are created
57 * final IStorage storage = Storage.openStorage(FILE);
58 * final ISession session =
59 * storage.getSession(new SessionConfiguration(RESOURCENAME, KEY));
60 * final IBucketReadTrx pRtx = session.beginBucketRtx(REVISION);
61 * final IBucketWriteTrx pWtx = session.beginBucketWtx();
62 * </code>
63 *
64 *
65 * @author Sebastian Graf, University of Konstanz
66 *
67 */
68 public interface IStorage {
69 /**
70 * Initialization of a resource. Since databases can consist out of several
71 * resources, those can be created within this method. This includes only the initialization, the
72 * creation of a suitable folder structure must take beforehand for example within the creation of
73 * properties.
74 * This is necessary because of Guice relying on completely provided structures for their data-backends.
75 *
76 * @param pResConf
77 * the config of the resource
78 * @return boolean with true if successful, false otherwise
79 * @throws TTIOException
80 * if anything happens while creating the resource
81 */
82 boolean createResource(final ResourceConfiguration pResConf) throws TTException;
83
84 /**
85 * Getting the session associated within this database.
86 *
87 * @param pSessionConf
88 * {@link SessionConfiguration} reference
89 * @throws TTException
90 * if can't get session
91 * @return the session
92 */
93 ISession getSession(final SessionConfiguration pSessionConf) throws TTException;
94
95 /**
96 * Truncating a resource. This includes the removal of all data stored
97 * within this resource.
98 *
99 * @param pResConf
100 * storing the name of the resource
101 * @throws TTException
102 * if anything weird happens
103 */
104 boolean truncateResource(final SessionConfiguration pResConf) throws TTException;
105
106 /**
107 * Is the resource within this database existing?
108 *
109 * @param pResourceName
110 * ot be checked
111 * @return true, if existing; false otherwise
112 */
113 boolean existsResource(final String pResourceName);
114
115 /**
116 * Listing all resources within this database.
117 *
118 * @return all resources
119 */
120 String[] listResources();
121
122 /**
123 * Getting the file location of this database.
124 *
125 * @return the File of this database
126 */
127 File getLocation();
128
129 /**
130 * Closing the database for further access.
131 *
132 * @return true if successful, false otherwise
133 * @throws TTException
134 * if anything happens within treetank.
135 */
136 boolean close() throws TTException;
137
138 }