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 final short
    HARD
    Deprecated.
    user STRONG
    static final short
    SOFT
    Reference mode soft, meaning the resource will be observed (but not necessarily kept) using a soft reference
    static final short
    STRONG
    Reference mode strong, meaning the resource will be observed (and kept) using a strong reference
    static final short
    WEAK
    Reference mode weak, meaning the resource will be observed (but not necessarily kept) using a weak reference

  • Method Summary

    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(Class<T> clz)
    Retrieve a resource representation adhering to the passed-on type.
    void
    attach(Object o)
    Attach the handle to an object.
    void
    detach(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 Details

    • WEAK

      static final short WEAK
      Reference mode weak, meaning the resource will be observed (but not necessarily kept) using a weak reference
      See Also:

    • SOFT

      static final short SOFT
      Reference mode soft, meaning the resource will be observed (but not necessarily kept) using a soft reference
      See Also:

    • STRONG

      static final short STRONG
      Reference mode strong, meaning the resource will be observed (and kept) using a strong reference
      See Also:

    • HARD

      @Deprecated static final short HARD
      Deprecated.
      user STRONG
      See Also:

  • Method Details

    • 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(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(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(Object o)
      Detach the handle from an object. See attach(Object).