2.17.2: 2011-06-17

net.sf.basedb.util.extensions
Class Registry

java.lang.Object
  extended by net.sf.basedb.util.extensions.Registry

public class Registry
extends Object

A registry for keeping track of extensions points and installed extensions. Extension points and extensions can, for example, be created programmatically using the ExtensionPointBean and ExtensionBean implementations, or loaded from an XML extension definition file with the XmlLoader class. Applications may provide other means of creating and registering extensions and extensions points.

Version:
2.7
Author:
nicklas
See Also:
ExtensionsDirectory
Last modified
$Date:2008-03-20 12:15:25 +0100 (Thu, 20 Mar 2008) $

Nested Class Summary
(package private) static class Registry.AttributeKey
          Identifies attribute.
(package private) static class Registry.RegisteredAbout
           
(package private) static class Registry.RegisteredExtension<A extends Action>
          Internal representation of an extension.
(package private) static class Registry.RegisteredExtensionPoint<A extends Action>
          Internal representation of an extension point.
 
Field Summary
private  Map<Registry.AttributeKey,Object> attributes
           
private static ExtensionsFilter DEFAULT_FILTER
          Default filter implementation for useExtensions(ClientContext, ExtensionsFilter, String...)
private  ErrorHandlerFactory<Action> defaultErrorHandlerFactory
           
private  Map<EventHandler,EventFilter> eventHandlers
           
private static Comparator<ExtensionPoint<?>> EXTENSIONPOINT_COMPARATOR
           
private  Map<String,Registry.RegisteredExtensionPoint<?>> extensionPoints
           
private  Map<String,Registry.RegisteredExtension<?>> extensions
           
private static Logger log
           
 
Constructor Summary
Registry()
          Create a new empty registry.
 
Method Summary
 boolean extensionIsRegistered(String id)
          Checks if an extension is registered or not.
 boolean extensionPointIsRegistered(String id)
          Checks if an extension point is registered or not.
 Object getAttribute(String id, String name)
          Get the value of a extra attribute for a registered extension or extension point.
 ErrorHandlerFactory<Action> getDefaultErrorHandlerFactory()
          Get the default error handler factory.
 Extension<?> getExtension(String id)
          Get the extension with a given ID.
 ExtensionPoint<?> getExtensionPoint(String id)
          Get the extension point with a given ID.
 Iterator<ExtensionPoint<?>> getExtensionPoints()
          Get an iterator returning all registered extension points.
 Iterator<Extension<?>> getExtensions()
          Get an iterator returning all registered extensions.
 Iterator<Extension<?>> getExtensions(String id)
          Get an iterator returning all registered extensions for a given extension point.
 Throwable getLastExtensionError(String id)
          Get information about the last error that happened when rendering an extension.
 Throwable getLastExtensionPointError(String id)
          Get information about the last error that happened when rendering an extension point.
 void handleEvent(EventType eventType, ExtensionPoint<?> extensionPoint, Extension<?> extension)
          Send an event to all event handlers.
 void registerEventHandler(EventHandler eventHandler, EventFilter filter)
          Register an event handler for responding to events happening to extension points and extensions in the registry.
<A extends Action>
void
registerExtension(Extension<A> extension)
          Register an extension.
<A extends Action>
void
registerExtensionPoint(ExtensionPoint<A> extensionPoint)
          Register an extension point.
 void setAttribute(String id, String name, Object value)
          Set an extra attribute on a registered extension or extension point.
 void setDefaultErrorHandlerFactory(ErrorHandlerFactory<Action> defaultErrorHandlerFactory)
          Set the default error handler factory.
 void unregisterEventHandler(EventHandler eventHandler)
          Unregisters an event handler.
 void unregisterExtension(String id)
          Unregister an extension.
 void unregisterExtensionPoint(String id)
          Unregister an extension point.
 ExtensionsInvoker<?> useExtensions(ClientContext clientContext, ExtensionsFilter filter, String... extensionPointIds)
          Use extensions from one or more extension points.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

private static final Logger log

