All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.webmacro.broker.ResourceEvent

java.lang.Object
   |
   +----java.util.EventObject
           |
           +----org.webmacro.broker.ResourceEvent

public abstract class ResourceEvent
extends EventObject
implements Observer, PropertyChangeListener
A ResourceEvent represents the request for, provision of, and revocation of a resource: the event has state, and passes through these three stages during its lifetime.

A ResourceProvider can construct a new AnnounceResourceEvent if it wishes to spontaneously announce a new resource to the world. More commonly a ResourceProvider will be passed a ResourceEvent by the Broker in response to a request from a ResourceConsumer. In either case the ResourceProvider should locate the resource and set it with the set() method.

Consumers can retreive the underlying resource from the Event, or revoke it. Consumers would revoke an event to indicate to a provider that the request is no longer desired--this may allow the provider to abort without doing expensive work.

ResourceEvents are handled asynchronously by the ResourceBroker. Attempts to call the toString() or getValue() methods before a resource has been obtained will block until the resource becomes available, or has been revoked. You can call the isAvailable() method to determine if such a call would block.

In addition, Providers should bear in mind that some kinds of ResourceEvents are passed to multiple consumers, so the returned object must be thread safe.

Also there may be more than one Provider working on obtianing the resource, or a consumer may revoke the request for some reason or other (eg: a client disconnected).

This class supports the PropertyChangeListener and Observer interfaces, but does not attempt to register itself as an observer or listener on any object. If you register it as an observer or listener on any object, possibly the resource that it contains, then it will notice whenever the resource has been updated, and use this information to cache it longer.

Thread policy: Methods of this object never acquire locks on external objects. ResourceBroker WILL lock ResourceEvent objects as needed, though--so if you lock on this object you MUST NOT call the ResourceBroker. If you synchronize on ResourceEvent, it is recommended that the code inside the synchronization block only call ResourceEvent methods.

See Also:
ResourceConsumer, ResourceProvider, ResourceBroker

Constructor Index

 o ResourceEvent(ResourceBroker, String, String, Object)
Create a new ResourceEvent.

Method Index

 o getName()
Get the name of this resource.
 o getType()
Return the type of this resource.
 o getValue()
This method will block until the resource is available, and once it's available, it will return it.
 o isAvailable()
Return true if the resource is currently available, so that calling getValue() will not block.
 o isRevoked()
Is this resource still valid? This will return false if the event has been revoked or cancelled, or the resource was non-existant or unavailable.
 o isSettable()
Return whether it is still possible to set this event.
 o propertyChange(PropertyChangeEvent)
Property Change Listener Interface: If this method is called, the reaper will note that the object has been used, and keep it around a little longer.
 o set(Object)
Set the resource.
 o toString()
Return the name and type of this resource event
 o update()
Updating the event indicates to the caching mechanism that the event is still in use.
 o update(Observable, Object)
Observer Interface: If this method is called, the reaper will note that the object has been used, and keep it around a little longer.

Constructors

 o ResourceEvent
 protected ResourceEvent(ResourceBroker broker,
                         String type,
                         String name,
                         Object resource) throws InvalidArgumentException
Create a new ResourceEvent. Providers can call this method to construct a new resource they wish to announce. Normally a ResourceEvent is constructed by a ResourceBroker in response to a request from a Consumer.

Providers MUST specify a ResourceBroker as the source of an event A ResourceEvent constructed from a request will always have the ResourceBroker as its source.

Parameters:
broker - is the source broker which handles this event
type - is required by Providers when filling requests
name - may be used by a provider filling a request
Throws: InvalidArgumentException
if a null value is passed in

Methods

 o getType
 public final String getType()
Return the type of this resource. Each resource has a type which associates it with a set of providers and consumers. Providers that handle multiple types should examine this field to determine what type of requests this is. Providers which handle only a single type can ignore it, as the Broker will only call a Provider with a matching type.

Returns:
the string type of this resource.
 o getName
 public final String getName()
Get the name of this resource. This is an arbitrary string that is meaningful to the provider and/or consumer. For example, it could be a query.

Providers should examine this string to determine what exactly is being requested.

Returns:
the string name of this ResourceEvent
 o set
 public final synchronized void set(Object resource) throws ResourceRevokedException, InvalidArgumentException
Set the resource. This can only be done once. Calling it a second time has no effect. This method also has no effect if the event has already been revoked. Returns whether the object was successfully set or not.

This method "accesses" the resource, resetting any cache expire.

Throws: InvalidArgumentException
if attempt to set to a null value
Throws: ResourceRevokedException
if the resource has been revoked
 o update
 public final void update()
Updating the event indicates to the caching mechanism that the event is still in use. Accessing the event in any way also touches it--this mechanism is provided in case you want to touch it when you access the object it's holding on to, to let the cache know that it is still in use even though you have not actually used the ResourceEvent itself.

This method "accesses" the resource, resetting any cache expire.

 o update
 public final void update(Observable o,
                          Object arg)
Observer Interface: If this method is called, the reaper will note that the object has been used, and keep it around a little longer. You can register the ResourceEvent as an observer on any observable object whose use is tied to the duration of time that the underlying resource should be kept alive.

This method "accesses" the resource, resetting any cache expire.

 o propertyChange
 public final void propertyChange(PropertyChangeEvent evt)
Property Change Listener Interface: If this method is called, the reaper will note that the object has been used, and keep it around a little longer. You can register the ResourceEvent as a property change listener on any object whose use is tied to the duration of time that the underlying resource should be kept alive.

This method "accesses" the resource, resetting any cache expire.

 o toString
 public final String toString()
Return the name and type of this resource event

Overrides:
toString in class EventObject
 o getValue
 public final synchronized Object getValue() throws ResourceRevokedException, ResourceUnavailableException
This method will block until the resource is available, and once it's available, it will return it. It will throw an exception if the resource cannot be located, has been revoked already, or if the call to this method violates the thread policy. Note that very few thread policy violations can be detected--most will just deadlock.

This method "accesses" the resource, resetting any cache expire.

Returns:
The underlying resource
Throws: ResourceRevokedException
resource has been revoked
Throws: ResourceUnavailableException
cannot retreive/doesn't exist
 o isAvailable
 public final boolean isAvailable()
Return true if the resource is currently available, so that calling getValue() will not block. Once a resource becomes available, calls to getValue will never block--even if the resource is revoked, the return will be immediate (and null in that case).

Calling this method marks the object as "accessed", resetting any cache expire count.

 o isRevoked
 public final boolean isRevoked()
Is this resource still valid? This will return false if the event has been revoked or cancelled, or the resource was non-existant or unavailable.

 o isSettable
 public final boolean isSettable()
Return whether it is still possible to set this event. In other words, the event is still valid, and it has not yet been set. Equivalent to !isRevoked() && !isAvailable().


All Packages  Class Hierarchy  This Package  Previous  Next  Index