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

package oracle.portal.provider.v1;

import java.security.*;
import java.util.*;
import java.text.*;
import oracle.webdb.utils.SimpleStringBuffer;

/**
 * Represents the Portal user.  Additionally provides the methods for
 * establishing and reaquiring the user's session. <p>
 * Some Providers have a distinct notion users. Providers are able to configure
 * the Portal (using a login server) to map between the Portal user and the
 * application (Provider) user.   The ProviderUser interface provides access to
 * both the Portal user information and this mapped information.<p>
 * The portal runs in a default public mode.  This occurs when a user accesses
 * the portal without logging in.  This is represented by a special ProviderUser
 * whose portal user name is defined by the String ProviderUser.PUBLIC.  The
 * convenience method isPublicUser() is provided to simplify this check.
 *
 */
public abstract class ProviderUser
{

    /**
     *  Constant (string) representing the public user.  That is the "user"
     *  when a request is made and the person hasn't logged in.
     */
    public static final String PUBLIC = "portal_public";
    public static final String PORTAL_PUBLIC = "portal_public";
    public static final String PUBLIC_USERNAME = "public";

    // static constants representing the various authentication levels
    // of authentication.

    // authentication status of the user has not been determined
    public static final int AUTH_NOT_DETERMINED = -99;

    // JPDK is running against a version of portal that does not support
    // authentication level
    public static final int AUTH_LEVEL_NOT_SUPPORTED = -1;

    // user has not been authenticated to the portal in any way
    // ie user has not logged on in the current session and does not
    // have a persistent cookie indicating they were authenticated by
    // the portal in a previous session
    public static final int NOT_AUTHENTICATED = 0;

    // user is weakly authenticated as a PUBLIC portal user
    // based on persistent cookie
    public static final int PUBLIC_WEAK_AUTH = 2;

    // user weakly authenticated as a portal user
    // (any user other than PUBLIC) based on a persistent cookie.
    public static final int USER_WEAK_AUTH = 5;

    // user has logged into the portal using the user id PUBLIC,
    // and been authenticated by the login server within the current session
    public static final int PUBLIC_STRONG_AUTH = 7;

    // user has logged into the portal using a user id other than PUBLIC,
    // and been authenticated by the login server within the current session
    public static final int USER_STRONG_AUTH = 10;


    /**
     *  @return the portal user.
     */
    public abstract Principal getPrincipal();

    /**
     * @return the mapped application user.  <b>null</b> is there is no mapped user.
     *
     */
    public abstract Principal getMappedPrincipal();

    /**
     *  @return the portal username. Convenience method for getPrincipal().getName()
     */
    public abstract String getName();

    /**
     *  @return the subscriber id. Convenience method for getPrincipal().getSubscriberId()
     */
    public abstract String getSubscriberId();

    /**
     *  @return the company name. Convenience method for getPrincipal().getCompanyName()
     */

    public abstract String getCompanyName();

    /**
     *  @return the mapped application username.
     *  Convenience method for getMappedPrincipal().getName()
     */
    public abstract String getMappedName();

   /**
     *  @return the qulaified username, ie username appended with company name
     *  separator is "@@"
     */
    public abstract String getQualifiedName();

    /**
     *  @return the time when this user logged into the Portal
     */
    public abstract Calendar getLoginTime();

    /**
     *  @return the user's location.  Value is allowed to be <code>null</code>.
     *  This means the information is not available.
     */
    public abstract UserLocation getLocation();

    /**
     *  @return the Portal session ID for this user.  Portlet developers can use
     *  this ID to map to their in memory "session" state vs. using a cookie based
     *  mechanism.  The benefit is performance.  If the provider doesn't use cookies
     *  the portal can communicate more efficiently with it.
     */
    public abstract String getPortalSessionId();

    /**
    * @return the authentication level for the user
    */
    public abstract int getAuthenticationLevel();

    /**
    * @return true if the user has logged onto the portal in the current session.
    *  A user who is weakly authentication has not logged on to the portal in the
    *  current session so this method will return false.
    */
    public abstract boolean isLoggedOn();

    /**
    * @return true if the current user is at least weakly authenticated
    */
    public abstract boolean isWeaklyAuthenticated();

    /**
     *  Tests whether we are running in public mode.  ie the user has not
     *  logged in and is not weakly authenticated based on a prior login
     *  @return true if the user is accessing the portal in public mode.
     */
    public abstract boolean isPublicUser();

    /**
     *  Used to create and/or reacquire the user session.  If running as a HttpProvider
     *  (servlet) and sessions are maintained via cookies then the sessions must only
     *  be created in Provider.initSession().  Note: this method can throw an
     *  IllegalStateException.  This occurs if the user object has become stale.
     *  I.e. no longer contains the state that it needs to acquire/create the
     *  session.  As all Provider/Portlet APIs give you access to the User object
     *  per request you should not (need to) retain the user object via reference
     *  in cross-request object (like the session itself).  This only leads to
     *  possibilities of memory leaks.
     *  @param create if true then a session is created for the user if it
     *  doesn't currently exist.
     *  @return the session object for this user. <b>null</b> if create is
     *  false and the session doesn't already exist.
     */
    public abstract ProviderSession getSession(boolean create) throws IllegalStateException;

    /**
     *  Used to create and/or reacquire the user session.  Always creates a session
     *  if it doesn't currently exist. The same as calling
     *  getSession(true). If running as a HttpProvider
     *  (servlet) and sessions are maintained via cookies then the sessions must only
     *  be created in Provider.initSession(). Note: this method can throw an
     *  IllegalStateException.  This occurs if the user object has become stale.
     *  I.e. no longer contains the state that it needs to acquire/create the
     *  session.  As all Provider/Portlet APIs give you access to the User object
     *  per request you should not (need to) retain the user object via reference
     *  in cross-request object (like the session itself).  This only leads to
     *  possibilities of memory leaks.
     *  @return the session object for this user.
     */
    public abstract ProviderSession getSession() throws IllegalStateException;

}