EXTENSIONPOINT_COMPARATOR

private static final Comparator<ExtensionPoint<?>> EXTENSIONPOINT_COMPARATOR

extensionPoints

private final Map<String,Registry.RegisteredExtensionPoint<?>> extensionPoints

extensions

private final Map<String,Registry.RegisteredExtension<?>> extensions

attributes

private Map<Registry.AttributeKey,Object> attributes

eventHandlers

private Map<EventHandler,EventFilter> eventHandlers

defaultErrorHandlerFactory

private ErrorHandlerFactory<Action> defaultErrorHandlerFactory

DEFAULT_FILTER

private static final ExtensionsFilter DEFAULT_FILTER
Default filter implementation for useExtensions(ClientContext, ExtensionsFilter, String...)

Constructor Detail

Registry

public Registry()
Create a new empty registry.

Method Detail

setDefaultErrorHandlerFactory

public void setDefaultErrorHandlerFactory(ErrorHandlerFactory<Action> defaultErrorHandlerFactory)
Set the default error handler factory.

Parameters:
defaultErrorHandlerFactory - Null is not allowed
Since:
2.17

getDefaultErrorHandlerFactory

public ErrorHandlerFactory<Action> getDefaultErrorHandlerFactory()
Get the default error handler factory.

Since:
2.17

getAttribute

public Object getAttribute(String id,
                           String name)
Get the value of a extra attribute for a registered extension or extension point.

Parameters:
id - The ID of a registered extension or extension point
name - The name of the attribute
Returns:
The attribute value or null if no value has been set

setAttribute

public void setAttribute(String id,
                         String name,
                         Object value)
Set an extra attribute on a registered extension or extension point.

Parameters:
id - The ID of a registered extension or extension point
name - The name of the attribute
value - The attribute value. A null value removes the attribute.

registerEventHandler

public void registerEventHandler(EventHandler eventHandler,
                                 EventFilter filter)
Register an event handler for responding to events happening to extension points and extensions in the registry. The registry itself sends the events listed below. Other events may be sent externally by calling handleEvent(EventType, ExtensionPoint, Extension).

unregisterEventHandler

public void unregisterEventHandler(EventHandler eventHandler)
Unregisters an event handler.

Parameters:
eventHandler - The event handler
Since:
2.8

handleEvent

public void handleEvent(EventType eventType,
                        ExtensionPoint<?> extensionPoint,
                        Extension<?> extension)
Send an event to all event handlers.

Parameters:
eventType - The event type
extensionPoint - The extension point the event is about
extension - The extension the event is about, or null
Since:
2.8

extensionPointIsRegistered

public boolean extensionPointIsRegistered(String id)
Checks if an extension point is registered or not.

Parameters:
id - The ID of the extension point
Returns:
TRUE if an extension point with the given ID is registered, FALSE otherwise

registerExtensionPoint

public <A extends Action> void registerExtensionPoint(ExtensionPoint<A> extensionPoint)
Register an extension point. If the extension point already exists, the description and renderer factory is updated. The action class can't be changed for a registered extension point. The registry keeps it's own internal representation of the extension point. Changes to the object passed as a parameter to this method will not be reflected in the registry.

Parameters:
extensionPoint - The extension point to register
Throws:
InvalidUseOfNullException - If the extension point is null, or if the ID or actionClass is null
ClassCastException - If the action class doesn't implement the Action interface

unregisterExtensionPoint

public void unregisterExtensionPoint(String id)
Unregister an extension point. If the extension point doesn't exists, nothing is done. This method will also unregister all extensions that extends the given extension point.

Parameters:
id - The ID of the extension point to unregister
Throws:
InvalidUseOfNullException - If the ID is null

getExtensionPoint

public ExtensionPoint<?> getExtensionPoint(String id)
Get the extension point with a given ID.

Parameters:
id - The ID of the extension point
Returns:
An Registry.RegisteredExtensionPoint object or null if that extension point doesn't exists

getExtensionPoints

