/* Copyright (c) 2001, 2003 Oracle Corporation. All rights reserved. */
package oracle.portal.provider.v2;

/**
 * In its simplest terms, a <code>ProviderLoader</code> can be thought of as a
 * 'factory' for {@link ProviderInstance} objects: the objects that actually
 * carry out the functionality of a single registered provider
 * instance. However, given that a {@link ProviderInstance} is generally driven
 * from meta-data in a {@link ProviderDefinition}, which should be shared by
 * other <code>ProviderInstance</code>s of the same 'type', it is also the
 * responsibility of a <code>ProviderLoader</code> to initialize and cache an
 * up-to-date version of the <code>ProviderDefinition</code> and associate this
 * with the instances it creates.<p>
 *
 * Generally, a <code>ProviderLoader</code> will initialize a
 * <code>ProviderDefinition</code> from meta data held in a persistent store,
 * e.g. XML file or database. To allow changes to the persisted data to be
 * picked up while the provider is in operation, a <code>ProviderLoader</code>
 * is allowed to replace its cached <code>ProviderDefinition</code> with a new
 * version under certain circumstances. A flag is provided to suppress this
 * behaviour, however, so that the ProviderInstance and the Portal it is
 * registered on do not get 'out of sync' with respect to their picture of the
 * provider.<p>
 *
 * Because this mechanism is kept external to the
 * <code>ProviderDefinition</code> itself, it gives scope for the same provider
 * to be backed by a different storage medium without having to change its
 * implementation.
 */
public abstract class ProviderLoader
{
    /**
     * Gets a <code>ProviderInstance</code> object with the specified
     * providerId without permitting reload of the cached
     * <code>ProviderDefinition</code>.<p>
     *
     * This is provided as a shorthand for calling {@link
     * #getProviderInstance(String,boolean) getProviderInstance(providerId,
     * false)}.
     *
     * @param providerId the providerId of the <code>ProviderInstance</code>
     * that is being requested
     * @return the <code>ProviderInstance</code> object with the specified
     * providerId
     */
    public ProviderInstance getProviderInstance(String providerId)
        throws ProviderException
    {
        return getProviderInstance(providerId, false);
    }

    /**
     * Gets a <code>ProviderInstance</code> object with the specified
     * providerId, optionally permitting reload of the cached
     * <code>ProviderDefinition</code>.<p>
     *
     * The first time this method is called, a new
     * <code>ProviderDefinition</code> should be loaded from its meta data and
     * cached internally. This same cached <code>ProviderDefinition</code> must
     * be associated with all <code>ProviderInstance</code>s returned by this
     * method, unless it is called again when the <code>refresh</code> flag is
     * <code>true</code>. In this case, the method is allowed to replace the
     * cached <code>ProviderDefinition</code> with a new version, e.g. if its
     * meta data has been changed.
     *
     * @param providerId the providerId of the <code>ProviderInstance</code>
     * that is being requested
     * @param refresh flag indicating whether the
     * <code>ProviderDefinition</code> should be reloaded or not. A value of
     * <code>true</code> will cause a refresh.
     *
     * @return the <code>ProviderInstance</code> object with the specified providerId
     */
    public abstract ProviderInstance getProviderInstance(String providerId, boolean refresh)
        throws ProviderException;


    /**
     * Gets the context object that describes the deployment environment of the
     * provider type handled by this <code>ProviderLoader</code>.
     * @return context object describing the deployment environment of the
     * provider.
     */
    public abstract ProviderContext getProviderContext();
}
