Package com.zfabrik.resources.provider

Class Resource

java.lang.Object

com.zfabrik.resources.provider.Resource

public abstract class Resource
extends java.lang.Object

Resource base class.

Resources model named, memory-managed objects that may have dependencies onto other resources and may have a non-trivial life cycle. For example all component factories are required to provide extensions of this class.

The resource management system is the underpinning of z2's on-demand behavior. The typical life cycle of a resource implementation instance looks as follows

1. Provisioning by name. The resource will be known by the given name from there on.
2. Any number of as(Class) calls may occur. In order to provide the required result or to implement some side-effect, a resource implementation may build up state and use other resources:
   • For every resource required the resource at hand should declare dependency calling

     handle().addDependency(<handle of required resource>)

     See also IResourceHandle.addDependency(IResourceHandle).
   • If returned objects are not associated to the resource instance natively, e.g. by using non-static inner classes, the resource should call

     handle().attach(Object)

     if it is desired that the resource instance be kept as long as the returned objects (see IResourceHandle.attach(Object)).
   • State changes should be synchronized as invalidations may happen at any time
   • A resource may change its management model using

     handle().adjust(long, long, short)

     See also IResourceHandle.adjust(long, long, short). Reasons for this vary. For example Web Applications require explicit "stop" calls, so that a resource representing a Web application may not be silently collected.
3. Unless managed by hard references (see IResourceHandle.adjust(long, long, short)), the resource may be collected once no other reference holds on to a resource handle for it.
4. Resource may be invalidated, most prominently due to synchronization of component repositories. Invalidation observes dependencies. That is, a resource will be invalidated also if (and before) any of its dependency resources will be invalidated.

   During invalidation, a resource should clean up any state built up since provisioning and return to a freshly provisioned status.

Resource is a class rather than an interface in order provide a simple and safe association of the resource implementation with its handle.

Author:

hb

Constructor Summary

Constructors

Constructor	Description
Resource()

Method Summary

Modifier and Type	Method	Description
<T> T	as(java.lang.Class<T> clz)	Retrieve a typed representation of the resource.
IResourceHandle	handle()	Return the handle for this resource.
void	init()	Called at initialization time with the resource management.
void	init(IResourceHandle c)
void	invalidate()	This method gets called whenever a dependency resource has been invalidated or this resource needs to be invalidated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Resource

public Resource()

Method Detail

init

public final void init(IResourceHandle c)

init

public void init()

Called at initialization time with the resource management. At the point in time this method gets called, a handle has been associated.

handle

public final IResourceHandle handle()

Return the handle for this resource. Use as outlined in the classes documentation.

invalidate

public void invalidate()
                throws ResourceBusyException

This method gets called whenever a dependency resource has been invalidated or this resource needs to be invalidated.

This code should be executed in a life cycle code block of this resource instance, i.e. where dependencies are effectively managed, so that race conditions can be avoided.

State changing methods of a resource should always be synchronized (e.g. on this). This is in particular true for cross-resource dependencies. In order to assure consistency under race conditions, a dependent resource should first declare its dependency and then retrieve the resource implementation. In case of failures, resources should clean up by calling handle().invalidate(true);

Throws:

ResourceBusyException

as

public <T> T as(java.lang.Class<T> clz)

Retrieve a typed representation of the resource.

Parameters:

clz - expected return type

Returns:

the expected return type instance represented by the resource or null if the type facade is not supported.

Throws:

ResourceTypeNotAvailableException - if the type is supported but cannot be made available due to an error situation