org.jboss.cache.factories
Class ComponentRegistry

java.lang.Object
  org.jboss.cache.factories.ComponentRegistry

public class ComponentRegistry
extends Object

A registry where components which have been created are stored. Components are stored as singletons, registered under a specific name. When retrieving components from the registry, callers may specify a component name or just the type of component needed (in which case the fully qualified class name is used as the component name).

Components can be retrieved from the registry using getComponent(Class), or they can be constructed using getOrCreateComponent(String, Class) which will scan for default factories and attempt to use such factpries to create the component if needed.

Default factories are treated as components too and will need to be wired and started before being used.

Components can exist in one of 4 states, as defined by the ComponentRegistry.State enumeration. The component registry also has a state for the overall component set. While some components may move to the ComponentRegistry.State.STARTED state before others (such as factories to create other components) the ComponentRegistry's overall state depicts the lowest possible form for all components.

In terms of the cache, overall state changes in the following manner:

• CONSTRUCTED - when created using the DefaultCacheFactory
• WIRED - when Cache.create() is called
• STARTED - when Cache.start() is called
• STOPPED - when Cache.stop() is called

Cache configuration can only be changed and will only be reinjected if the cache is not in the CacheStatus.STARTED state.

Since:

2.1.0

Author:

Manik Surtani (manik@jboss.org)

Nested Class Summary

static class

ComponentRegistry.State Represents the state of a component

Constructor Summary

ComponentRegistry(Configuration configuration)
Creates an instance of the component registry.

Method Summary

protected void	addComponentDependencies(org.jboss.cache.factories.ComponentRegistry.Component c, boolean firstTimeAdded)
<T> T	getComponent(Class<T> c)
<T> T	getComponent(String name, Class<T> c) Retrieves a named component which can be assigned to the type passed in.
protected ComponentFactory	getFactory(Class componentClass) Retrieves a component factory instance capable of constructing components of a specified type.
<T> T	getOrCreateComponent(Class<T> componentClass) Retrieves a named component if one exists, and if not, attempts to find a factory capable of constructing the component (factories annotated with the DefaultFactoryFor annotation that is capable of creating the component class).
<T> T	getOrCreateComponent(String componentName, Class<T> componentClass) Retrieves a named component if one exists, and if not, attempts to find a factory capable of constructing the component (factories annotated with the DefaultFactoryFor annotation that is capable of creating the component class).
ComponentRegistry.State	getOverallState()
void	registerComponent(Object component, Class type) Adds a singleton instance to the registry.
void	registerComponent(String name, Object component, Class type) Adds an instance component to the registry, registering the component under the given name.
void	registerDefaultClassLoader(ClassLoader loader) Registers the default class loader.
void	reset() Wipes everything in the registry.
void	start() Starts all components that contain the Start annotation.
void	stop() Stops all components that contain the Stop annotation.
void	unregisterComponent(Class<?> clazz) Removes a component from the registry.
void	unregisterComponent(String name) Removes a component from the registry.
void	updateDependencies() Updates (re-injects) any dependencies needed by all components already in the registry.
void	wire() Injects dependencies to all components that require injection.
void	wireDependencies(Object target) Wires an object instance with dependencies annotated with the Inject annotation, creating more components as needed based on the Configuration passed in if these additional components don't exist in the ComponentRegistry.

Methods inherited from class java.lang.Object

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

Constructor Detail

ComponentRegistry

public ComponentRegistry(Configuration configuration)

Creates an instance of the component registry. The configuration passed in is automatically registered.

Parameters:

configuration -

Method Detail

registerDefaultClassLoader

public void registerDefaultClassLoader(ClassLoader loader)

Registers the default class loader. This method *must* be called before any other components are registered, typically called by bootstrap code. Defensively, it is called in the constructor of ComponentRegistry with a null parameter.

Parameters:

loader - a class loader to use by default. If this is null, the class loader used to load this instance of ComponentRegistry is used.

getOverallState

public ComponentRegistry.State getOverallState()

registerComponent

public void registerComponent(Object component,
                              Class type)

Adds a singleton instance to the registry. Note that if an instance of this component already exists in the registry it is overwritten. The instance is registered under type component.getClass(). If the component implements an interface or extends an abstract class, it may make more sense to use registerComponent(String, Object, Class)

The status of the component is updated th the overall state of the registry, which may involve calling of methods annotated with Inject, Start or Stop.

Parameters:

component - component to add to the registry.

registerComponent

public void registerComponent(String name,
                              Object component,
                              Class type)

Adds an instance component to the registry, registering the component under the given name. If an instance already exists in the registry under the given name, it will be overwritten.

The status of the component is updated th the overall state of the registry, which may involve calling of methods annotated with Inject, Start or Stop.

Parameters:

name - name of the instance

component - component to add

addComponentDependencies

protected void addComponentDependencies(org.jboss.cache.factories.ComponentRegistry.Component c,
                                        boolean firstTimeAdded)

getComponent

public <T> T getComponent(Class<T> c)

getComponent

public <T> T getComponent(String name,
                          Class<T> c)

Retrieves a named component which can be assigned to the type passed in. Will return a null if no such component is registered

Parameters:

c - type to be able to assign component to.

Returns:

component, if found, or a null otherwise.

getOrCreateComponent

public <T> T getOrCreateComponent(Class<T> componentClass)

Retrieves a named component if one exists, and if not, attempts to find a factory capable of constructing the component (factories annotated with the DefaultFactoryFor annotation that is capable of creating the component class).

If an instance needs to be constructed, dependencies are then automatically wired into the instance, based on methods on the component type annotated with Inject.

Summing it up, component retrieval happens in the following order:
1. Look for an appropriate component that exists in the Configuration that may be injected from an external system. 2. Look for a class definition passed in to the Configuration - such as an EvictionPolicy implementation 3. Attempt to create it by looking for an appropriate factory (annotated with DefaultFactoryFor)

Parameters:

componentClass - type of component to be retrieved. Should not be null.

Returns:

a fully wired component instance, or null if one cannot be found or constructed.

Throws:

ConfigurationException - if there is a problem with consructing or wiring the instance.

getOrCreateComponent

public <T> T getOrCreateComponent(String componentName,
                                  Class<T> componentClass)

Retrieves a named component if one exists, and if not, attempts to find a factory capable of constructing the component (factories annotated with the DefaultFactoryFor annotation that is capable of creating the component class).

If an instance needs to be constructed, dependencies are then automatically wired into the instance, based on methods on the component type annotated with Inject.

Summing it up, component retrieval happens in the following order:
1. Look for an appropriate component that exists in the Configuration that may be injected from an external system. 2. Look for a class definition passed in to the Configuration - such as an EvictionPolicy implementation 3. Attempt to create it by looking for an appropriate factory (annotated with DefaultFactoryFor)

Parameters:

componentName - name of component to be created. If null, uses the fully qualified class name as component name.

componentClass - type of component to be retrieved. Should not be null.

Returns:

a fully wired component instance, or null if one cannot be found or constructed.

Throws:

ConfigurationException - if there is a problem with consructing or wiring the instance.

updateDependencies

public void updateDependencies()

Updates (re-injects) any dependencies needed by all components already in the registry.

unregisterComponent

public void unregisterComponent(Class<?> clazz)

Removes a component from the registry. If the component has already been injected into other components, you should call updateDependencies() to ensure dependencies are updated.

Parameters:

clazz - class of component to remove.

unregisterComponent

public void unregisterComponent(String name)

Removes a component from the registry. If the component has already been injected into other components, you should call updateDependencies() to ensure dependencies are updated.

Parameters:

name - name of the component to remove.

wireDependencies

public void wireDependencies(Object target)
                      throws ConfigurationException

Wires an object instance with dependencies annotated with the Inject annotation, creating more components as needed based on the Configuration passed in if these additional components don't exist in the ComponentRegistry. Strictly for components that don't otherwise live in the registry and have a lifecycle, such as Nodes.

Parameters:

target - object to wire

Throws:

ConfigurationException - if there is a problem wiring the instance

getFactory

protected ComponentFactory getFactory(Class componentClass)

Retrieves a component factory instance capable of constructing components of a specified type. If the factory doesn't exist in the registry, one is created. Always changes the state of any factory to ComponentRegistry.State.STARTED before returning.

Parameters:

componentClass - type of component to construct

Returns:

component factory capable of constructing such components

reset

public void reset()

Wipes everything in the registry. Use with care.

start

public void start()

Starts all components that contain the Start annotation.

stop

public void stop()

Stops all components that contain the Stop annotation.

wire

public void wire()

Injects dependencies to all components that require injection.