public Iterator<ExtensionPoint<?>> getExtensionPoints()
Get an iterator returning all registered extension points. The returned iterator doesn't support removal and will not reflect changes made to the registry by the same or other threads after this call has returned.

Returns:
An iterator object

extensionIsRegistered

public boolean extensionIsRegistered(String id)
Checks if an extension is registered or not.

Parameters:
id - The ID of the extension
Returns:
TRUE if an extension with the given ID is registered, FALSE otherwise

getLastExtensionPointError

public Throwable getLastExtensionPointError(String id)
Get information about the last error that happened when rendering an extension point.

Parameters:
id - The id of the extension point
Returns:
The error, or null if no error information is available
Since:
2.9

registerExtension

public <A extends Action> void registerExtension(Extension<A> extension)
Register an extension. If the extension is already registered, the description, position, action factory and renderer factory is updated. The registry keeps it's own internal representation of the extension. Changes made to the object passed as a parameter to this method will not be reflected in the registry.

Parameters:
extension - The extension to register
Throws:
InvalidUseOfNullException - If the extension is null, or if the ID or action factory is null

unregisterExtension

public void unregisterExtension(String id)
Unregister an extension. If the extension point doesn't exists, nothing is done.

Parameters:
id - The ID of the extension to unregister
Throws:
InvalidUseOfNullException - If the ID is null

getExtension

public Extension<?> getExtension(String id)
Get the extension with a given ID.

Parameters:
id - The ID of the extension point
Returns:
An Extension object or null if that extension doesn't exists

getLastExtensionError

public Throwable getLastExtensionError(String id)
Get information about the last error that happened when rendering an extension.

Parameters:
id - The id of the extension
Returns:
The error, or null if no error information is available
Since:
2.9

getExtensions

public Iterator<Extension<?>> getExtensions()
Get an iterator returning all registered extensions. The returned iterator doesn't support removal and will not reflect changes made to the registry by the same or other threads after this call has returned.

Returns:
An iterator object

getExtensions

public Iterator<Extension<?>> getExtensions(String id)
Get an iterator returning all registered extensions for a given extension point. If the extension point is not found an empty iterator is returned. The returned iterator doesn't support removal and will not reflect changes made to the registry by the same or other threads after this call has returned.

Parameters:
id - The ID of the extension point
Returns:
An iterator object

useExtensions

public ExtensionsInvoker<?> useExtensions(ClientContext clientContext,
                                          ExtensionsFilter filter,
                                          String... extensionPointIds)
Use extensions from one or more extension points. This method will return an invoker object that allows the use and rendering of extensions for one or more extension points. The context object should have been initialised with information about the currently logged in user and, depending on the application, some information about what it about to happen. For example, that we are going to display a list of samples.

Each extension that has been registered with the extension points will get a chance to check the context object and to further initialise it with extension-dependent information. This is a task for the ActionFactory.prepareContext(InvokationContext) method. If this method returns false the extension will not be included in the invoker. Extensions may for example use this to check if the logged in user has enough permissions to be able to use the extension.

If the extension points and/or extensions also provide renderer factories, the RendererFactory.prepareContext(InvokationContext) is called. For renderer factories that are attached to extension points the method is only called if at least one enabled extension exists. If the method is called, it is only called once with a null argument for the extension. Renderer factories that are attached to extensions are called once for each enabled extension, but only if the extension point allows renderer overriding. See Registry.RegisteredExtensionPoint.allowRendererOverride().

The returned invoker will not reflect changes made to the registry by the same or other threads after this call has returned. Each use/invokation of an extension point should call this method to get a new invoker object.

Parameters:
clientContext - Information about the current context
filter - A filter object that can be used to filter out disabled extensions and sort the extensions in a particular order. If this value is null, no extensions are filtered out and they are sorted according to their Extension.getIndex() value
extensionPointIds - An array of extension point ID:s to get extension for. In most cases the extension points should require the same action class but this is not required if the extension point renderer can handle more than one action type. Extension points that are not found are ignored.

2.17.2: 2011-06-17