Package org.jvnet.hk2.testing.junit

Class ServiceLocatorTestRule<T>

java.lang.Object

org.junit.rules.ExternalResource

org.jvnet.hk2.testing.junit.ServiceLocatorTestRule<T>

Type Parameters:

T - the type of JUnit test this ServiceLocatorTestRule is related to; consider making it an instance of Binder

All Implemented Interfaces:

Binder, TestRule

public class ServiceLocatorTestRule<T>
extends ExternalResource
implements Binder

An ExternalResource (and a Binder) that sets up and tears down an HK2 ServiceLocator on a per-test-class or per-test-method basis.

Since:

2.4.0-b33

Author:

Laird Nelson

See Also:

• ExternalResource
• Binder

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	ServiceLocatorTestRule.ServiceLocatorIsolation	An enum describing possible ServiceLocator isolation levels for JUnit tests.

Constructor Summary

Constructors

Constructor	Description
ServiceLocatorTestRule(T test)	Creates a new ServiceLocatorTestRule on behalf of the supplied JUnit test in ServiceLocatorTestRule.ServiceLocatorIsolation.PER_TEST isolation in non-verbose mode.
ServiceLocatorTestRule(T test, boolean verbose)	Creates a new ServiceLocatorTestRule on behalf of the supplied JUnit test in ServiceLocatorTestRule.ServiceLocatorIsolation.PER_TEST isolation with the supplied verbosity.
ServiceLocatorTestRule(T test, ServiceLocatorTestRule.ServiceLocatorIsolation isolation)	Creates a new ServiceLocatorTestRule on behalf of the supplied JUnit test in the given ServiceLocatorTestRule.ServiceLocatorIsolation in non-verbose mode.
ServiceLocatorTestRule(T test, ServiceLocatorTestRule.ServiceLocatorIsolation isolation, boolean verbose)	Creates a new ServiceLocatorTestRule on behalf of the supplied JUnit test in the given ServiceLocatorTestRule.ServiceLocatorIsolation.

Method Summary

Modifier and Type	Method	Description
void	after()	Shuts down and cleans up the ServiceLocator created by this ServiceLocatorTestRule.
Statement	apply(Statement statement, Description description)	Overrides the ExternalResource.apply(Statement, Description) method to save the supplied Description so that other methods in this class can refer to it.
void	before()	When necessary, calls the createServiceLocator(Description), configureServiceLocator(ServiceLocator, Description) and performDependencyInjection(ServiceLocator, Object) methods in order to set up a ServiceLocator appropriate for the current JUnit test.
void	bind(DynamicConfiguration dynamicConfiguration)	Called at the appropriate time by the configureServiceLocator(ServiceLocator, Description) method in case subclasses wish to add services to the ServiceLocator being configured.
protected void	configureServiceLocator(ServiceLocator serviceLocator, Description testDescription)	Configures the supplied ServiceLocator for use by the test described by the supplied Description.
protected ServiceLocator	createServiceLocator(Description testDescription)	Creates and returns a ServiceLocator suitable for the JUnit test described by the supplied Description.
protected String	getClasspath()	Returns a String representing the classpath to use to search for classes.
final ServiceLocatorTestRule.ServiceLocatorIsolation	getServiceLocatorIsolation()	Returns the ServiceLocatorTestRule.ServiceLocatorIsolation for this ServiceLocatorTestRule.
protected String	getServiceLocatorName(Description testDescription)	Returns a name for a ServiceLocator that is appropriate for the supplied Description.
final boolean	isVerbose()	Returns true if this ServiceLocatorTestRule should output additional information to System.out.
protected void	performDependencyInjection(ServiceLocator serviceLocator, T test)	Performs HK2 dependency injection on this ServiceLocatorTestRule and the supplied test instance, using the supplied ServiceLocator as needed.
void	shutdownAndDestroyServiceLocator(Description testDescription)	Blindly calls the ServiceLocator.shutdown() and ServiceLocatorFactory.destroy(ServiceLocator) methods on this ServiceLocatorTestRule's associated ServiceLocator if it is discovered to be non-null.

Methods inherited from class java.lang.Object

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

Constructor Details

ServiceLocatorTestRule

public ServiceLocatorTestRule(T test)

Creates a new ServiceLocatorTestRule on behalf of the supplied JUnit test in ServiceLocatorTestRule.ServiceLocatorIsolation.PER_TEST isolation in non-verbose mode.

Parameters:

test - the JUnit test; must not be null

Throws:

AssertionError - if test is null

See Also:

• ServiceLocatorTestRule(Object, ServiceLocatorIsolation, boolean)

ServiceLocatorTestRule

