1   /*
2    *  DataStore.java
3    *
4    *  Copyright (c) 1998-2001, 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.25 2001/11/29 13:29:43 marin Exp $
14   */
15  
16  package gate;
17  
18  import java.util.*;
19  import java.net.*;
20  
21  import gate.util.*;
22  import gate.persist.*;
23  import gate.event.*;
24  import gate.security.*;
25  import gate.security.SecurityException;
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 the name of an LR from its ID. */
111   public String getLrName(Object lrId) throws PersistenceException;
112 
113   /**
114    * Registers a new {@link gate.event.DatastoreListener} with this datastore
115    */
116   public void addDatastoreListener(DatastoreListener l);
117 
118   /**
119    * Removes a a previously registered {@link gate.event.DatastoreListener}
120    * from the list listeners for this datastore
121    */
122   public void removeDatastoreListener(DatastoreListener l);
123 
124   /**
125    * Returns the name of the icon to be used when this datastore is displayed
126    * in the GUI
127    */
128   public String getIconName();
129 
130   /**
131    * Returns the comment displayed by the GUI for this DataStore
132    */
133   public String getComment();
134 
135 
136   /**
137    * Checks if the user (identified by the sessionID)
138    *  has read access to the LR
139    */
140   public boolean canReadLR(Object lrID)
141     throws PersistenceException, gate.security.SecurityException;
142 
143   /**
144    * Checks if the user (identified by the sessionID)
145    * has write access to the LR
146    */
147   public boolean canWriteLR(Object lrID)
148     throws PersistenceException, gate.security.SecurityException;
149 
150   /** get security information for LR . */
151   public SecurityInfo getSecurityInfo(LanguageResource lr)
152     throws PersistenceException;
153 
154   /** set security information for LR . */
155   public void setSecurityInfo(LanguageResource lr,SecurityInfo si)
156     throws PersistenceException, gate.security.SecurityException;
157 
158   /** identify user using this datastore */
159   public void setSession(Session s)
160     throws gate.security.SecurityException;
161 
162   /** identify user using this datastore */
163   public Session getSession(Session s)
164     throws gate.security.SecurityException;
165 
166   /**
167    * Try to acquire exlusive lock on a resource from the persistent store.
168    * Always call unlockLR() when the lock is no longer needed
169    */
170   public boolean lockLr(LanguageResource lr)
171   throws PersistenceException,SecurityException;
172 
173   /**
174    * Releases the exlusive lock on a resource from the persistent store.
175    */
176   public void unlockLr(LanguageResource lr)
177   throws PersistenceException,SecurityException;
178 
179 
180 } // interface DataStore
181