org.sakaiproject.entitybroker.entityprovider.EntityProviderManager Maven / Gradle / Ivy
The newest version!
/**
* $Id$
* $URL$
* AutoRegister.java - entity-broker - 31 May 2007 7:01:11 PM - azeckoski
**************************************************************************
* Copyright (c) 2007, 2008, 2009 The Sakai Foundation
*
* Licensed under the Educational Community License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.opensource.org/licenses/ECL-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
**/
package org.sakaiproject.entitybroker.entityprovider;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.sakaiproject.entitybroker.entityprovider.capabilities.AutoRegisterEntityProvider;
import org.sakaiproject.entitybroker.entityprovider.extension.EntityProviderListener;
import org.sakaiproject.entitybroker.entityprovider.extension.RequestGetterWrite;
import org.sakaiproject.entitybroker.entityprovider.extension.RequestStorageWrite;
import org.sakaiproject.entitybroker.providers.EntityPropertiesService;
/**
* Handles all internal work of managing and working with the entity providers
* Registration of entity brokers happens via spring, see the {@link EntityProvider} interface for
* details
*
* @author Aaron Zeckoski ([email protected])
* @author Antranig Basman ([email protected])
*/
public interface EntityProviderManager {
/**
* Retrieve a complete list of all currently registered {@link EntityProvider}s
*
* @return all currently registered entity providers
*/
public Set getRegisteredPrefixes();
/**
* Get the entity provider which handles the entity defined by an entity reference, this is a
* convenience method for {@link #getProviderByPrefix(String)}
NOTE: this returns
* the {@link CoreEntityProvider} that handles the exists check (it may handle many other things
* as well) or returns null
*
* @param reference
* a globally unique reference to an entity
* @return the {@link EntityProvider} which handles this entity or null if none exists, fails if
* the reference is invalid
* @deprecated this method is no longer functional or supported
*/
public EntityProvider getProviderByReference(String reference);
/**
* Get the entity provider by the prefix which uniquely defines all entities of a type,
* NOTE: this returns the {@link CoreEntityProvider} that handles the exists check (it
* may handle many other things as well), the basic {@link EntityProvider} if there is no
* {@link CoreEntityProvider}, OR null if neither exists
*
* @param prefix the string which represents a type of entity handled by an entity provider
* @return the {@link EntityProvider} which handles this entity or null if none exists (only if
* prefix is not used)
*/
public EntityProvider getProviderByPrefix(String prefix);
/**
* 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)
*
* @param a class which extends {@link EntityProvider}
* @param prefix
* the string which represents a type of entity handled by an entity provider
* @param capability
* any entity provider capability class (these classes extend {@link EntityProvider} or
* {@link CoreEntityProvider} or another capability)
* @return the {@link EntityProvider} which handles this capability for this prefix or null if
* none exists or the prefix is not used
*/
public T getProviderByPrefixAndCapability(String prefix, Class 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
*
* @param a class which extends {@link EntityProvider}
* @param capability
* any entity provider capability class (these classes extend {@link EntityProvider} or
* {@link CoreEntityProvider} or another capability)
* @return the list of providers which implement the given capability, may be an empty list
*/
public List getProvidersByCapability(Class capability);
/**
* Gets the prefixes which support a specific capability
*
* @param a class which extends {@link EntityProvider}
* @param capability
* any entity provider capability class (these classes extend {@link EntityProvider} or
* {@link CoreEntityProvider} or another capability)
* @return the list of entity prefixes which support this capability, may be an empty list
*/
public List getPrefixesByCapability(Class capability);
/**
* Get all the capabilities for a given entity prefix,
* WARNING: This is very inefficient so you should normally use {@link #getProviderByPrefixAndCapability(String, Class)}
* when trying to determine if a provider implements a specific capability
*
* @param prefix
* the string which represents a type of entity handled by an entity provider
* @return a list of the capabilities classes implemented by the entity provider defining this prefix
*/
public List> getPrefixCapabilities(String prefix);
/**
* Get all registered prefixes and their capabilities,
* WARNING: This is very inefficient so you should normally use {@link #getProviderByPrefixAndCapability(String, Class)}
* when trying to determine if a provider implements a specific capability
*
* @return a map of prefix -> List(capabilities)
*/
public Map>> getRegisteredEntityCapabilities();
/**
* Registers an entity provider with the manager, this allows registration to happen
* programatically but the preferred method is to use the {@link AutoRegisterEntityProvider}
* instead (see the {@link 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)
*
* @param entityProvider
* an entity provider to register with the main entity provider manager
*/
public void registerEntityProvider(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
*
* @param entityProvider
* an entity provider to unregister with the main entity provider manager
*/
public void unregisterEntityProvider(EntityProvider entityProvider);
/**
* 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 {@link EntityProvider} will cause an exception, if you want to completely unregister a
* type of entity you must use the {@link #unregisterEntityProviderByPrefix(String)}
*
* @param prefix
* the string which represents a type of entity handled by an entity provider
* @param capability
* any entity provider capability class (these classes extend {@link EntityProvider} or
* {@link CoreEntityProvider} or another capability)
*/
public void unregisterCapability(String prefix, Class capability);
/**
* 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
*
* @param prefix
* the string which represents a type of entity handled by entity providers
*/
public void unregisterEntityProviderByPrefix(String prefix);
// LISTENER
/**
* Registers a listener which is called whenever entity providers are registered depending on the
* filters in the {@link 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
*
* @param notifier the entity provider listener to register
* @param 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
*/
public void registerListener(EntityProviderListener listener, boolean includeExisting);
/**
* Unregisters the listener if it is registered or does nothing
*
* @param notifier the entity provider listener to unregister
* @throws IllegalArgumentException if the params are null
*/
public void unregisterListener(EntityProviderListener listener);
/**
* Allows access to the current RequestStorage service
* @return the current RequestStorageWrite service
*/
public RequestStorageWrite getRequestStorage();
/**
* Allows access to the current RequestGetter service
* @return the current RequestGetter service
*/
public RequestGetterWrite getRequestGetter();
/**
* Allows access to the current EntityPropertiesService service
* @return the current EntityPropertiesService service
*/
public EntityPropertiesService getEntityProperties();
/**
* Allows access to the current EntityProviderMethodStore service
* @return the current EntityProviderMethodStore service
*/
public EntityProviderMethodStore getEntityProviderMethodStore();
}