public ServiceLocatorTestRule(T test,
 boolean verbose)

Creates a new ServiceLocatorTestRule on behalf of the supplied JUnit test in ServiceLocatorTestRule.ServiceLocatorIsolation.PER_TEST isolation with the supplied verbosity.

Parameters:

test - the JUnit test; must not be null

verbose - whether this ServiceLocatorTestRule should output additional information to System.out

Throws:

AssertionError - if test is null

See Also:

• ServiceLocatorTestRule(Object, ServiceLocatorIsolation, boolean)

ServiceLocatorTestRule

public ServiceLocatorTestRule(T test,
 ServiceLocatorTestRule.ServiceLocatorIsolation isolation)

Creates a new ServiceLocatorTestRule on behalf of the supplied JUnit test in the given ServiceLocatorTestRule.ServiceLocatorIsolation in non-verbose mode.

Parameters:

test - the JUnit test; must not be null

isolation - the ServiceLocatorTestRule.ServiceLocatorIsolation; if null then ServiceLocatorTestRule.ServiceLocatorIsolation.PER_TEST will be used instead

Throws:

AssertionError - if test is null

See Also:

• ServiceLocatorTestRule(Object, ServiceLocatorIsolation, boolean)

ServiceLocatorTestRule

public ServiceLocatorTestRule(T test,
 ServiceLocatorTestRule.ServiceLocatorIsolation isolation,
 boolean verbose)

Creates a new ServiceLocatorTestRule on behalf of the supplied JUnit test in the given ServiceLocatorTestRule.ServiceLocatorIsolation.

Parameters:

test - the JUnit test; must not be null

isolation - the ServiceLocatorTestRule.ServiceLocatorIsolation; if null then ServiceLocatorTestRule.ServiceLocatorIsolation.PER_TEST will be used instead

verbose - whether this ServiceLocatorTestRule should output additional information to System.out

Throws:

AssertionError - if test is null

Method Details

getServiceLocatorIsolation

public final ServiceLocatorTestRule.ServiceLocatorIsolation getServiceLocatorIsolation()

Returns the ServiceLocatorTestRule.ServiceLocatorIsolation for this ServiceLocatorTestRule.

This method never returns null.

Returns:

the ServiceLocatorTestRule.ServiceLocatorIsolation for this ServiceLocatorTestRule; never null

isVerbose

public final boolean isVerbose()

Returns true if this ServiceLocatorTestRule should output additional information to System.out.

Returns:

true if this ServiceLocatorTestRule should be verbose; false otherwise

See Also:

• ServiceLocatorUtilities.dumpAllDescriptors(ServiceLocator, PrintStream)

before

public void before()
            throws IOException

When necessary, calls the createServiceLocator(Description), configureServiceLocator(ServiceLocator, Description) and performDependencyInjection(ServiceLocator, Object) methods in order to set up a ServiceLocator appropriate for the current JUnit test.

Overrides:

before in class ExternalResource

Throws:

IOException - if the configureServiceLocator(ServiceLocator, Description) method threw an IOException

See Also:

• createServiceLocator(Description)
• configureServiceLocator(ServiceLocator, Description)
• performDependencyInjection(ServiceLocator, Object)

configureServiceLocator

protected void configureServiceLocator(ServiceLocator serviceLocator,
 Description testDescription)
                                throws IOException

Configures the supplied ServiceLocator for use by the test described by the supplied Description.

This implementation:

1. Adds the ErrorServiceImpl class to the supplied ServiceLocator so that exceptions will be thrown from tests
2. Removes, via DynamicConfiguration.addUnbindFilter(Filter), all Descriptors that have Description.class as one of their contracts
3. Adds a constant descriptor in Singleton scope with a name equal to the return value of the Description.getDisplayName() method for the supplied Description so that the current test can inject the Description for the current method if it wishes
4. Adds any classes found in an optional Classes annotation decorating the test class—if they are assignable to Factory.class then they are added as factories
5. Adds any classes found in any packages listed in an optional Packages annotation decorating the test class, provided they are annotated with Service
6. Reads any locator files listed in an optional InhabitantFiles annotation decorating the test class and adds the services listed therein
7. Calls the bind(DynamicConfiguration) method
8. Calls the Binder.bind(DynamicConfiguration) method on the test if it is in fact an instance of Binder

Parameters:

serviceLocator - the ServiceLocator to configure; must not be null

testDescription - the Description describing the particular test being run; must not be null

Throws:

AssertionError - if either serviceLocator or testDescription is null

IOException - if there was an error looking for classes in packages or finding or reading locator files

bind

