001: // ResourceStore.java
002: // $Id: ResourceStore.java,v 1.3 2000/08/16 21:37:54 ylafon Exp $
003: // (c) COPYRIGHT MIT and INRIA, 1996.
004: // Please first read the full copyright statement in file COPYRIGHT.html
005:
006: package org.w3c.tools.resources.store;
007:
008: import org.w3c.tools.resources.InvalidResourceException;
009: import org.w3c.tools.resources.Resource;
010:
011: import org.w3c.tools.resources.serialization.Serializer;
012:
013: import java.util.Enumeration;
014: import java.util.Hashtable;
015:
016: import java.io.File;
017:
018: /**
019: * A resource store implements persistency for a set of resources.
020: * A resource store may implement a number of strategies along different
021: * axis, for example:
022: * <ul>
023: * <li>It may connect to some database to get the resource attributes.
024: * <li>It may restrict the classes of the resource it handles (for security
025: * reasons), by using a specific class loader.
026: * <li>It may implement some caching scheme, to keep memory requirements low.
027: * <li>It may be distributed (eg using a ResourceStoreStub in the client, but
028: * providing access to a server-side resource store.).
029: * </ul>
030: */
031:
032: public interface ResourceStore {
033:
034: /**
035: * Get the version of that resource store.
036: * Version numbers are used to distinguish between pickling format.
037: * A resource store implementator has the duty of bumping the returned
038: * number whenever it's archiving format changes.
039: * Resource stores that relies on some external archiving mechanisms
040: * (such as a database), may return a constant.
041: * @return An integer version number.
042: */
043:
044: public int getVersion();
045:
046: /**
047: * Get the identifier for that store.
048: * @return A uniq store identifier, as a String.
049: */
050:
051: public String getIdentifier();
052:
053: /**
054: * Restore the resource whose name is given.
055: * This method doesn't assume that the resource will actually be restored,
056: * it can be kept in a cache by the ResourceStore object, and the cached
057: * version of the resource may be returned.
058: * @param identifier The identifier of the resource to restore.
059: * @param defs Default attribute values. If the resource needs to be
060: * restored from its pickled version, this Hashtable provides
061: * a set of default values for some of the attributes.
062: * @return A Resource instance, or <strong>null</strong>.
063: * @exception InvalidResourceException If the resource could not
064: * be restored from the store.
065: */
066:
067: public Resource loadResource(String identifier, Hashtable defs)
068: throws InvalidResourceException;
069:
070: /**
071: * Get this resource, but only if already loaded.
072: * The resource store may (recommended) maintain a cache of the resource
073: * it loads from its store. If the resource having this identifier
074: * has already been loaded, return it, otherwise, return
075: * <strong>null</strong>.
076: * @param identifier The resource identifier.
077: * @return A Resource instance, or <strong>null</strong>.
078: */
079:
080: public Resource lookupResource(String identifier);
081:
082: /**
083: * Stabilize the given resource.
084: * @param resource The resource to save.
085: */
086:
087: public void saveResource(Resource resource);
088:
089: /**
090: * Add this resource to this resource store.
091: * @param resource The resource to be added.
092: */
093:
094: public void addResource(Resource resource);
095:
096: /**
097: * Remove this resource from the repository.
098: * @param identifier The identifier of the resource to be removed.
099: */
100:
101: public void removeResource(String identifier);
102:
103: /**
104: * Rename a given resource.
105: * @param oldid The olde resource identifier.
106: * @param newid The new resource identifier.
107: */
108:
109: public void renameResource(String oldid, String newid);
110:
111: /**
112: * Mark this resource as modified.
113: * @param resource The resource that has changed (and will have to be
114: * pickled some time latter).
115: */
116:
117: public void markModified(Resource resource);
118:
119: /**
120: * Can this resource store be unloaded now ?
121: * This method gets called by the ResourceStoreManager before calling
122: * the <code>shutdown</code> method, when possible. An implementation
123: * of that method is responsible for checking the <code>acceptUnload
124: * </code> method of all its loaded resource before returning
125: * <strong>true</strong>, meaning that the resource store can be unloaded.
126: * @return A boolean <strong>true</strong> if the resource store can be
127: * unloaded.
128: */
129:
130: public abstract boolean acceptUnload();
131:
132: /**
133: * Shutdown this store.
134: */
135:
136: public void shutdown();
137:
138: /**
139: * Save this store.
140: */
141:
142: public void save();
143:
144: /**
145: * Enumerate all the resources saved in this store.
146: * @return An enumeration of Strings, giving the identifier for all
147: * the resources that this store knows about.
148: */
149:
150: public Enumeration enumerateResourceIdentifiers();
151:
152: /**
153: * Check for the existence of a resource in this store.
154: * @param identifier The identifier of the resource to check.
155: * @return A boolean <strong>true</strong> if the resource exists
156: * in this store, <strong>false</strong> otherwise.
157: */
158:
159: public boolean hasResource(String identifier);
160:
161: /**
162: * This resource store is being built, initialize it with the given arg.
163: * @param manager The ResourceStoreManager instance that asks yourself
164: * to initialize.
165: * @param token The resource store manager key to that resource store,
166: * this token should be used when calling methods from the manager that
167: * are to act on yourself.
168: * @param repository A file, giving the location of the associated
169: * repository.
170: */
171:
172: public void initialize(ResourceStoreManager manager, Object token,
173: File repository, Serializer serializer);
174:
175: }
|