DataStore.java
001 /*
002  *  DataStore.java
003  *
004  *  Copyright (c) 1995-2012, 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 17662 2014-03-14 16:19:05Z markagreenwood $
015  */
016 
017 package gate;
018 
019 import gate.event.DatastoreListener;
020 import gate.persist.PersistenceException;
021 import gate.util.FeatureBearer;
022 import gate.util.NameBearer;
023 
024 import java.util.List;
025 
026 /** Models all sorts of data storage.
027   */
028 public interface DataStore extends FeatureBearer, NameBearer {
029 
030   public static final String DATASTORE_FEATURE_NAME = "DataStore";
031   public static final String LR_ID_FEATURE_NAME = "LRPersistenceId";
032 
033 
034   /** Set the URL as string for the underlying storage mechanism. */
035   public void setStorageUrl(String storageUrlthrows PersistenceException;
036 
037   /** Get the URL as String for the underlying storage mechanism. */
038   public String getStorageUrl();
039 
040   /**
041    * Create a new data store. <B>NOTE:</B> for some data stores
042    * creation is an system administrator task; in such cases this
043    * method will throw an UnsupportedOperationException.
044    */
045   public void create()
046   throws PersistenceException, UnsupportedOperationException;
047 
048   /** Open a connection to the data store. */
049   public void open() throws PersistenceException;
050 
051   /** Close the data store. */
052   public void close() throws PersistenceException;
053 
054   /**
055    * Delete the data store. <B>NOTE:</B> for some data stores
056    * deletion is an system administrator task; in such cases this
057    * method will throw an UnsupportedOperationException.
058    */
059   public void delete()
060   throws PersistenceException, UnsupportedOperationException;
061 
062   /**
063    * Delete a resource from the data store.
064    @param lrId a data-store specific unique identifier for the resource
065    @param lrClassName class name of the type of resource
066    */
067   public void delete(String lrClassName, Object lrId)
068   throws PersistenceException,SecurityException;
069 
070   /**
071    * Save: synchonise the in-memory image of the LR with the persistent
072    * image.
073    */
074   public void sync(LanguageResource lr)
075   throws PersistenceException,SecurityException;
076 
077   /**
078    * Set method for the autosaving behaviour of the data store.
079    <B>NOTE:</B> many types of datastore have no auto-save function,
080    * in which case this will throw an UnsupportedOperationException.
081    */
082   public void setAutoSaving(boolean autoSaving)
083   throws UnsupportedOperationException,PersistenceException;
084 
085   /** Get the autosaving behaviour of the LR. */
086   public boolean isAutoSaving();
087   
088   /** Adopt a resource for persistence. */
089   public LanguageResource adopt(LanguageResource lrthrows PersistenceException;
090 
091   /**
092    * Get a resource from the persistent store.
093    <B>You should never call this method directly, instead use the following:</B>
094    <pre> FeatureMap params = Factory.newFeatureMap();
095    * params.put(DataStore.DATASTORE_FEATURE_NAME, datastore);
096    * params.put(DataStore.LR_ID_FEATURE_NAME, lrID);
097    * LanguageResource lr = (LanguageResource)Factory.createResource(lrClassName, params);</pre>
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<String> getLrTypes() throws PersistenceException;
104 
105   /** Get a list of the IDs of LRs of a particular type that are present. */
106   public List<String> getLrIds(String lrTypethrows PersistenceException;
107 
108   /** Get a list of the names of LRs of a particular type that are present. */
109   public List<String> getLrNames(String lrTypethrows PersistenceException;
110 
111   /** Get a list of LRs that satisfy some set or restrictions */
112   @SuppressWarnings("rawtypes"// we've never implemented the types are unknown
113   public List findLrIds(List constraintsthrows PersistenceException;
114 
115   /**
116    *  Get a list of LRs that satisfy some set or restrictions and are
117    *  of a particular type
118    */
119   @SuppressWarnings("rawtypes"// we've never implemented the types are unknown
120   public List findLrIds(List constraints, String lrTypethrows PersistenceException;
121 
122   /** Get the name of an LR from its ID. */
123   public String getLrName(Object lrIdthrows PersistenceException;
124 
125   /**
126    * Registers a new {@link gate.event.DatastoreListener} with this datastore
127    */
128   public void addDatastoreListener(DatastoreListener l);
129 
130   /**
131    * Removes a a previously registered {@link gate.event.DatastoreListener}
132    * from the list listeners for this datastore
133    */
134   public void removeDatastoreListener(DatastoreListener l);
135 
136   /**
137    * Returns the name of the icon to be used when this datastore is displayed
138    * in the GUI
139    */
140   public String getIconName();
141 
142   /**
143    * Returns the comment displayed by the GUI for this DataStore
144    */
145   public String getComment();
146 
147 
148   /**
149    * Checks if the user (identified by the sessionID)
150    *  has read access to the LR
151    */
152   public boolean canReadLR(Object lrID)
153     throws PersistenceException;
154 
155   /**
156    * Checks if the user (identified by the sessionID)
157    * has write access to the LR
158    */
159   public boolean canWriteLR(Object lrID)
160     throws PersistenceException;
161 
162   /**
163    * Try to acquire exlusive lock on a resource from the persistent store.
164    * Always call unlockLR() when the lock is no longer needed
165    */
166   public boolean lockLr(LanguageResource lr)
167   throws PersistenceException,SecurityException;
168 
169   /**
170    * Releases the exlusive lock on a resource from the persistent store.
171    */
172   public void unlockLr(LanguageResource lr)
173   throws PersistenceException,SecurityException;
174 
175 
176 // interface DataStore