| DataStore.java |
1 /*
2 * DataStore.java
3 *
4 * Copyright (c) 1998-2005, The University of Sheffield.
5 *
6 * This file is part of GATE (see http://gate.ac.uk/), and is free
7 * software, licenced under the GNU Library General Public License,
8 * Version 2, June 1991 (in the distribution as file licence.html,
9 * and also available at http://gate.ac.uk/gate/licence.html).
10 *
11 * Hamish Cunningham, 11/Feb/2000
12 *
13 * $Id: DataStore.java,v 1.30 2005/01/11 13:51:30 ian Exp $
14 */
15
16 package gate;
17
18 import java.util.List;
19
20 import gate.event.DatastoreListener;
21 import gate.persist.PersistenceException;
22 import gate.security.*;
23 import gate.security.SecurityException;
24 import gate.util.FeatureBearer;
25 import gate.util.NameBearer;
26
27 /** Models all sorts of data storage.
28 */
29 public interface DataStore extends FeatureBearer, NameBearer {
30
31 public static final String DATASTORE_FEATURE_NAME = "DataStore";
32 public static final String LR_ID_FEATURE_NAME = "LRPersistenceId";
33
34
35 /** Set the URL as string for the underlying storage mechanism. */
36 public void setStorageUrl(String storageUrl) throws PersistenceException;
37
38 /** Get the URL as String for the underlying storage mechanism. */
39 public String getStorageUrl();
40
41 /**
42 * Create a new data store. <B>NOTE:</B> for some data stores
43 * creation is an system administrator task; in such cases this
44 * method will throw an UnsupportedOperationException.
45 */
46 public void create()
47 throws PersistenceException, UnsupportedOperationException;
48
49 /** Open a connection to the data store. */
50 public void open() throws PersistenceException;
51
52 /** Close the data store. */
53 public void close() throws PersistenceException;
54
55 /**
56 * Delete the data store. <B>NOTE:</B> for some data stores
57 * deletion is an system administrator task; in such cases this
58 * method will throw an UnsupportedOperationException.
59 */
60 public void delete()
61 throws PersistenceException, UnsupportedOperationException;
62
63 /**
64 * Delete a resource from the data store.
65 * @param lrId a data-store specific unique identifier for the resource
66 * @param lrClassName class name of the type of resource
67 */
68 public void delete(String lrClassName, Object lrId)
69 throws PersistenceException,SecurityException;
70
71 /**
72 * Save: synchonise the in-memory image of the LR with the persistent
73 * image.
74 */
75 public void sync(LanguageResource lr)
76 throws PersistenceException,SecurityException;
77
78 /**
79 * Set method for the autosaving behaviour of the data store.
80 * <B>NOTE:</B> many types of datastore have no auto-save function,
81 * in which case this will throw an UnsupportedOperationException.
82 */
83 public void setAutoSaving(boolean autoSaving)
84 throws UnsupportedOperationException,PersistenceException;
85
86 /** Get the autosaving behaviour of the LR. */
87 public boolean isAutoSaving();
88
89 /** Adopt a resource for persistence. */
90 public LanguageResource adopt(LanguageResource lr, SecurityInfo secInfo)
91 throws PersistenceException, gate.security.SecurityException;
92
93 /**
94 * Get a resource from the persistent store.
95 * <B>Don't use this method - use Factory.createResource with
96 * DataStore and DataStoreInstanceId parameters set instead.</B>
97 */
98 LanguageResource getLr(String lrClassName, Object lrId)
99 throws PersistenceException,SecurityException;
100
101 /** Get a list of the types of LR that are present in the data store. */
102 public List getLrTypes() throws PersistenceException;
103
104 /** Get a list of the IDs of LRs of a particular type that are present. */
105 public List getLrIds(String lrType) throws PersistenceException;
106
107 /** Get a list of the names of LRs of a particular type that are present. */
108 public List getLrNames(String lrType) throws PersistenceException;
109
110 /** Get a list of LRs that satisfy some set or restrictions */
111 public List findLrIds(List constraints) throws PersistenceException;
112
113 /**
114 * Get a list of LRs that satisfy some set or restrictions and are
115 * of a particular type
116 */
117 public List findLrIds(List constraints, String lrType) throws PersistenceException;
118
119 /** Get the name of an LR from its ID. */
120 public String getLrName(Object lrId) throws PersistenceException;
121
122 /**
123 * Registers a new {@link gate.event.DatastoreListener} with this datastore
124 */
125 public void addDatastoreListener(DatastoreListener l);
126
127 /**
128 * Removes a a previously registered {@link gate.event.DatastoreListener}
129 * from the list listeners for this datastore
130 */
131 public void removeDatastoreListener(DatastoreListener l);
132
133 /**
134 * Returns the name of the icon to be used when this datastore is displayed
135 * in the GUI
136 */
137 public String getIconName();
138
139 /**
140 * Returns the comment displayed by the GUI for this DataStore
141 */
142 public String getComment();
143
144
145 /**
146 * Checks if the user (identified by the sessionID)
147 * has read access to the LR
148 */
149 public boolean canReadLR(Object lrID)
150 throws PersistenceException, gate.security.SecurityException;
151
152 /**
153 * Checks if the user (identified by the sessionID)
154 * has write access to the LR
155 */
156 public boolean canWriteLR(Object lrID)
157 throws PersistenceException, gate.security.SecurityException;
158
159 /** get security information for LR . */
160 public SecurityInfo getSecurityInfo(LanguageResource lr)
161 throws PersistenceException;
162
163 /** set security information for LR . */
164 public void setSecurityInfo(LanguageResource lr,SecurityInfo si)
165 throws PersistenceException, gate.security.SecurityException;
166
167 /** identify user using this datastore */
168 public void setSession(Session s)
169 throws gate.security.SecurityException;
170
171 /** identify user using this datastore */
172 public Session getSession(Session s)
173 throws gate.security.SecurityException;
174
175 /**
176 * Try to acquire exlusive lock on a resource from the persistent store.
177 * Always call unlockLR() when the lock is no longer needed
178 */
179 public boolean lockLr(LanguageResource lr)
180 throws PersistenceException,SecurityException;
181
182 /**
183 * Releases the exlusive lock on a resource from the persistent store.
184 */
185 public void unlockLr(LanguageResource lr)
186 throws PersistenceException,SecurityException;
187
188
189 } // interface DataStore
190