    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class JavaAgent.resource.Resource

    java.lang.Object
       |
       +----JavaAgent.resource.Resource

public class Resource
extends Object

Abstract superclass for all resource objects owned by an Agent which must be handled as condition variables (i.e. access to the object must be synchronized). Objects can be added, removed and queried for existence. Storage is modeled by a Hashtable where the keys are identifiers and the objects are the actual resource elements being stored. Object locations are stored in a separate Hashtable, the location for code objects is represented by a FileLocation object. A NullResource object is used as a temporary marker for nonexistant objects.

Copyright (c) 1995, H. Robert Frost, Stanford University. All rights reserved.

Copyright (c) 1996, H. Robert Frost, Enterprise Integration Technologies, Inc. All rights reserved.

RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions as set forth in subparagraph(c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR supplement.

This software is bound by the terms and conditions listed in the attached LICENSE file.

##

locations
NO_RETRIEVAL
  Specifies that no attempt should be made to retrieve the element.
parent
storage

##

Resource(Agent)
  Constructor for the resource, initializes the storage space.

##

addElement(Object, Object, boolean)
  Synchronized method which adds a new element Object associated with an identifier Object.
addLocation(Object, Object, boolean)
  Method which adds a location Object associated with an identifier Object.
cache()
  Provides persistent storage of the Resource elements.
clean()
  Removes all NullResource objects from the storage Hashtable.
getElement(Object, int)
  Automatically uses the default receiver for retrieve messages.
getElement(Object, int, String)
  Synchronized method which returns the Object identified by the input identifier.
getElements()
getLocation(Object)
  Method which returns the location associated with the input identifier.
getMissingAction(Object, int, String)
  Action to take when there is an attempt to retrieve an element associated with a non-existent identifier.
hasElement(Object)
  Checks to see if a given identifier already exists.
removeElement(Object)
  Synchronized method which is called to remove the element associated with a given identifier.
removeLocation(Object)
  Removes the location associated with a given identifier.
removeMissingAction(Object)
  Action to be taken when there is an attempt to remove the element associated with a non-existant identifier.
size()
  Returns the number of elements.
uncache(Object)
  Adds elements to the Resource from persistent storage.

##

NO_RETRIEVAL

     public static final int NO_RETRIEVAL

  Specifies that no attempt should be made to retrieve the element.

storage

     protected Hashtable storage

locations

     protected Hashtable locations

parent

     protected Agent parent

##

Resource

     public Resource(Agent agent)

  Constructor for the resource, initializes the storage space.

  Parameters:
    agent - The Agent which owns the resource.

##

cache

     public Object cache() throws ResourceException

  Provides persistent storage of the Resource elements. This storage could be through a local file or a remote process. This method must be overridden and the uncache() method must also be implemented.

  Returns:
    Object representing the storage location.

uncache

     public void uncache(Object location) throws ResourceException

  Adds elements to the Resource from persistent storage. This method must be overridden.

  Returns:
    location Object representing the storage location.

size

     public int size()

  Returns the number of elements.

  Returns:
    Number of elements.

getElements

     public Enumeration getElements()

  Returns:
    Enumeration of the element names.

clean

     protected void clean()

  Removes all NullResource objects from the storage Hashtable.

hasElement

     public synchronized boolean hasElement(Object identifier)

  Checks to see if a given identifier already exists.

  Parameters:
    indentifier - Identifier whose existence is being checked.
  Returns:
    true if the identifier exists, false otherwise.

addElement

     public synchronized void addElement(Object identifier,
                                         Object element,
                                         boolean replace)

  Synchronized method which adds a new element Object associated with an identifier Object. Calls the notify() method to inform threads which might be waiting on a getElement() method. Depending on the value of the replace boolean, the element associated with a pre-existing identifier is either replaced or left unchanged.

  Parameters:
    identifier - Object identifier for the element.
    element - Object associated with the identifier.
    replace - Should the element of a pre-existing identifier be replaced?

addLocation

     public void addLocation(Object identifier,
                             Object location,
                             boolean replace)

  Method which adds a location Object associated with an identifier Object. Depending on the value of the replace boolean, the element associated with a pre-existing identifier is either replaced or left unchanged. For resources which are pieces of code the location is represented by a FileLocation object.

  Parameters:
    identifier - Object identifier for the element.
    location - Location associated with the identifier.
    replace - Should the location of a pre-existing identifier be replaced?

getElement

     public synchronized Object getElement(Object identifier,
                                           int retrieve_option,
                                           String receiver) throws ResourceException

  Synchronized method which returns the Object identified by the input identifier. If an object associated with the identifier does not exist then the getMissingAction() method is called. This method currently throws a ResourceException.

  Parameters:
    identifier - Object identifier for the element.
    retrieve_option - Specifies action to take if the element is not currently present.
    receiver - Agent to whom retrieve requests should be sent, null if default should be used.
  Returns:
    Object associated with the identifier.

getElement

     public synchronized Object getElement(Object identifier,
                                           int retrieve_option) throws ResourceException

  Automatically uses the default receiver for retrieve messages.

  Parameters:
    identifier - Object identifier for the element.
    retrieve_option - Specifies action to take if the element is not currently present.
  Returns:
    Object associated with the identifier.

getMissingAction

     public Object getMissingAction(Object identifier,
                                    int retrieve_option,
                                    String receiver) throws ResourceException

  Action to take when there is an attempt to retrieve an element associated with a non-existent identifier. Currently throws a ResourceException. Override to do something else.

  Parameters:
    identifier - Object identifier for the element.
    retrieve_option - Specifies action to take if the element is not currently present.
    receiver - Agent to whom retrieve requests should be sent, null if default should be used.
  Returns:
    Object to be returned.

getLocation

     public Object getLocation(Object identifier)

  Method which returns the location associated with the input identifier. Returns null if the identifier is not contained.

  Parameters:
    identifier - Object identifier for the location
  Returns:
    Location Object associated with the identifier.

removeElement

     public synchronized void removeElement(Object identifier)

  Synchronized method which is called to remove the element associated with a given identifier. If the identifier does not exist, the removeMissingAction() method is called (currently does nothing).

  Parameters:
    identifier - Identifier of the Object to remove.

removeMissingAction

     public void removeMissingAction(Object identifier)

  Action to be taken when there is an attempt to remove the element associated with a non-existant identifier. Must be overridden to do something.

  Parameters:
    identifier - Identifier of the non-existent object.

removeLocation

     public void removeLocation(Object identifier)

  Removes the location associated with a given identifier. Does nothing if the identifier does not exist.

  Parameters:
    identifier - Identifier of the location to remove.

    All Packages  Class Hierarchy  This Package  Previous  Next  Index