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

    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)` |
    `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

    - #### 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)