## org.w3c.tools.resources
Interface ResourceReference

All Known Implementing Classes:
  DummyResourceReference

public interface ResourceReference

Resolving a resource provides back a resource reference. Resource references are the basis for handling an eventual cache between the store of the resource and its memory image (ie the resource instance).

All resource spaces must provide some notion of resource reference.

A typical access to a resource looks like:

     ResourceReference rr = space.lookup("/x/y/z");
     try {
        Resource r = rr.lock();
        // Fiddle with the resource:
        r.setValue("foo", new Integer(10));
     } catch (InvalidResourceException e) {
       System.out.println(e.getMessage());
     } finally {
        // Make sure to unlock the reference:
        rr.unlock();

Method Summary
`boolean` `isLocked()` Is that resource reference locked ?
`Resource` `lock()` Lock the refered resource in memory.
`int` `nbLock()` How many locks?
`void` `unlock()` Unlock that resource from memory.
`Resource` `unsafeLock()` Lock the refered resource in memory.
`void` `updateContext(ResourceContext ctxt)` update the cached context of that reference.

Method Detail

### lock

    public Resource lock()
                  throws InvalidResourceException

  Lock the refered resource in memory.
  Returns:
    A real pointer to the resource.
  Throws:
    InvalidResourceException - is thrown if the resource is invalid (has been deleted or everything else).

### unsafeLock

    public Resource unsafeLock()
                        throws InvalidResourceException

  Lock the refered resource in memory. NOTE, this version is NOT using a synchronized call and therefore must be used with extreme caution. Basically it must be used only when a backward locking is needed
  Returns:
    A real pointer to the resource.
  Throws:
    InvalidResourceException - is thrown if the resource is invalid (has been deleted or everything else).

### unlock

    public void unlock()

  Unlock that resource from memory.

### isLocked

    public boolean isLocked()

  Is that resource reference locked ?
  Returns:
    a boolean.

### nbLock

    public int nbLock()

  How many locks?
  Returns:
    an int.

### updateContext

    public void updateContext(ResourceContext ctxt)

  update the cached context of that reference.
  Parameters:
    `ctxt` - the new ResourceContext.