Package com.yahoo.jdisc.application

Class ResourcePool

java.lang.Object
com.yahoo.jdisc.AbstractResource
com.yahoo.jdisc.application.ResourcePool
All Implemented Interfaces:
SharedResource, AutoCloseable
public final class ResourcePool extends AbstractResource implements 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 Details

    • 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 Details

    • 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:
      NullPointerException - If this pool was constructed without a ContainerBuilder.

    • get

      public <T extends SharedResource> T get(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:
      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 Exception
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception