/*
* #%L
* Alfresco Repository
* %%
* Copyright (C) 2005 - 2016 Alfresco Software Limited
* %%
* This file is part of the Alfresco software.
* If the software was purchased under a paid Alfresco license, the terms of
* the paid license agreement will prevail. Otherwise, the software is
* provided under the following open source license terms:
*
* Alfresco is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* Alfresco is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with Alfresco. If not, see .
* #L%
*/
package org.alfresco.traitextender;
/**
* Trait-extender central extension registry and life cycle handler.
* Implementors must handle:
*
* -
* {@link ExtensionBundle} life cycle operations that start and stop bundles
* of extension points implementations at runtime.
* See also: {@link Extender#start(ExtensionBundle)} ,
* {@link Extender#stop(ExtensionBundle)} and {@link Extender#stopAll()} ).
* - The management of the extension point factory registry. At runtime
* extension point factories can be registered or unregistered. The registered
* factories will later be used for creating extensions of extensible-traits
* (see {@link Extender#getExtension(Extensible, ExtensionPoint))}.
* See also:{@link #register(ExtensionPoint, ExtensionFactory)} and
* {@link Extender#unregister(ExtensionPoint)}
* - The creation of extension for a given extensible trait.
* See: {@link Extender#getExtension(Extensible, ExtensionPoint)}
*
*
* @author Bogdan Horje
*/
public abstract class Extender
{
private static Extender instance;
/**
* @return singleton {@link ExtenderImpl} instance
*/
public static synchronized Extender getInstance()
{
if (instance == null)
{
instance = new ExtenderImpl();
}
return instance;
}
/**
* Start life-cycle phase trigger method.
* Upon successful execution the bundle will have all its extension points
* registered using {@link #register(ExtensionPoint, ExtensionFactory)} and
* ready to be.
*
* @param bundle to be started
*/
public abstract void start(ExtensionBundle bundle);
/**
* Start life-cycle phase trigger method.
* Upon successful execution the bundle will have all its extension points
* unregistered using {@link #unregister(ExtensionPoint)}.
*
* @param bundle to be stopped
*/
public abstract void stop(ExtensionBundle bundle);
/**
* Stops all previously registered {@link ExtensionBundle}s.
*/
public abstract void stopAll();
/**
* Creates and returns a unique per {@link ExtensibleTrait} object or
* null
if no extension-point factory is registered for the
* given {@link ExtensionPoint}.
* Given that {@link Extensible#getTrait(Class)} is used to obtain the
* {@link ExtendedTrait} that the returned extension is uniquely associated
* with, the uniqueness and garbage collection of the returned extension is
* dependent on how the given {@link Extensible} handles its
* {@link ExtendedTrait}s.
*
* @param anExtensible
* @param point
* @return a unique per {@link ExtensibleTrait} extension object or
* null
if no extension-point factory is registered for
* the given {@link ExtensionPoint}
*/
public abstract E getExtension(Extensible anExtensible, ExtensionPoint point);
/**
* Registers an extension-point to factory association to be used in
* extension creation. The presence of an association for a given extension
* point guarantees that, when requested, a unique extension object per
* {@link ExtensibleTrait} extension is returned by
* {@link #getExtension(Extensible, ExtensionPoint)}.
*
* @param point the extension point to be associated with the given
* extension factory during extension retrieval using
* {@link Extender#getExtension(Extensible, ExtensionPoint)}
* @param factory
*/
public abstract void register(ExtensionPoint, ?> point, ExtensionFactory> factory);
/**
* Unregisters an extension-point to factory association of the given
* extension point. The absence of an association for a given extension
* point guarantees that, when requested, a null is returned by
* {@link #getExtension(Extensible, ExtensionPoint)}.
* Unregistering extension points does not force the garbage collection of
* the already created extensions.
*
* @param point
*/
public abstract void unregister(ExtensionPoint, ?> point);
}