org.sakaiproject.entitybroker.entityprovider
Interface EntityProviderManager

public interface EntityProviderManager

Handles all internal work of managing and working with the entity providers

Registration of entity brokers happens via spring, see the EntityProvider interface for details

Author:

Aaron Zeckoski (aaronz@vt.edu), Antranig Basman (antranig@caret.cam.ac.uk)

Method Summary

EntityPropertiesService	getEntityProperties() Allows access to the current EntityPropertiesService service
EntityProviderMethodStore	getEntityProviderMethodStore() Allows access to the current EntityProviderMethodStore service
List<Class<? extends EntityProvider>>	getPrefixCapabilities(String prefix) Get all the capabilities for a given entity prefix, WARNING: This is very inefficient so you should normally use getProviderByPrefixAndCapability(String, Class) when trying to determine if a provider implements a specific capability
<T extends EntityProvider> List<String>	getPrefixesByCapability(Class<T> capability) Gets the prefixes which support a specific capability
EntityProvider	getProviderByPrefix(String prefix) Get the entity provider by the prefix which uniquely defines all entities of a type, NOTE: this returns the CoreEntityProvider that handles the exists check (it may handle many other things as well), the basic EntityProvider if there is no CoreEntityProvider, OR null if neither exists
<T extends EntityProvider> T	getProviderByPrefixAndCapability(String prefix, Class<T> capability) Get the entity provider by the prefix which uniquely defines all entities of a type and also handles a specific capability NOTE: this returns the provider that handles this capability (it may handle many other things as well)
EntityProvider	getProviderByReference(String reference) Deprecated. this method is no longer functional or supported
<T extends EntityProvider> List<T>	getProvidersByCapability(Class<T> capability) Get all the entity providers which support a specific capability, this useful if you need to get the providers and call the capability methods on them directly
Map<String,List<Class<? extends EntityProvider>>>	getRegisteredEntityCapabilities() Get all registered prefixes and their capabilities, WARNING: This is very inefficient so you should normally use getProviderByPrefixAndCapability(String, Class) when trying to determine if a provider implements a specific capability
Set<String>	getRegisteredPrefixes() Retrieve a complete list of all currently registered EntityProviders
RequestGetterWrite	getRequestGetter() Allows access to the current RequestGetter service
RequestStorageWrite	getRequestStorage() Allows access to the current RequestStorage service
void	registerEntityProvider(EntityProvider entityProvider) Registers an entity provider with the manager, this allows registration to happen programatically but the preferred method is to use the AutoRegisterEntityProvider instead (see the EntityProvider interface), replaces an existing entity provider which uses the same prefix and handles the same capabilities if one is already registered, does not affect other providers which handle the same prefix but handle other capabilities NOTE: This allows developers to register providers from all over the code base without requiring all capabilities to live in the same project (i.e. allows for a large reduction in dependencies and conflicts)
<T extends EntityProvider> void	registerListener(EntityProviderListener<T> listener, boolean includeExisting) Registers a listener which is called whenever entity providers are registered depending on the filters in the EntityProviderListener This is particularly useful for capabilities which should/must be executed one time only and should not be called over and over OR will not do anything until they are triggered
void	unregisterCapability(String prefix, Class<? extends EntityProvider> capability) Unregisters an entity provider with the manager based on a prefix and capability, this will remove a registered entity broker from the manager registration, if the prefix and capability are not registered then no error is thrown NOTE: Attempting to unregister the base EntityProvider will cause an exception, if you want to completely unregister a type of entity you must use the unregisterEntityProviderByPrefix(String)
void	unregisterEntityProvider(EntityProvider entityProvider) Unregisters an entity provider with the manager, this will remove a registered entity broker from the manager registration, if the entity provider supplied is not registered then no error is thrown
void	unregisterEntityProviderByPrefix(String prefix) Unregisters an entity provider with the manager based on the entity prefix it handles, this will remove all registered entity providers from the manager registration by the prefix, if the entity provider prefix provided is not registered then no error is thrown This effectively purges the entire set of entity providers for a prefix
<T extends EntityProvider> void	unregisterListener(EntityProviderListener<T> listener) Unregisters the listener if it is registered or does nothing

Method Detail

getRegisteredPrefixes

Set<String> getRegisteredPrefixes()

Retrieve a complete list of all currently registered EntityProviders

Returns:

all currently registered entity providers

getProviderByReference

EntityProvider getProviderByReference(String reference)

Deprecated. this method is no longer functional or supported

Get the entity provider which handles the entity defined by an entity reference, this is a convenience method for getProviderByPrefix(String)
NOTE: this returns the CoreEntityProvider that handles the exists check (it may handle many other things as well) or returns null

Parameters:

reference - a globally unique reference to an entity

Returns:

the EntityProvider which handles this entity or null if none exists, fails if the reference is invalid

getProviderByPrefix

EntityProvider getProviderByPrefix(String prefix)

Get the entity provider by the prefix which uniquely defines all entities of a type,
NOTE: this returns the CoreEntityProvider that handles the exists check (it may handle many other things as well), the basic EntityProvider if there is no CoreEntityProvider, OR null if neither exists

Parameters:

prefix - the string which represents a type of entity handled by an entity provider

Returns:

the EntityProvider which handles this entity or null if none exists (only if prefix is not used)

getProviderByPrefixAndCapability

<T extends EntityProvider> T getProviderByPrefixAndCapability(String prefix,
                                                              Class<T> capability)

