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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private class	TestDriver.CloseTask
private static class	TestDriver.SimpleApplication

Field Summary

Fields

Modifier and Type	Field and Description
private FutureTask<Boolean>	closeTask
private com.yahoo.jdisc.core.ApplicationLoader	loader
private static AtomicInteger	testId

Constructor Summary

Constructors

Modifier	Constructor and Description
private	TestDriver(com.yahoo.jdisc.core.ApplicationLoader loader)

Method Summary

Modifier and Type	Method and Description
DeactivatedContainer	activateContainer(ContainerBuilder builder) Creates and activates a Container based on the provided ContainerBuilder.
Application	application() Returns the Application loaded by this TestDriver.
boolean	awaitClose(long timeout, TimeUnit unit) Waits for shut down of this TestDriver to complete.
com.yahoo.jdisc.core.BootstrapLoader	bootstrapLoader() Returns the BootstrapLoader used by this TestDriver.
boolean	close() Initiatiates shut down of this TestDriver and waits for it to complete.
ContentChannel	connectRequest(String requestUri, ResponseHandler responseHandler) Convenience method to create and Request.connect(ResponseHandler) a Request on the CurrentContainer.
Future<Response>	dispatchRequest(String requestUri, ResponseHandler responseHandler) Convenience method to create a Request, connect it to a RequestHandler, and close the returned ContentChannel.
static TestDriver	newApplicationBundleInstance(String bundleLocation, boolean privileged, com.google.inject.Module... guiceModules) Creates a new TestDriver from an application bundle.
ContainerBuilder	newContainerBuilder() This method creates and returns a new ContainerBuilder object that has the necessary references to the application and its internal components.
static TestDriver	newInjectedApplicationInstance(Application app, com.google.inject.Module... guiceModules) Creates a new TestDriver with an injected Application.
static TestDriver	newInjectedApplicationInstance(Class<? extends Application> appClass, com.google.inject.Module... guiceModules) Creates a new TestDriver with an injected Application.
static TestDriver	newInjectedApplicationInstanceWithoutOsgi(Application app, com.google.inject.Module... guiceModules) Creates a new TestDriver with an injected Application, but without OSGi support.
static TestDriver	newInjectedApplicationInstanceWithoutOsgi(Class<? extends Application> appClass, com.google.inject.Module... guiceModules) Creates a new TestDriver with an injected Application, but without OSGi support.
private static TestDriver	newInstance(OsgiFramework osgiFramework, String bundleLocation, boolean privileged, Iterable<? extends com.google.inject.Module> guiceModules)
static TestDriver	newInstance(OsgiFramework osgiFramework, String bundleLocation, boolean privileged, com.google.inject.Module... guiceModules) Creates a new TestDriver with the given parameters.
private static List<com.google.inject.Module>	newModuleList(Application app, Class<? extends Application> appClass, com.google.inject.Module... guiceModules)
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.
static com.yahoo.jdisc.core.FelixFramework	newOsgiFramework() Factory method to create a working OsgiFramework.
Container	newReference(URI uri) Returns a reference to the currently active Container.
RequestDispatch	newRequestDispatch(String requestUri, ResponseHandler responseHandler) Creates a new RequestDispatch that dispatches a Request with the given URI and ResponseHandler.
static TestDriver	newSimpleApplicationInstance(com.google.inject.Module... guiceModules) Creates a new TestDriver with a predefined Application implementation.
static TestDriver	newSimpleApplicationInstanceWithoutOsgi(com.google.inject.Module... guiceModules) Creates a new TestDriver with a predefined Application implementation, but without OSGi support.
OsgiFramework	osgiFramework() Returns the OsgiFramework created by this TestDriver.
void	scheduleClose() Initiates the shut down of this TestDriver in another thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

testId

private static final AtomicInteger testId

closeTask

private final FutureTask<Boolean> closeTask

loader

private final com.yahoo.jdisc.core.ApplicationLoader loader

Constructor Detail

TestDriver

private TestDriver(com.yahoo.jdisc.core.ApplicationLoader loader)

Method Detail

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)

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.

newReference

public Container newReference(URI uri)

Description copied from interface: CurrentContainer

Returns a reference to the currently active Container. Until SharedResource.release() has been called, the Container can not shut down.

Specified by:

newReference in interface CurrentContainer

Parameters:

uri - The identifier used to match this Request to an appropriate ClientProvider or RequestHandler. The hostname must be "localhost" or a fully qualified domain name.

Returns:

A reference to the current Container.

bootstrapLoader

public com.yahoo.jdisc.core.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(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.

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(Class, Module...), newNonWorkingOsgiFramework()

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:

newInjectedApplicationInstance(Application, Module...), newNonWorkingOsgiFramework()

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 com.yahoo.jdisc.core.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.

newInstance

private static TestDriver newInstance(OsgiFramework osgiFramework,
                                      String bundleLocation,
                                      boolean privileged,
                                      Iterable<? extends com.google.inject.Module> guiceModules)

newModuleList

private static List<com.google.inject.Module> newModuleList(Application app,
                                                            Class<? extends Application> appClass,
                                                            com.google.inject.Module... guiceModules)