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
.
Modifier and Type | Class and Description |
---|---|
private class |
TestDriver.CloseTask |
private static class |
TestDriver.SimpleApplication |
Modifier and Type | Field and Description |
---|---|
private FutureTask<Boolean> |
closeTask |
private com.yahoo.jdisc.core.ApplicationLoader |
loader |
private static AtomicInteger |
testId |
Modifier | Constructor and Description |
---|---|
private |
TestDriver(com.yahoo.jdisc.core.ApplicationLoader loader) |
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)
|
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.
|
private static final AtomicInteger testId
private final FutureTask<Boolean> closeTask
private final com.yahoo.jdisc.core.ApplicationLoader loader
public ContainerBuilder newContainerBuilder()
ContainerActivator
This method creates and returns a new ContainerBuilder
object that has the necessary references to the
application and its internal components.
newContainerBuilder
in interface ContainerActivator
public DeactivatedContainer activateContainer(ContainerBuilder builder)
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.
activateContainer
in interface ContainerActivator
builder
- The builder to activate.public Container newReference(URI uri)
CurrentContainer
Container
. Until SharedResource.release()
has been called,
the Container can not shut down.newReference
in interface CurrentContainer
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.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.
public Application application()
Returns the Application
loaded by this TestDriver. Until close()
is called, this method will
never return null.
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.
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)
).
requestUri
- The URI string to parse and pass to the Request constructor.responseHandler
- The ResponseHandler to pass to Request.connect(ResponseHandler)
.Request.connect(ResponseHandler)
.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.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);
requestUri
- The URI string to parse and pass to the Request constructor.responseHandler
- The ResponseHandler to pass to Request.connect(ResponseHandler)
.Response
.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.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.
awaitClose(long, TimeUnit)
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()
.
timeout
- The maximum time to wait.unit
- The time unit of the timeout argument.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.
IllegalStateException
- If shut down failed to complete within the allocated time.public RequestDispatch newRequestDispatch(String requestUri, ResponseHandler responseHandler)
Creates a new RequestDispatch
that dispatches a Request
with the given URI and ResponseHandler
.
requestUri
- The uri of the Request to create.responseHandler
- The ResponseHandler to use for the dispather.public static TestDriver newInjectedApplicationInstance(Class<? extends Application> appClass, com.google.inject.Module... guiceModules)
Creates a new TestDriver with an injected Application
.
appClass
- The Application class to inject.guiceModules
- The Guice Modules
to install prior to startup.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.
appClass
- The Application class to inject.guiceModules
- The Guice Modules
to install prior to startup.newInjectedApplicationInstance(Class, Module...)
,
newNonWorkingOsgiFramework()
public static TestDriver newInjectedApplicationInstance(Application app, com.google.inject.Module... guiceModules)
Creates a new TestDriver with an injected Application
.
app
- The Application to inject.guiceModules
- The Guice Modules
to install prior to startup.public static TestDriver newInjectedApplicationInstanceWithoutOsgi(Application app, com.google.inject.Module... guiceModules)
Creates a new TestDriver with an injected Application
, but without OSGi support.
app
- The Application to inject.guiceModules
- The Guice Modules
to install prior to startup.newInjectedApplicationInstance(Application, Module...)
,
newNonWorkingOsgiFramework()
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.
guiceModules
- The Guice Modules
to install prior to startup.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.
guiceModules
- The Guice Modules
to install prior to startup.newSimpleApplicationInstance(Module...)
,
newNonWorkingOsgiFramework()
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.
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.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.
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.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.
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.
private static TestDriver newInstance(OsgiFramework osgiFramework, String bundleLocation, boolean privileged, Iterable<? extends com.google.inject.Module> guiceModules)
private static List<com.google.inject.Module> newModuleList(Application app, Class<? extends Application> appClass, com.google.inject.Module... guiceModules)
Copyright © 2017. All rights reserved.