Package com.yahoo.jdisc.application

Class ResourcePool

  • All Implemented Interfaces:
    SharedResource, java.lang.AutoCloseable
    public final class ResourcePool
extends AbstractResource
implements java.lang.AutoCloseable

    This is a utility class to help manage SharedResources while configuring a ContainerBuilder. This class can still be used without a ContainerBuilder, albeit with the injection APIs (i.e. get(Class) and get(com.google.inject.Key)) disabled.

    The core problem with SharedResources is that they need to be tracked carefully to ensure exception safety in the code that creates and registers them with a ContainerBuilder. The code for this typically looks like this:

     MyServerProvider serverProvider = null;
 MyRequestHandler requestHandler = null;
 try {
     serverProvider = builder.getInstance(MyServerProvider.class);
     serverProvider.start();
     containerBuilder.serverProviders().install(serverProvider);

     requestHandler = builder.getInstance(MyRequestHandler.class);
     containerBuilder.serverBindings().bind("http://host/path", requestHandler);

     containerActivator.activateContainer(containerBuilder);
 } finally {
     if (serverProvider != null) {
         serverProvider.release();
     }
     if (requestHandler != null) {
         requestHandler.release();
     }
 }

    The ResourcePool helps remove the boiler-plate code used to track the resources from outside the try-finally block. Using the ResourcePool, the above snippet can be rewritten to the following:

     try (ResourcePool resources = new ResourcePool(containerBuilder)) {
     ServerProvider serverProvider = resources.get(MyServerProvider.class);
     serverProvider.start();
     containerBuilder.serverProviders().install(serverProvider);

     RequestHandler requestHandler = resources.get(MyRequestHandler.class);
     containerBuilder.serverBindings().bind("http://host/path", requestHandler);

     containerActivator.activateContainer(containerBuilder);
 }

    This class is not thread-safe.

    Author:
    Simon Thoresen Hult

    • Constructor Detail

      • ResourcePool

        public ResourcePool()

        Creates a new instance of this class without a backing ContainerBuilder. A ResourcePool created with this constructor will throw a NullPointerException if either get(Class) or get(Key) is called.

      • ResourcePool

        public ResourcePool​(ContainerBuilder builder)

        Creates a new instance of this class. All calls to get(Class) and get(Key) are forwarded to the ContainerBuilder given to this constructor.

        Parameters:
        builder - The ContainerBuilder that provides the injection functionality for this ResourcePool.

    • Method Detail

      • add

        public <T extends SharedResource> T add​(T t)

        Adds the given SharedResource to this ResourcePool. Note that this DOES NOT call SharedResource.refer(), as opposed to retain(SharedResource). When this ResourcePool is destroyed, it will release the main reference to the resource (by calling SharedResource.release()).

        Type Parameters:
        T - The class of parameter t.
        Parameters:
        t - The SharedResource to add.
        Returns:
        The parameter t, to allow inlined calls to this function.

      • get

        public <T extends SharedResource> T get​(com.google.inject.Key<T> key)

        Returns the appropriate instance for the given injection key. Note that this DOES NOT call SharedResource.refer(). This is the equivalent of doing:

         t = containerBuilder.getInstance(key);
 resourcePool.add(t);

        When this ResourcePool is destroyed, it will release the main reference to the resource (by calling SharedResource.release()).

        Type Parameters:
        T - The class of the injection type.
        Parameters:
        key - The injection key to return.
        Returns:
        The appropriate instance of T.
        Throws:
        java.lang.NullPointerException - If this pool was constructed without a ContainerBuilder.

      • get

        public <T extends SharedResource> T get​(java.lang.Class<T> type)

        Returns the appropriate instance for the given injection type. Note that this DOES NOT call SharedResource.refer(). This is the equivalent of doing:

         t = containerBuilder.getInstance(type);
 resourcePool.add(t);

        When this ResourcePool is destroyed, it will release the main reference to the resource (by calling SharedResource.release()).

        Type Parameters:
        T - The class of the injection type.
        Parameters:
        type - The injection type to return.
        Returns:
        The appropriate instance of T.
        Throws:
        java.lang.NullPointerException - If this pool was constructed without a ContainerBuilder.

      • retain

        public <T extends SharedResource> T retain​(T t)

        Retains and adds the given SharedResource to this ResourcePool. Note that this DOES call SharedResource.refer(), as opposed to add(SharedResource).

        When this ResourcePool is destroyed, it will release the resource reference returned by the SharedResource.refer() call.

        Type Parameters:
        T - The class of parameter t.
        Parameters:
        t - The SharedResource to retain and add.
        Returns:
        The parameter t, to allow inlined calls to this function.

      • destroy

        protected void destroy()
        Description copied from class: AbstractResource

        This method signals that this AbstractResource can dispose of any internal resources, and commence with shut down of any internal threads. This will be called once the reference count of this resource reaches zero.

        Overrides:
        destroy in class AbstractResource

      • close

        public void close()
           throws java.lang.Exception
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        java.lang.Exception