Package com.yahoo.jdisc.test

Class TestDriver

java.lang.Object
com.yahoo.jdisc.test.TestDriver
All Implemented Interfaces:
ContainerActivator, CurrentContainer
public class TestDriver extends Object implements ContainerActivator, CurrentContainer

This class provides a unified way to set up and run unit tests on jDISC components. In short, it is a programmable BootstrapLoader that provides convenient access to the ContainerActivator and CurrentContainer interfaces. A typical test case using this class looks as follows:

@Test
 public void requireThatMyComponentIsWellBehaved() {
     TestDriver driver = TestDriver.newSimpleApplicationInstanceWithoutOsgi();
     ContainerBuilder builder = driver.newContainerBuilder();
     (... configure builder ...)
     driver.activateContainer(builder);
     (... run tests ...)
     assertTrue(driver.close());
 }

One of the most important things to remember when using this class is to always call close() at the end of your test case. This ensures that the tested configuration does not prevent graceful shutdown. If close() returns FALSE, it means that either your components or the test case itself does not conform to the reference counting requirements of Request, RequestHandler, ContentChannel, or CompletionHandler.

Author:
Simon Thoresen Hult

  • Method Details

    • newContainerBuilder

      public ContainerBuilder newContainerBuilder()
      Description copied from interface: ContainerActivator
      This method creates and returns a new ContainerBuilder object that has the necessary references to the application and its internal components.
      Specified by:
      newContainerBuilder in interface ContainerActivator
      Returns:
      The created builder.

    • activateContainer

      public DeactivatedContainer activateContainer(ContainerBuilder builder)
      Returns the deactivated container, with its container reference already released.
      Specified by:
      activateContainer in interface ContainerActivator
      Parameters:
      builder - The builder to activate.
      Returns:
      The previous container, if any.

    • newReference

      public Container newReference(URI uri)
      Specified by:
      newReference in interface CurrentContainer

    • bootstrapLoader

      public BootstrapLoader bootstrapLoader()

      Returns the BootstrapLoader used by this TestDriver. Use caution when invoking methods on the BootstrapLoader directly, since the lifecycle management done by this TestDriver may become corrupt.

      Returns:
      The BootstrapLoader.

    • application

      public Application application()

      Returns the Application loaded by this TestDriver. Until close() is called, this method will never return null.

      Returns:
      The loaded Application.

    • osgiFramework

      public OsgiFramework osgiFramework()

      Returns the OsgiFramework created by this TestDriver. Although this method will never return null, it might return a NonWorkingOsgiFramework depending on the factory method used to instantiate it.

      Returns:
      The OSGi framework.

    • connectRequest

      public ContentChannel connectRequest(String requestUri, ResponseHandler responseHandler)

      Convenience method to create and Request.connect(ResponseHandler) a Request on the CurrentContainer. This method will either return the corresponding ContentChannel or throw the appropriate exception (see Request.connect(ResponseHandler)).

      Parameters:
      requestUri - The URI string to parse and pass to the Request constructor.
      responseHandler - The ResponseHandler to pass to Request.connect(ResponseHandler).
      Returns:
      The ContentChannel returned by Request.connect(ResponseHandler).
      Throws:
      NullPointerException - If the URI string or the ResponseHandler is null.
      IllegalArgumentException - If the URI string violates RFC 2396.
      BindingNotFoundException - If the corresponding call to Container.resolveHandler(Request) returns null.
      RequestDeniedException - If the corresponding call to RequestHandler.handleRequest(Request, ResponseHandler) returns null.

    • dispatchRequest

      public Future<Response> dispatchRequest(String requestUri, ResponseHandler responseHandler)

      Convenience method to create a Request, connect it to a RequestHandler, and close the returned ContentChannel. This is the same as calling:

       connectRequest(uri, responseHandler).close(null);
      Parameters:
      requestUri - The URI string to parse and pass to the Request constructor.
      responseHandler - The ResponseHandler to pass to Request.connect(ResponseHandler).
      Returns:
      A waitable Future that provides access to the corresponding Response.
      Throws:
      NullPointerException - If the URI string or the ResponseHandler is null.
      IllegalArgumentException - If the URI string violates RFC 2396.
      BindingNotFoundException - If the corresponding call to Container.resolveHandler(Request) returns null.
      RequestDeniedException - If the corresponding call to RequestHandler.handleRequest(Request, ResponseHandler) returns null.

    • scheduleClose

      public void scheduleClose()

      Initiates the shut down of this TestDriver in another thread. By doing this in a separate thread, it allows other code to monitor its progress. Unless you need the added monitoring capability, you should use close() instead.

      See Also:

    • awaitClose

      public boolean awaitClose(long timeout, TimeUnit unit)

      Waits for shut down of this TestDriver to complete. This call must be preceded by a call to scheduleClose().

      Parameters:
      timeout - The maximum time to wait.
      unit - The time unit of the timeout argument.
      Returns:
      True if shut down completed within the allocated time.

    • close

      public boolean close()

      Initiatiates shut down of this TestDriver and waits for it to complete. If shut down fails to complete within 60 seconds, this method throws an exception.

      Returns:
      True if shut down completed within the allocated time.
      Throws:
      IllegalStateException - If shut down failed to complete within the allocated time.

    • newRequestDispatch

      public RequestDispatch newRequestDispatch(String requestUri, ResponseHandler responseHandler)

      Creates a new RequestDispatch that dispatches a Request with the given URI and ResponseHandler.

      Parameters:
      requestUri - The uri of the Request to create.
      responseHandler - The ResponseHandler to use for the dispather.
      Returns:
      The created RequestDispatch.

    • newInjectedApplicationInstance

      public static TestDriver newInjectedApplicationInstance(Class<? extends Application> appClass, com.google.inject.Module... guiceModules)

      Creates a new TestDriver with an injected Application.

      Parameters:
      appClass - The Application class to inject.
      guiceModules - The Guice Modules to install prior to startup.
      Returns:
      The created TestDriver.

    • newInjectedApplicationInstanceWithoutOsgi

      public static TestDriver newInjectedApplicationInstanceWithoutOsgi(Class<? extends Application> appClass, com.google.inject.Module... guiceModules)

      Creates a new TestDriver with an injected Application, but without OSGi support.

      Parameters:
      appClass - The Application class to inject.
      guiceModules - The Guice Modules to install prior to startup.
      Returns:
      The created TestDriver.
      See Also:

    • newInjectedApplicationInstance

      public static TestDriver newInjectedApplicationInstance(Application app, com.google.inject.Module... guiceModules)

      Creates a new TestDriver with an injected Application.

      Parameters:
      app - The Application to inject.
      guiceModules - The Guice Modules to install prior to startup.
      Returns:
      The created TestDriver.

    • newInjectedApplicationInstanceWithoutOsgi

      public static TestDriver newInjectedApplicationInstanceWithoutOsgi(Application app, com.google.inject.Module... guiceModules)

      Creates a new TestDriver with an injected Application, but without OSGi support.

      Parameters:
      app - The Application to inject.
      guiceModules - The Guice Modules to install prior to startup.
      Returns:
      The created TestDriver.
      See Also:

    • newSimpleApplicationInstance

      public static TestDriver newSimpleApplicationInstance(com.google.inject.Module... guiceModules)

      Creates a new TestDriver with a predefined Application implementation. The injected Application class implements nothing but the bare minimum to conform to the Application interface.

      Parameters:
      guiceModules - The Guice Modules to install prior to startup.
      Returns:
      The created TestDriver.

    • newSimpleApplicationInstanceWithoutOsgi

      public static TestDriver newSimpleApplicationInstanceWithoutOsgi(com.google.inject.Module... guiceModules)

      Creates a new TestDriver with a predefined Application implementation, but without OSGi support. The injected Application class implements nothing but the bare minimum to conform to the Application interface.

      Parameters:
      guiceModules - The Guice Modules to install prior to startup.
      Returns:
      The created TestDriver.
      See Also:

    • newApplicationBundleInstance

      public static TestDriver newApplicationBundleInstance(String bundleLocation, boolean privileged, com.google.inject.Module... guiceModules)

      Creates a new TestDriver from an application bundle. This runs the same code path as the actual jDISC startup code. Note that the named bundle must have a "X-JDisc-Application" bundle instruction, or setup will fail.

      Parameters:
      bundleLocation - The location of the application bundle to load.
      privileged - Whether or not privileges should be marked as available to the application bundle.
      guiceModules - The Guice Modules to install prior to startup.
      Returns:
      The created TestDriver.

    • newInstance

      public static TestDriver newInstance(OsgiFramework osgiFramework, String bundleLocation, boolean privileged, com.google.inject.Module... guiceModules)

      Creates a new TestDriver with the given parameters. This is the factory method that all other factory methods call. It allows you to specify all parts of the TestDriver manually.

      Parameters:
      osgiFramework - The OsgiFramework to assign to the created TestDriver.
      bundleLocation - The location of the application bundle to load, may be null.
      privileged - Whether or not privileges should be marked as available to the application bundle.
      guiceModules - The Guice Modules to install prior to startup.
      Returns:
      The created TestDriver.

    • newOsgiFramework

      public static FelixFramework newOsgiFramework()

      Factory method to create a working OsgiFramework. This method is used by all TestDriver factories that DO NOT have the "WithoutOsgi" suffix.

      Returns:
      A working OsgiFramework.

    • newNonWorkingOsgiFramework

      public static OsgiFramework newNonWorkingOsgiFramework()

      Factory method to create a light-weight OsgiFramework that throws UnsupportedOperationException if OsgiFramework.installBundle(String) or OsgiFramework.startBundles(List, boolean) is called. This allows for unit testing without the footprint of OSGi support. This method is used by TestDriver factories that have the "WithoutOsgi" suffix.

      Returns:
      A non-working OsgiFramework.