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, org.junit.rules.TestRule

public class ServiceLocatorTestRule<T>
extends org.junit.rules.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

See Also:

ExternalResource, Binder

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ServiceLocatorTestRule.ServiceLocatorIsolation	An enum describing possible ServiceLocator isolation levels for JUnit tests.
private static class	ServiceLocatorTestRule.Visitor	A very, very special-purpose ClassVisitorImpl suitable only for use by the ServiceLocatorTestRule class to determine efficiently whether a given Class is annotated with Service or not.

Field Summary

Fields

Modifier and Type	Field	Description
private org.junit.runner.Description	description	The Description describing the JUnit test method currently executing.
private ServiceLocatorTestRule.ServiceLocatorIsolation	isolation	The ServiceLocatorTestRule.ServiceLocatorIsolation designating whether the ServiceLocator associated with this ServiceLocatorTestRule is set up for each test method or shared among them.
private ServiceLocator	serviceLocator	The ServiceLocator in effect for the currently executing JUnit test method.
private T	test	The test instance instantiating this ServiceLocatorTestRule.
private boolean	verbose	A boolean indicating whether this ServiceLocatorTestRule is configured to output additional information to System.out.

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.
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement statement, org.junit.runner.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.
private static void	bind(DynamicConfiguration configuration, java.io.BufferedReader reader)	Reads the HK2 locator file represented by the supplied BufferedReader and binds the Descriptors it represents.
private void	bind(DynamicConfiguration configuration, java.lang.reflect.AnnotatedElement element)	Retrieves any Annotations found on the supplied AnnotatedElement and calls the bind(DynamicConfiguration, Collection) method supplying them as the second parameter.
private static void	bind(DynamicConfiguration configuration, java.lang.String locatorResourceName)	Using the context ClassLoader, gets all classpath resources with the supplied locatorResourceName, and iterates through them, calling the bind(DynamicConfiguration, URL) method for each one.
private static void	bind(DynamicConfiguration configuration, java.net.URL locatorResource)	Opens an InputStream to the supplied URL, wraps a BufferedReader around it, and calls the bind(DynamicConfiguration, BufferedReader) method.
private void	bind(DynamicConfiguration configuration, java.util.Collection<? extends java.lang.annotation.Annotation> annotations)	Recursively examines the Annotations supplied looking for instances of the Classes, InhabitantFiles and Packages annotations, and, using the binding methods on the supplied DynamicConfiguration binds Descriptors for those "reachable" classes into the configuration.
private void	bind(DynamicConfiguration configuration, java.util.Set<java.lang.String> packageNames)	Binds all Classes "reachable" from the supplied packages.
private void	bind(DynamicConfiguration configuration, Classes classes)	Binds all Classes "reachable" from the supplied Classes annotation.
private static void	bind(DynamicConfiguration configuration, InhabitantFiles inhabitantFiles)	Gathers all classpath resource names found in the supplied InhabitantFiles annotation representing HK2 locator files and calls the bind(DynamicConfiguration, String) method for each such entry found.
private void	bind(DynamicConfiguration configuration, Packages packages)	Binds all Classes "reachable" from packages described by the supplied Packages annotation.
protected void	configureServiceLocator(ServiceLocator serviceLocator, org.junit.runner.Description testDescription)	Configures the supplied ServiceLocator for use by the test described by the supplied Description.
protected ServiceLocator	createServiceLocator(org.junit.runner.Description testDescription)	Creates and returns a ServiceLocator suitable for the JUnit test described by the supplied Description.
private static java.util.Set<java.lang.Class<?>>	getClassesFromDirectory(java.util.Set<java.lang.String> packageNames, java.io.File directory, boolean verbose)	Given a Set of package names and a File designating an existing directory in the classpath that can be read, returns a Set of Service-annotated Classes that can be found there that belong to one of the supplied package names.
private java.util.Set<java.lang.Class<?>>	getClassesFromPackages(java.util.Set<java.lang.String> packageNames)	Given a Set of package names, returns a Set of Service-annotated Classes found in those packages, whether they are located in ZipFiles or directories on the classpath.
private java.util.Set<java.lang.Class<?>>	getClassesFromZipFile(java.util.Set<java.lang.String> packageNames, java.util.zip.ZipFile zipFile)	Given a ZipFile (which is usually a .jar file) containing class files and a Set of package names, searches it to find Service-annotated Classes inside it that belong to one of the supplied package names and returns a Set of such Classes.
protected java.lang.String	getClasspath()	Returns a String representing the classpath to use to search for classes.
private org.junit.runner.Description	getDescription()	Returns the Description describing the currently executing JUnit test method.
ServiceLocatorTestRule.ServiceLocatorIsolation	getServiceLocatorIsolation()	Returns the ServiceLocatorTestRule.ServiceLocatorIsolation for this ServiceLocatorTestRule.
protected java.lang.String	getServiceLocatorName(org.junit.runner.Description testDescription)	Returns a name for a ServiceLocator that is appropriate for the supplied Description.
private static boolean	isBlacklisted(java.lang.annotation.Annotation annotation)	Returns true if the supplied Annotation is null or designates an annotation type that should be excluded from recursive annotation scanning performed by the bind(DynamicConfiguration, AnnotatedElement) method.
private static boolean	isBlacklisted(java.lang.Class<? extends java.lang.annotation.Annotation> c)	Returns true if the supplied Class is null or designates an annotation type that should be excluded from recursive annotation scanning performed by the bind(DynamicConfiguration, AnnotatedElement) method.
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(org.junit.runner.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

Field Detail

test

private final T test

The test instance instantiating this ServiceLocatorTestRule.

This field is never null.

isolation

private final ServiceLocatorTestRule.ServiceLocatorIsolation isolation

The ServiceLocatorTestRule.ServiceLocatorIsolation designating whether the ServiceLocator associated with this ServiceLocatorTestRule is set up for each test method or shared among them.

This field is never null.

verbose

private final boolean verbose

A boolean indicating whether this ServiceLocatorTestRule is configured to output additional information to System.out.

See Also:

isVerbose()

description

private org.junit.runner.Description description

The Description describing the JUnit test method currently executing.

This field may be null.

See Also:

apply(Statement, Description)

serviceLocator

private ServiceLocator serviceLocator

The ServiceLocator in effect for the currently executing JUnit test method.

This field may be null.

Constructor Detail

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:

java.lang.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:

java.lang.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:

java.lang.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:

java.lang.AssertionError - if test is null

Method Detail

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

getDescription

private final org.junit.runner.Description getDescription()

Returns the Description describing the currently executing JUnit test method.

This method may return null.

Returns:

the Description describing the currently executing JUnit test method, or 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 java.io.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 org.junit.rules.ExternalResource

Throws:

java.io.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,
                                       org.junit.runner.Description testDescription)
                                throws java.io.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:

java.lang.AssertionError - if either serviceLocator or testDescription is null

java.io.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

getClassesFromPackages

private final java.util.Set<java.lang.Class<?>> getClassesFromPackages(java.util.Set<java.lang.String> packageNames)
                                                                throws java.io.IOException

Given a Set of package names, returns a Set of Service-annotated Classes found in those packages, whether they are located in ZipFiles or directories on the classpath.

This method never returns null.

Parameters:

packageNames - the names of packages to search; may be null in which case an empty Set will be returned

Returns:

a non-null Set of Classes

Throws:

java.io.IOException - if there was any kind of error during package searching or file reading

See Also:

getClassesFromDirectory(Set, File, boolean), getClassesFromZipFile(Set, ZipFile)

getClassesFromZipFile

private final java.util.Set<java.lang.Class<?>> getClassesFromZipFile(java.util.Set<java.lang.String> packageNames,
                                                                      java.util.zip.ZipFile zipFile)
                                                               throws java.io.IOException

Given a ZipFile (which is usually a .jar file) containing class files and a Set of package names, searches it to find Service-annotated Classes inside it that belong to one of the supplied package names and returns a Set of such Classes.

Parameters:

packageNames - a Set of package names; may be null in which case an empty Set will be returned

zipFile - a ZipFile hopefully containing class files; may be null in which case an empty Set will be returned

