Package com.yahoo.jdisc.test

Class 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 Detail

      • activateContainer

        public DeactivatedContainer activateContainer​(ContainerBuilder builder)
        Description copied from interface: ContainerActivator
        Creates and activates a Container based on the provided ContainerBuilder. By providing a null argument, this method can be used to deactivate the current Container. The returned object can be used to schedule a cleanup task that is executed once the the deactivated Container has terminated.
        Specified by:
        activateContainer in interface ContainerActivator
        Parameters:
        builder - The builder to activate.
        Returns:
        The previous container, if any.

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

      • 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(long, TimeUnit)

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

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

      • 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:
        newSimpleApplicationInstance(Module...), newNonWorkingOsgiFramework()

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