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

    • 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).