Package com.zfabrik.resources

## Interface IResourceHandle

-     public interface IResourceHandle

  A resource handle is a nameless accessor to a resource managed by the resource management system.

  The handle can be used to add and remove dependencies of a resource, to adjust the life-cycle handling of a resource and generally to hold on to a resource.

  Resources that are not managed by hard references will not be collected as long as an associated resource handle is held onto.

  Author:
    hb

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static short` | `HARD` | Deprecated. user `STRONG`
    `static short` | `SOFT` | Reference mode soft, meaning the resource will be observed (but not necessarily kept) using a soft reference
    `static short` | `STRONG` | Reference mode strong, meaning the resource will be observed (and kept) using a strong reference
    `static short` | `WEAK` | Reference mode weak, meaning the resource will be observed (but not necessarily kept) using a weak reference

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addDependency​(IResourceHandle rh)` | Adds a dependency for this resource.
    `void` | `adjust​(long ttl, long exp, short rm)` | Adjust the life-cycle handling of the single resource
    `<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 resource representation adhering to the passed-on type.
    `void` | `attach​(java.lang.Object o)` | Attach the handle to an object.
    `void` | `detach​(java.lang.Object o)` | Detach the handle from an object.
    `IResourceObserver` | `getObserver()` | Get the observer, an id to the handle that does not determine the handles life cycle
    `IResourceInfo` | `getResourceInfo()` | Gets resource info
    `boolean` | `hasDependency​(IResourceHandle rh)` | Checks whether this handle depends on the resource associated to the passed-in handle.
    `void` | `invalidate​(boolean forced)` | Invalidate the resource.
    `void` | `removeDependency​(IResourceHandle rh)` | Removes a dependency from this resource.

- - ### Field Detail

    - #### WEAK

          static final short WEAK

      Reference mode weak, meaning the resource will be observed (but not necessarily kept) using a weak reference
      See Also:
        Constant Field Values

    - #### SOFT

          static final short SOFT

      Reference mode soft, meaning the resource will be observed (but not necessarily kept) using a soft reference
      See Also:
        Constant Field Values

    - #### STRONG

          static final short STRONG

      Reference mode strong, meaning the resource will be observed (and kept) using a strong reference
      See Also:
        Constant Field Values

    - #### HARD

          @Deprecated
          static final short HARD

      Deprecated.
      user `STRONG`
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### adjust

          void adjust​(long ttl,
                      long exp,
                      short rm)

      Adjust the life-cycle handling of the single resource
      Parameters:
        `ttl` - a time-to-live parameter.
        `exp` - an absolute point in time. When reaching exp, the resource will be automatically invalidated. Set to `Long.MAX_VALUE` by default.
        `rm` - the type of reference applied when holding onto the resource (see `WEAK`, `SOFT`, `STRONG`).

    - #### invalidate

          void invalidate​(boolean forced)
                   throws ResourceBusyException

      Invalidate the resource.
      Parameters:
        `forced` - if `true` the resource cannot veto by throwing a ResourceBusyException. Otherwise it can.
      Throws:
        `ResourceBusyException`

    - #### as

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

      Retrieve a resource representation adhering to the passed-on type. For components default resolutions exist.
      Parameters:
        `clz` - the expected return type

    - #### as

          <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. Using the `TypeRef` API, it is possible to specify parameterized types in a type-safe manner. For example:

           lookup(new TypeRef<List<String>>(){});

      Parameters:
        `typeRef` - the expected return type specified via `TypeRef` (that also supports parameterized types)

    - #### hasDependency

          boolean hasDependency​(IResourceHandle rh)

      Checks whether this handle depends on the resource associated to the passed-in handle.

    - #### addDependency

          void addDependency​(IResourceHandle rh)

      Adds a dependency for this resource. The invalidation or termination of a dependency resource implies the invalidation of this resource

    - #### removeDependency

          void removeDependency​(IResourceHandle rh)

      Removes a dependency from this resource.

    - #### getResourceInfo

          IResourceInfo getResourceInfo()

      Gets resource info

    - #### getObserver

          IResourceObserver getObserver()

      Get the observer, an id to the handle that does not determine the handles life cycle

    - #### attach

          void attach​(java.lang.Object o)

      Attach the handle to an object. That means, as long as the object is held by some reference, the handle and accordingly the resource not be collected. This is a good way of propagating the singleton aspect of the handle and the resource implementation to its emitted objects.

    - #### detach

          void detach​(java.lang.Object o)

      Detach the handle from an object. See `attach(Object)`.