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 theContainerActivator
andCurrentContainer
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 ofRequest
,RequestHandler
,ContentChannel
, orCompletionHandler
.- Author:
- Simon Thoresen Hult
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description DeactivatedContainer
activateContainer(ContainerBuilder builder)
Creates and activates aContainer
based on the providedContainerBuilder
.Application
application()
Returns theApplication
loaded by this TestDriver.boolean
awaitClose(long timeout, TimeUnit unit)
Waits for shut down of this TestDriver to complete.BootstrapLoader
bootstrapLoader()
Returns theBootstrapLoader
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 andRequest.connect(ResponseHandler)
aRequest
on theCurrentContainer
.Future<Response>
dispatchRequest(String requestUri, ResponseHandler responseHandler)
Convenience method to create aRequest
, connect it to aRequestHandler
, and close the returnedContentChannel
.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 newContainerBuilder
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 injectedApplication
.static TestDriver
newInjectedApplicationInstance(Class<? extends Application> appClass, com.google.inject.Module... guiceModules)
Creates a new TestDriver with an injectedApplication
.static TestDriver
newInjectedApplicationInstanceWithoutOsgi(Application app, com.google.inject.Module... guiceModules)
Creates a new TestDriver with an injectedApplication
, but without OSGi support.static TestDriver
newInjectedApplicationInstanceWithoutOsgi(Class<? extends Application> appClass, com.google.inject.Module... guiceModules)
Creates a new TestDriver with an injectedApplication
, but without OSGi support.static TestDriver
newInstance(OsgiFramework osgiFramework, String bundleLocation, boolean privileged, com.google.inject.Module... guiceModules)
Creates a new TestDriver with the given parameters.static OsgiFramework
newNonWorkingOsgiFramework()
Factory method to create a light-weightOsgiFramework
that throwsUnsupportedOperationException
ifOsgiFramework.installBundle(String)
orOsgiFramework.startBundles(List, boolean)
is called.static FelixFramework
newOsgiFramework()
Factory method to create a workingOsgiFramework
.Container
newReference(URI uri)
RequestDispatch
newRequestDispatch(String requestUri, ResponseHandler responseHandler)
static TestDriver
newSimpleApplicationInstance(com.google.inject.Module... guiceModules)
Creates a new TestDriver with a predefinedApplication
implementation.static TestDriver
newSimpleApplicationInstanceWithoutOsgi(com.google.inject.Module... guiceModules)
Creates a new TestDriver with a predefinedApplication
implementation, but without OSGi support.OsgiFramework
osgiFramework()
Returns theOsgiFramework
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
-
Methods inherited from interface com.yahoo.jdisc.service.CurrentContainer
newReference
-
-
-
-
Method Detail
-
newContainerBuilder
public ContainerBuilder newContainerBuilder()
Description copied from interface:ContainerActivator
This method creates and returns a newContainerBuilder
object that has the necessary references to the application and its internal components.- Specified by:
newContainerBuilder
in interfaceContainerActivator
- Returns:
- The created builder.
-
activateContainer
public DeactivatedContainer activateContainer(ContainerBuilder builder)
Description copied from interface:ContainerActivator
Creates and activates aContainer
based on the providedContainerBuilder
. 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 interfaceContainerActivator
- Parameters:
builder
- The builder to activate.- Returns:
- The previous container, if any.
-
newReference
public Container newReference(URI uri)
- Specified by:
newReference
in interfaceCurrentContainer
-
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. Untilclose()
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 aNonWorkingOsgiFramework
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)
aRequest
on theCurrentContainer
. This method will either return the correspondingContentChannel
or throw the appropriate exception (seeRequest.connect(ResponseHandler)
).- Parameters:
requestUri
- The URI string to parse and pass to the Request constructor.responseHandler
- The ResponseHandler to pass toRequest.connect(ResponseHandler)
.- Returns:
- The ContentChannel returned by
Request.connect(ResponseHandler)
. - Throws:
NullPointerException
- If the URI string or theResponseHandler
is null.IllegalArgumentException
- If the URI string violates RFC 2396.BindingNotFoundException
- If the corresponding call toContainer.resolveHandler(Request)
returns null.RequestDeniedException
- If the corresponding call toRequestHandler.handleRequest(Request, ResponseHandler)
returns null.
-
dispatchRequest
public Future<Response> dispatchRequest(String requestUri, ResponseHandler responseHandler)
Convenience method to create a
Request
, connect it to aRequestHandler
, and close the returnedContentChannel
. 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 toRequest.connect(ResponseHandler)
.- Returns:
- A waitable Future that provides access to the corresponding
Response
. - Throws:
NullPointerException
- If the URI string or theResponseHandler
is null.IllegalArgumentException
- If the URI string violates RFC 2396.BindingNotFoundException
- If the corresponding call toContainer.resolveHandler(Request)
returns null.RequestDeniedException
- If the corresponding call toRequestHandler.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 aRequest
with the given URI andResponseHandler
.- 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 GuiceModules
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 GuiceModules
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 GuiceModules
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 GuiceModules
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 GuiceModules
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 GuiceModules
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 GuiceModules
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
- TheOsgiFramework
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 GuiceModules
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 allTestDriver
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 throwsUnsupportedOperationException
ifOsgiFramework.installBundle(String)
orOsgiFramework.startBundles(List, boolean)
is called. This allows for unit testing without the footprint of OSGi support. This method is used byTestDriver
factories that have the "WithoutOsgi" suffix.- Returns:
- A non-working OsgiFramework.
-
-