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
-
ResourceEvent(ResourceBroker, String, String, Object)
- Create a new ResourceEvent.
-
getName()
- Get the name of this resource.
-
getType()
- Return the type of this resource.
-
getValue()
- This method will block until the resource is available, and once
it's available, it will return it.
-
isAvailable()
- Return true if the resource is currently available, so that calling
getValue() will not block.
-
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.
-
isSettable()
- Return whether it is still possible to set this event.
-
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.
-
set(Object)
- Set the resource.
-
toString()
- Return the name and type of this resource event
-
update()
- Updating the event indicates to the caching mechanism that the
event is still in use.
-
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.
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
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.
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
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
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.
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.
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.
toString
public final String toString()
- Return the name and type of this resource event
- Overrides:
- toString in class EventObject
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
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.
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.
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