Get the entity provider by the prefix which uniquely defines all entities of a type and also handles a specific capability
NOTE: this returns the provider that handles this capability (it may handle many other things as well)

Type Parameters:

T - a class which extends EntityProvider

Parameters:

prefix - the string which represents a type of entity handled by an entity provider

capability - any entity provider capability class (these classes extend EntityProvider or CoreEntityProvider or another capability)

Returns:

the EntityProvider which handles this capability for this prefix or null if none exists or the prefix is not used

getProvidersByCapability

<T extends EntityProvider> List<T> getProvidersByCapability(Class<T> capability)

Get all the entity providers which support a specific capability, this useful if you need to get the providers and call the capability methods on them directly

Type Parameters:

T - a class which extends EntityProvider

Parameters:

capability - any entity provider capability class (these classes extend EntityProvider or CoreEntityProvider or another capability)

Returns:

the list of providers which implement the given capability, may be an empty list

getPrefixesByCapability

<T extends EntityProvider> List<String> getPrefixesByCapability(Class<T> capability)

Gets the prefixes which support a specific capability

Type Parameters:

T - a class which extends EntityProvider

Parameters:

capability - any entity provider capability class (these classes extend EntityProvider or CoreEntityProvider or another capability)

Returns:

the list of entity prefixes which support this capability, may be an empty list

getPrefixCapabilities

List<Class<? extends EntityProvider>> getPrefixCapabilities(String prefix)

Get all the capabilities for a given entity prefix, WARNING: This is very inefficient so you should normally use getProviderByPrefixAndCapability(String, Class) when trying to determine if a provider implements a specific capability

Parameters:

prefix - the string which represents a type of entity handled by an entity provider

Returns:

a list of the capabilities classes implemented by the entity provider defining this prefix

getRegisteredEntityCapabilities

Map<String,List<Class<? extends EntityProvider>>> getRegisteredEntityCapabilities()

Get all registered prefixes and their capabilities, WARNING: This is very inefficient so you should normally use getProviderByPrefixAndCapability(String, Class) when trying to determine if a provider implements a specific capability

Returns:

a map of prefix -> List(capabilities)

registerEntityProvider

void registerEntityProvider(EntityProvider entityProvider)

Registers an entity provider with the manager, this allows registration to happen programatically but the preferred method is to use the AutoRegisterEntityProvider instead (see the EntityProvider interface), replaces an existing entity provider which uses the same prefix and handles the same capabilities if one is already registered, does not affect other providers which handle the same prefix but handle other capabilities
NOTE: This allows developers to register providers from all over the code base without requiring all capabilities to live in the same project (i.e. allows for a large reduction in dependencies and conflicts)

Parameters:

entityProvider - an entity provider to register with the main entity provider manager

unregisterEntityProvider

void unregisterEntityProvider(EntityProvider entityProvider)

Unregisters an entity provider with the manager, this will remove a registered entity broker from the manager registration, if the entity provider supplied is not registered then no error is thrown

Parameters:

entityProvider - an entity provider to unregister with the main entity provider manager

unregisterCapability

void unregisterCapability(String prefix,
                          Class<? extends EntityProvider> capability)

Unregisters an entity provider with the manager based on a prefix and capability, this will remove a registered entity broker from the manager registration, if the prefix and capability are not registered then no error is thrown
NOTE: Attempting to unregister the base EntityProvider will cause an exception, if you want to completely unregister a type of entity you must use the unregisterEntityProviderByPrefix(String)

Parameters:

prefix - the string which represents a type of entity handled by an entity provider

capability - any entity provider capability class (these classes extend EntityProvider or CoreEntityProvider or another capability)

unregisterEntityProviderByPrefix

void unregisterEntityProviderByPrefix(String prefix)

Unregisters an entity provider with the manager based on the entity prefix it handles, this will remove all registered entity providers from the manager registration by the prefix, if the entity provider prefix provided is not registered then no error is thrown
This effectively purges the entire set of entity providers for a prefix

Parameters:

prefix - the string which represents a type of entity handled by entity providers

registerListener

<T extends EntityProvider> void registerListener(EntityProviderListener<T> listener,
                                                 boolean includeExisting)

Registers a listener which is called whenever entity providers are registered depending on the filters in the EntityProviderListener
This is particularly useful for capabilities which should/must be executed one time only and should not be called over and over OR will not do anything until they are triggered

Parameters:

notifier - the entity provider listener to register

includeExisting - if true then the listener will be called for existing registered providers, otherwise it will only be called for newly registered providers

Throws:

IllegalArgumentException - if the params are null

unregisterListener

<T extends EntityProvider> void unregisterListener(EntityProviderListener<T> listener)

Unregisters the listener if it is registered or does nothing

Parameters:

notifier - the entity provider listener to unregister

Throws:

IllegalArgumentException - if the params are null

getRequestStorage

RequestStorageWrite getRequestStorage()

Allows access to the current RequestStorage service

Returns:

the current RequestStorageWrite service

getRequestGetter

RequestGetterWrite getRequestGetter()

Allows access to the current RequestGetter service

Returns:

the current RequestGetter service

getEntityProperties

EntityPropertiesService getEntityProperties()

Allows access to the current EntityPropertiesService service

Returns:

the current EntityPropertiesService service

getEntityProviderMethodStore

EntityProviderMethodStore getEntityProviderMethodStore()

Allows access to the current EntityProviderMethodStore service

Returns:

the current EntityProviderMethodStore service