01: // ResourceReference.java
02: // $Id: ResourceReference.java,v 1.5 2002/08/08 12:30:15 ylafon Exp $
03: // (c) COPYRIGHT MIT and INRIA, 1997.
04: // Please first read the full copyright statement in file COPYRIGHT.html
05:
06: package org.w3c.tools.resources;
07:
08: /**
09: * Resolving a resource provides back a resource reference.
10: * Resource <em>references</em> are the basis for handling an eventual
11: * cache between the store of the resource and its memory image (ie
12: * the resource instance).
13: * <p>All resource spaces must provide some notion of resource reference.
14: * <p>A typical access to a resource looks like:
15: * <pre>
16: * ResourceReference rr = space.lookup("/x/y/z");
17: * try {
18: * Resource r = rr.lock();
19: * // Fiddle with the resource:
20: * r.setValue("foo", new Integer(10));
21: * } catch (InvalidResourceException e) {
22: * System.out.println(e.getMessage());
23: * } finally {
24: * // Make sure to unlock the reference:
25: * rr.unlock();
26: * </pre>
27: */
28:
29: public interface ResourceReference {
30:
31: /**
32: * Lock the refered resource in memory.
33: * @return A real pointer to the resource.
34: * @exception InvalidResourceException is thrown if the resource is
35: * invalid (has been deleted or everything else).
36: */
37: public Resource lock() throws InvalidResourceException;
38:
39: /**
40: * Lock the refered resource in memory.
41: * NOTE, this version is NOT using a synchronized call and therefore
42: * must be used with extreme caution. Basically it must be used only
43: * when a backward locking is needed
44: * @return A real pointer to the resource.
45: * @exception InvalidResourceException is thrown if the resource is
46: * invalid (has been deleted or everything else).
47: */
48: public Resource unsafeLock() throws InvalidResourceException;
49:
50: /**
51: * Unlock that resource from memory.
52: */
53: public void unlock();
54:
55: /**
56: * Is that resource reference locked ?
57: * @return a boolean.
58: */
59: public boolean isLocked();
60:
61: /**
62: * How many locks?
63: * @return an int.
64: */
65: public int nbLock();
66:
67: /**
68: * update the cached context of that reference.
69: * @param ctxt the new ResourceContext.
70: */
71: public void updateContext(ResourceContext ctxt);
72:
73: }
|