001 /*
002 * DataStore.java
003 *
004 * Copyright (c) 1995-2010, The University of Sheffield. See the file
005 * COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
006 *
007 * This file is part of GATE (see http://gate.ac.uk/), and is free
008 * software, licenced under the GNU Library General Public License,
009 * Version 2, June 1991 (in the distribution as file licence.html,
010 * and also available at http://gate.ac.uk/gate/licence.html).
011 *
012 * Hamish Cunningham, 11/Feb/2000
013 *
014 * $Id: DataStore.java 12006 2009-12-01 17:24:28Z thomas_heitz $
015 */
016
017 package gate;
018
019 import java.util.List;
020
021 import gate.event.DatastoreListener;
022 import gate.persist.PersistenceException;
023 import gate.security.*;
024 import gate.security.SecurityException;
025 import gate.util.FeatureBearer;
026 import gate.util.NameBearer;
027
028 /** Models all sorts of data storage.
029 */
030 public interface DataStore extends FeatureBearer, NameBearer {
031
032 public static final String DATASTORE_FEATURE_NAME = "DataStore";
033 public static final String LR_ID_FEATURE_NAME = "LRPersistenceId";
034
035
036 /** Set the URL as string for the underlying storage mechanism. */
037 public void setStorageUrl(String storageUrl) throws PersistenceException;
038
039 /** Get the URL as String for the underlying storage mechanism. */
040 public String getStorageUrl();
041
042 /**
043 * Create a new data store. <B>NOTE:</B> for some data stores
044 * creation is an system administrator task; in such cases this
045 * method will throw an UnsupportedOperationException.
046 */
047 public void create()
048 throws PersistenceException, UnsupportedOperationException;
049
050 /** Open a connection to the data store. */
051 public void open() throws PersistenceException;
052
053 /** Close the data store. */
054 public void close() throws PersistenceException;
055
056 /**
057 * Delete the data store. <B>NOTE:</B> for some data stores
058 * deletion is an system administrator task; in such cases this
059 * method will throw an UnsupportedOperationException.
060 */
061 public void delete()
062 throws PersistenceException, UnsupportedOperationException;
063
064 /**
065 * Delete a resource from the data store.
066 * @param lrId a data-store specific unique identifier for the resource
067 * @param lrClassName class name of the type of resource
068 */
069 public void delete(String lrClassName, Object lrId)
070 throws PersistenceException,SecurityException;
071
072 /**
073 * Save: synchonise the in-memory image of the LR with the persistent
074 * image.
075 */
076 public void sync(LanguageResource lr)
077 throws PersistenceException,SecurityException;
078
079 /**
080 * Set method for the autosaving behaviour of the data store.
081 * <B>NOTE:</B> many types of datastore have no auto-save function,
082 * in which case this will throw an UnsupportedOperationException.
083 */
084 public void setAutoSaving(boolean autoSaving)
085 throws UnsupportedOperationException,PersistenceException;
086
087 /** Get the autosaving behaviour of the LR. */
088 public boolean isAutoSaving();
089
090 /** Adopt a resource for persistence. */
091 public LanguageResource adopt(LanguageResource lr, SecurityInfo secInfo)
092 throws PersistenceException, gate.security.SecurityException;
093
094 /**
095 * Get a resource from the persistent store.
096 * <B>Don't use this method - use Factory.createResource with
097 * DataStore and DataStoreInstanceId parameters set instead.</B>
098 */
099 LanguageResource getLr(String lrClassName, Object lrId)
100 throws PersistenceException,SecurityException;
101
102 /** Get a list of the types of LR that are present in the data store. */
103 public List getLrTypes() throws PersistenceException;
104
105 /** Get a list of the IDs of LRs of a particular type that are present. */
106 public List getLrIds(String lrType) throws PersistenceException;
107
108 /** Get a list of the names of LRs of a particular type that are present. */
109 public List getLrNames(String lrType) throws PersistenceException;
110
111 /** Get a list of LRs that satisfy some set or restrictions */
112 public List findLrIds(List constraints) throws PersistenceException;
113
114 /**
115 * Get a list of LRs that satisfy some set or restrictions and are
116 * of a particular type
117 */
118 public List findLrIds(List constraints, String lrType) throws PersistenceException;
119
120 /** Get the name of an LR from its ID. */
121 public String getLrName(Object lrId) throws PersistenceException;
122
123 /**
124 * Registers a new {@link gate.event.DatastoreListener} with this datastore
125 */
126 public void addDatastoreListener(DatastoreListener l);
127
128 /**
129 * Removes a a previously registered {@link gate.event.DatastoreListener}
130 * from the list listeners for this datastore
131 */
132 public void removeDatastoreListener(DatastoreListener l);
133
134 /**
135 * Returns the name of the icon to be used when this datastore is displayed
136 * in the GUI
137 */
138 public String getIconName();
139
140 /**
141 * Returns the comment displayed by the GUI for this DataStore
142 */
143 public String getComment();
144
145
146 /**
147 * Checks if the user (identified by the sessionID)
148 * has read access to the LR
149 */
150 public boolean canReadLR(Object lrID)
151 throws PersistenceException, gate.security.SecurityException;
152
153 /**
154 * Checks if the user (identified by the sessionID)
155 * has write access to the LR
156 */
157 public boolean canWriteLR(Object lrID)
158 throws PersistenceException, gate.security.SecurityException;
159
160 /** get security information for LR . */
161 public SecurityInfo getSecurityInfo(LanguageResource lr)
162 throws PersistenceException;
163
164 /** set security information for LR . */
165 public void setSecurityInfo(LanguageResource lr,SecurityInfo si)
166 throws PersistenceException, gate.security.SecurityException;
167
168 /** identify user using this datastore */
169 public void setSession(Session s)
170 throws gate.security.SecurityException;
171
172 /** identify user using this datastore */
173 public Session getSession(Session s)
174 throws gate.security.SecurityException;
175
176 /**
177 * Try to acquire exlusive lock on a resource from the persistent store.
178 * Always call unlockLR() when the lock is no longer needed
179 */
180 public boolean lockLr(LanguageResource lr)
181 throws PersistenceException,SecurityException;
182
183 /**
184 * Releases the exlusive lock on a resource from the persistent store.
185 */
186 public void unlockLr(LanguageResource lr)
187 throws PersistenceException,SecurityException;
188
189
190 } // interface DataStore
|