Returns:

a non-null Set of Service-annotated Classes

Throws:

java.io.IOException - if an error occurred reading the ZipFile

getClasspath

protected java.lang.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

bind

private final void bind(DynamicConfiguration configuration,
                        java.lang.reflect.AnnotatedElement element)
                 throws java.io.IOException

Retrieves any Annotations found on the supplied AnnotatedElement and calls the bind(DynamicConfiguration, Collection) method supplying them as the second parameter.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

element - the AnnotatedElement that has annotations; may be null in which case no action is performed

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading class or locator files

See Also:

bind(DynamicConfiguration, Collection)

bind

private final void bind(DynamicConfiguration configuration,
                        java.util.Collection<? extends java.lang.annotation.Annotation> annotations)
                 throws java.io.IOException

Recursively examines the Annotations supplied looking for instances of the Classes, InhabitantFiles and Packages annotations, and, using the binding methods on the supplied DynamicConfiguration binds Descriptors for those "reachable" classes into the configuration.

Recursively means that a user-defined Annotation might itself be annotated with Classes; in such a case the Classes annotation's contents will be found and processed. This effectively allows stereotyping the Classes, InhabitantFiles and Packages annotations.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

annotations - a Collection of Annotations; may be null in which case no action will be performed

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading class or locator files

See Also:

bind(DynamicConfiguration, Classes), bind(DynamicConfiguration, InhabitantFiles), bind(DynamicConfiguration, Packages)

bind

private final void bind(DynamicConfiguration configuration,
                        Classes classes)
                 throws java.io.IOException

Binds all Classes "reachable" from the supplied Classes annotation.

Each Class found as a member of the return value of the Classes.value() method is bound (even if it is an implementation of Factory) and in turn is examined for Annotations on itself.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

classes - a Classes; may be null in which case no action will be performed

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading class files or locator files

See Also:

DynamicConfiguration.addActiveDescriptor(Class), DynamicConfiguration.addActiveFactoryDescriptor(Class)

bind

private final void bind(DynamicConfiguration configuration,
                        Packages packages)
                 throws java.io.IOException

Binds all Classes "reachable" from packages described by the supplied Packages annotation.

This method calls the bind(DynamicConfiguration, Set) method, passing it a Set formed from the supplied Packages annotation's list of package names as the second parameter.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

packages - a Packages; may be null in which case no action will be performed

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading class files or locator files

See Also:

bind(DynamicConfiguration, Set)

bind

private final void bind(DynamicConfiguration configuration,
                        java.util.Set<java.lang.String> packageNames)
                 throws java.io.IOException

Binds all Classes "reachable" from the supplied packages.

This method calls the getClassesFromPackages(Set) method, and, for each Class returned, if it is an implementation of Factory then two Descriptors are added to the DynamicConfigurationin the form of a FactoryDescriptorsaddition by way of the DynamicConfiguration.addActiveFactoryDescriptor(Class) method, or, if not, then a single Descriptoris added to the DynamicConfiguration.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

packageNames - a Set of package names; may be null in which case no action will be performed

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading class files or locator files

See Also:

getClassesFromPackages(Set), DynamicConfiguration.addActiveDescriptor(Class), DynamicConfiguration.addActiveFactoryDescriptor(Class)

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(org.junit.runner.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:

java.lang.AssertionError - if testDescription is null

getServiceLocatorName

protected java.lang.String getServiceLocatorName(org.junit.runner.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:

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

apply

public org.junit.runners.model.Statement apply(org.junit.runners.model.Statement statement,
                                               org.junit.runner.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 org.junit.rules.TestRule

Overrides:

apply in class org.junit.rules.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 ServiceLocatorisolation 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 org.junit.rules.ExternalResource

See Also:

shutdownAndDestroyServiceLocator(Description)

shutdownAndDestroyServiceLocator

public void shutdownAndDestroyServiceLocator(org.junit.runner.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

getClassesFromDirectory

private static final java.util.Set<java.lang.Class<?>> getClassesFromDirectory(java.util.Set<java.lang.String> packageNames,
                                                                               java.io.File directory,
                                                                               boolean verbose)
                                                                        throws java.io.IOException

Given a Set of package names and a File designating an existing directory in the classpath that can be read, returns a Set of Service-annotated Classes that can be found there that belong to one of the supplied package names.

This method never returns null.

Parameters:

packageNames - a Set of package names; may be null in which case an empty Set will be returned

directory - a File designating a directory; an empty Set will be returned unless the directory so designated exists and is readable

verbose - whether additional information should be output

Returns:

a non-null Set of Service-annotated Classes

Throws:

java.io.IOException - if there was a problem reading files

isBlacklisted

private static final boolean isBlacklisted(java.lang.annotation.Annotation annotation)

Returns true if the supplied Annotation is null or designates an annotation type that should be excluded from recursive annotation scanning performed by the bind(DynamicConfiguration, AnnotatedElement) method.

Parameters:

annotation - the Annotation to consider; may be null in which case true will be returned

Returns:

true if the supplied Annotation is null or designates an annotation type that should be excluded from recursive annotation scanning performed by the bind(DynamicConfiguration, AnnotatedElement) method

See Also:

isBlacklisted(Class)

isBlacklisted

private static final boolean isBlacklisted(java.lang.Class<? extends java.lang.annotation.Annotation> c)

Returns true if the supplied Class is null or designates an annotation type that should be excluded from recursive annotation scanning performed by the bind(DynamicConfiguration, AnnotatedElement) method.

Parameters:

c - the Class to consider; may be null in which case true will be returned

Returns:

true if the supplied Class is null or designates an annotation type that should be excluded from recursive annotation scanning performed by the bind(DynamicConfiguration, AnnotatedElement) method; false otherwise

bind

private static final void bind(DynamicConfiguration configuration,
                               InhabitantFiles inhabitantFiles)
                        throws java.io.IOException

Gathers all classpath resource names found in the supplied InhabitantFiles annotation representing HK2 locator files and calls the bind(DynamicConfiguration, String) method for each such entry found.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

inhabitantFiles - an InhabitantFiles; may be null in which case no action will be performed

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading locator files

See Also:

bind(DynamicConfiguration, String)

bind

private static final void bind(DynamicConfiguration configuration,
                               java.lang.String locatorResourceName)
                        throws java.io.IOException

Using the context ClassLoader, gets all classpath resources with the supplied locatorResourceName, and iterates through them, calling the bind(DynamicConfiguration, URL) method for each one.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

locatorResourceName - the name of a classpath resource identifying one or more HK2 locator files; may be null in which case no action will be performed

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading locator files

See Also:

ClassLoader.getResources(String), Thread.getContextClassLoader(), bind(DynamicConfiguration, URL)

bind

private static final void bind(DynamicConfiguration configuration,
                               java.net.URL locatorResource)
                        throws java.io.IOException

Opens an InputStream to the supplied URL, wraps a BufferedReader around it, and calls the bind(DynamicConfiguration, BufferedReader) method.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

locatorResource - a URL to an HK2 locator resource; may be null in which case no action will be taken

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading locator files

See Also:

bind(DynamicConfiguration, BufferedReader)

bind

private static final void bind(DynamicConfiguration configuration,
                               java.io.BufferedReader reader)
                        throws java.io.IOException

Reads the HK2 locator file represented by the supplied BufferedReader and binds the Descriptors it represents.

Parameters:

configuration - a DynamicConfiguration that will perform the binding; must not be null

reader - a BufferedReader reading a stream of descriptor information as parseable by the DescriptorImpl.readObject(BufferedReader) method; may be null in which case no action will be performed

Throws:

java.lang.AssertionError - if configuration is null

java.io.IOException - if there was a problem reading locator files

See Also:

DescriptorImpl.readObject(BufferedReader), DynamicConfiguration.bind(Descriptor)