/*  Copyright (c) 2000 by Oracle Corporation. All Rights Reserved. */

package oracle.portal.provider.v1;


/**
 *  A Provider manages a set of portlets.  As such it is the conduit between the
 *  Portal Adapter and a given portlet.  I.e. calls are mapped to portlets
 *  their controllers by calling Provider APIs.  Thus the primary function
 *  of the Provider interface is to expose its portlets to a Portal.  As a manager
 *  it additionally takes on the role of "application" manager.  That is the
 *  Provider is used to expose function that is shared between the portlets it is
 *  managing.  In the JPDK shared function is (commonly) controlled via a session.
 *  The session is created and maintained by the Provider.
 */

public interface Provider {

    /**
     *  Initialize the provider.  Basically all this does is set the providerId.
     *  This can't be set at create time because of the need to use a null constructor.
     *
     *  @param  providerId  this providers ID.
     *  @param  logger  logging mechanism this provider should use.  If null the
     *  provider may implement a default logging facility (but is not required to do so).
     */
    public void init(long providerId, ProviderLog logger) throws ProviderException;

    /**
     *  Returns this provider's ID.
     */
    public long getProviderId();

    /**
     * Gets the default storage path used for meta data associated with this
     * provider, if any
     *
     * @return a physical storage path, or <code>null</code> if not applicable
     */
    public String getProviderRepositoryPath();

    /**
     *  Returns the subscriber for this portal.  In a subscription-based model
     *  a company may want/need to associate its own ID with a customer.  This ID
     *  could be used for billing purposes, for example.  When a Provider is
     *  registered in a Portal, the subscriber ID is entered by the administrator and
     *  passed to the Provider in the register method.  Once established, the Provider
     *  is expected to maintain the relationship between the ProviderId and the
     *  subscriberID (persistently).
     *
     *  @return the subscriber.  <b>null</b> if this Provider doesn't use/support
     *  subscription.
     */
    public ProviderSubscriber getSubscriber();

    /**
     *  Provider's version -- version of the PDK API it implements.
     */
    public int getVersion();

    /**
     *  Register this newly created provider.  Having your register method
     *  called means your Provider has just been installed/activated in
     *  a portal.  The Provider should do its per portal initialization here.<p>
     *  In some cases, such as when customers are billed on a subscription basis
     *  for using a particular provider, a Provider needs to distinguish the
     *  particular portal being registered.  This is supported by passing a
     *  <b>subscriberId</b> to the <b>register</b> method.  A subscriberID is
     *  controlled by the Provider owner.  A portal customer requests/receives a
     *  subscriber ID from the Provider owner when they "purchase" the service.
     *  This subscriberId is entered by the portal customer when the Provider is
     *  installed/registered.  The portal in turn sends this ID to the Provider
     *  software to complete the registration.  Providers that don't support this
     *  subscription model will receive a <b>null</b> subscriberID.<p>
     *  This mechanism is also used to enhance security.  Along with the subscriberId
     *  a Provider can supply an encryption key to the portal customer.  If provided,
     *  the portal encrypts all requests to the Provider using this key.  The request
     *  then sent to the Provider with the subscriberID encoded in the requests
     *  header.  The Provider uses the subscriberID to identify the proper key
     *  to use for decryption.<p>
     *  Recognizing that certain Providers would like the enhanced security that
     *  encrpyted messaging supports but don't want to deal with providing a
     *  non-programmatic mechanism for communicating the encryption key to the
     *  portal customer, the register() method can alternatively generate a subscriberID
     *  and encryption key that it returns to the registering portal for use with
     *  all subsequent requests.  Currently, this id/key pair must be communicated
     *  over an unsecure channel making this a less then bullet-proof mechanism.
     *  However, given that all subsequent messages occur in a secure manner, the
     *  level of security to the Provider is greatly enhanced.<p>
     *  Providers that don't dynamically generate and return an id/key pair
     *  should return <b>null</b>.
     *
     *  @param subscriberId Subscriber identifier the portal customer supplied when
     *  registering the Provider in the Portal UI.  If none was provided this value
     *  is <b>null</b>.
     *  @param PortalVersion the version of the portal registering this provider.
     *  In the typical Oracle form: 1.0.1.0.1.
     *  @return If this Provider dynamically generates an encryption key to be
     *  used to secure subsequent requests from this portal then a ProviderSubscriber,
     *  <b>null</b> otherwise.
     */
    public ProviderSubscriber register(String subscriberId, String portalVersion) throws ProviderException;

    /**
     *  Deregister this provider.  Indicates this Provider is no longer in use in
     *  the specified portal.  The specific portal is inferred from the providerId
     *  which Oracle Portal attempts to make unique across all portals.  Providers
     *  typically respond to this call by unsubscribing the customer and or deleting
     *  the entries in the portlet (personalization) repository that correspond to this
     *  provider/portal.
     */
    public void deregister() throws ProviderException;