public void bind(DynamicConfiguration dynamicConfiguration)

Called at the appropriate time by the configureServiceLocator(ServiceLocator, Description) method in case subclasses wish to add services to the ServiceLocator being configured.

Overrides of this method must not invoke the DynamicConfiguration.commit() method.

The default implementation of this method does nothing.

Specified by:

bind in interface Binder

Parameters:

dynamicConfiguration - the DynamicConfiguration to manipulate in order to add or remove services from the ServiceLocator being configured; must not be null

getClasspath

protected String getClasspath()

Returns a String representing the classpath to use to search for classes.

This method never returns null.

Overrides of this method are permitted to return null.

The default implementation of this method returns the value of the java.class.path system property, or in the almost certainly catastrophic case where this is not set, the empty string.

Returns:

a String representing the classpath, or null

performDependencyInjection

protected void performDependencyInjection(ServiceLocator serviceLocator,
 T test)

Performs HK2 dependency injection on this ServiceLocatorTestRule and the supplied test instance, using the supplied ServiceLocator as needed.

The default implementation of this method does the following:

1. Calls ServiceLocator.inject(Object) on the supplied ServiceLocator, if it is non-null, passing it this ServiceLocatorTestRule
2. Calls ServiceLocator.postConstruct(Object) on the supplied ServiceLocator, if it is non-null, passing it this ServiceLocatorTestRule
3. Calls ServiceLocator.inject(Object) on the supplied ServiceLocator, if it is non-null, passing it the supplied test instance, if it is non-null
4. Calls ServiceLocator.postConstruct(Object) on the supplied ServiceLocator, if it is non-null, passing it the supplied test instance, if it is non-null

This method is guaranteed to be called after the configureServiceLocator(ServiceLocator, Description) method with the same ServiceLocator.

Parameters:

serviceLocator - the ServiceLocator to use to perform injection; may be null in which case no action will be taken

test - the test instance to inject; may be null

See Also:

• bind(DynamicConfiguration)
• configureServiceLocator(ServiceLocator, Description)

createServiceLocator

protected ServiceLocator createServiceLocator(Description testDescription)

Creates and returns a ServiceLocator suitable for the JUnit test described by the supplied Description.

This method never returns null.

Overrides of this method must not return null.

Parameters:

testDescription - the Description describing the currently executing JUnit test; must not be null

Returns:

a non-null ServiceLocator

Throws:

AssertionError - if testDescription is null

getServiceLocatorName

protected String getServiceLocatorName(Description testDescription)

Returns a name for a ServiceLocator that is appropriate for the supplied Description.

This method never returns null.

Overrides of this method must not return null.

Parameters:

testDescription - the Description describing the currently executing JUnit test; must not be null

Returns:

a non-null String that will be used as a name for a ServiceLocator

Throws:

AssertionError - if testDescription is null, or if its getClassName() method returns null or if its getMethodName() method returns null

apply

public Statement apply(Statement statement,
 Description description)

Overrides the ExternalResource.apply(Statement, Description) method to save the supplied Description so that other methods in this class can refer to it.

This method never returns null.

Overrides of this method must not return null.

Specified by:

apply in interface TestRule

Overrides:

apply in class ExternalResource

Parameters:

statement - the Statement this ServiceLocatorTestRule will modify; passed unchanged to the ExternalResource.apply(Statement, Description) method

description - the Description describing the current JUnit test; must not be null; passed unchanged to the ExternalResource.apply(Statement, Description) method

Returns:

the return value of the ExternalResource.apply(Statement, Description) method; never null

after

public void after()

Shuts down and cleans up the ServiceLocator created by this ServiceLocatorTestRule.

This method performs the following actions in order:

1. Calls the ServiceLocator.preDestroy(Object) method on the existing ServiceLocator, passing it the test instance supplied at construction time
2. Calls the ServiceLocator.preDestroy(Object) method on the existing ServiceLocator, passing it this ServiceLocatorTestRule
3. If the ServiceLocator isolation level is PER_TEST, calls the shutdownAndDestroyServiceLocator(Description) method with a Description instance that describes the JUnit test method that just executed

Overrides:

after in class ExternalResource

See Also:

• shutdownAndDestroyServiceLocator(Description)

shutdownAndDestroyServiceLocator

public void shutdownAndDestroyServiceLocator(Description testDescription)

Blindly calls the ServiceLocator.shutdown() and ServiceLocatorFactory.destroy(ServiceLocator) methods on this ServiceLocatorTestRule's associated ServiceLocator if it is discovered to be non-null.

Parameters:

testDescription - a Description describing the currently executing JUnit test, if any; ignored by this method's default implementation; may be null