Package com.zfabrik.resources.provider

Class 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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      <T> T as​(TypeRef<T> typeRef)
      Retrieve a resource representation adhering to the passed-on type reference.
      <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)
      Called at initialization time with the resource management.
      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)
        Called at initialization time with the resource management. At the point in time this method gets called, a handle has been associated. While there will be only one instance at a time, in highly concurrent situations, this method may be called more than once

      • 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. While there will be only one instance at a time, in highly concurrent situations, this method may be called more than once

      • 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

      • as

        public <T> T as​(TypeRef<T> typeRef)
        Retrieve a resource representation adhering to the passed-on type reference. For components default resolutions exist. The default implementation delegates to as(Class) whenever possible. In order to check for a TypeRef to match something expected, compare with a local type reference. E.g. 
         
 private TypeRef> ref = new TypeRef<>(){};
 
 public  T as(TypeRef typeRef) {
   if (ref.equals(typeRef)) {
     return typeRef.cast((Supplier) ()->"Hello World");
   }
   return super.as(typeRef);
 }
        Parameters:
        typeRef - the expected return type specified via TypeRef (that also supports parameterized types)