    /**
     *  Called to initialize the Provider in a particular user session.  This
     *  may be called never, once per user session, or once per request depending
     *  on how the provider is configured in the portal.  If the Provider uses
     *  HTTP cookies or maintains state via a cookie-based HTTP session, it is
     *  imperative that (all) cookies be established during this call. <p>
     *  A session is established via the user object.  I.e. the user object
     *  contains the methods for creating and retrieving a session.<p>As this
     *  interface is designed for use in both servlet and non-serlvet environments
     *  servlet interfaces could not be used. initSession returns an array of
     *  cookie objects of the type expected in the particular framework the
     *  provider is executing in.  For HttpProviders this <i>is</i> servlets and
     *  hence the returned object array should contain object of type
     *  javax.servlet.http.Cookie.
     *
     *  @param user  Current portal user.
     *  @param externalApp External Applciation information (if it exists)
     *  @return Array of cookie objects.  <b>null</b> if this provider doesn't
     *  use cookies or relies on the (user) session to maintain its state.
     *  The type of these objects is specific
     *  to the environment in which this provider runs.  When running in the
     *  servlet environment (HttpProviders) these objects should be of type
     *  javax.servlet.http.Cookie.
     *  @exception ProviderException ProviderException is a generic exception
     *  for Providers
     *  @exception AuthenticationException AuthenticationException should be
     *  thrown if you have an external application that requires additional
     *  authentication and that authentication fails for some reason.
     */
    public Object[] initSession(ProviderUser user, ExternalPrincipal externalApp) 
           throws ProviderException;

    /**
     *  @deprecated  As of Portal 3.0.8 use initSession that receives the
     *  externalApp parameter.<p>
     *  Called to initialize the Provider in a particular user session.  This
     *  may be called never, once per user session, or once per request depending
     *  on how the provider is configured in the portal.  If the Provider uses
     *  HTTP cookies or maintains state via a cookie-based HTTP session, it is
     *  imperative that (all) cookies be established during this call. <p>
     *  A session is established via the user object.  I.e. the user object
     *  contains the methods for creating and retrieving a session.<p>As this
     *  interface is designed for use in both servlet and non-serlvet environments
     *  servlet interfaces could not be used. initSession returns an array of
     *  cookie objects of the type expected in the particular framework the
     *  provider is executing in.  For HttpProviders this <i>is</i> servlets and
     *  hence the returned object array should contain object of type
     *  javax.servlet.http.Cookie.
     *
     *  @param user  Current portal user.
     *  @return Array of cookie objects.  <b>null</b> if this provider doesn't
     *  use cookies or relies on the (user) session to maintain its state.
     *  The type of these objects is specific
     *  to the environment in which this provider runs.  When running in the
     *  servlet environment (HttpProviders) these objects should be of type
     *  javax.servlet.http.Cookie.
     *  @exception ProviderException ProviderException is a generic exception
     *  for Providers
     */
    public Object[] initSession(ProviderUser user) throws ProviderException;

    /**
     * Returns array of Portlets managed by this Provider. The array is constrained
     * to the specified range.  If <code>byUser</code> is true, then the array is further
     * constrained to only those Portlets that the passed user has priveleges to.
     *
     * @param start The starting element in the range being requested. This value is
     * 0 based.  I.e. a start of 0 indicates the first element in the set.
     * @param count The number of elements in the range.  The returned array
     * should contain a maximum of <code>count</code> elements.
     * @param byUser If <code>true</code> then the set should be restricted to those
     * portlets this user has access privileges to.
     * @param user The user on whose behalf this request is being made.  Used to
     * both validated that this user has the privileges to make this request, to
     * get access to session state if needed, and to restrict the response set if
     * <code>byUser</code> is true.
     * @return An array of Portlets constrained to the passed criteria.  The array's
     * length must equal the number of returned elements.  I.e. the caller can count
     * on array.length to describe the number of valid entries.  If no portlets
     * match the constaints then the call can return either <code>null</code> or a zero
     * length array.
     */
    public Portlet[] getPortlets(int start, int count, boolean byUser, ProviderUser user) throws ProviderException;

    /**
     *  Returns a Portlet by its Id.  Only return if user has access otherwise
     *  <code>null</code> is returned.
     *
     *  @param id  Portlet Id.
     *  @param user The user on whose behalf this request is being made.  Used to
     *  both validated that this user has the privileges to make this request, to
     *  get access to session state if needed, and most importantly to check if
     *  this user has access privileges to this portlet.
     *  @return the Portlet that maps from this id, <b>null</b> otherwise.
     *  If non-null, it signifies that this user has access privileges to this
     *  Portlet.
     */
    public Portlet getPortlet(long id, ProviderUser user) throws ProviderException;

    /**
     *
     * Writes the specified message to a provider log, which is usually
     * an event log. The message provides explanatory information about
     * an exception or error or an action the provider takes. The name
     * and type of the provider log file is specific to the provider engine.
     *
     *
     * @param msg 	a <code>String</code> specifying the explanatory
     *			message to be written to the log file
     *
     */

    public void log(String msg);

    /**
     * Writes the stack trace and an explanatory message
     * for a given <code>Throwable</code> exception
     * to the provider log file. The stack trace is
     * part of the <code>Throwable</code> object, and
     * the message is the one you specify in the <code>message</code>
     * parameter. The name and type of the provider log file is specific to
     * the provider engine, but it is usually an event log.
     *
     *
     * @param message 		a <code>String</code> that
     *				describes the error or exception
     *
     * @param throwable 	the <code>Throwable</code> error
     *				or exception
     *
     */

    public void log(String message, Throwable throwable);


}

