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

package oracle.portal.provider.v2.cache.invalidation;

import oracle.portal.provider.v2.ProviderInstance;
import oracle.portal.provider.v2.PortletInstance;
import oracle.portal.provider.v2.PortletDefinition;
import oracle.portal.provider.v2.ProviderUser;
import oracle.portal.provider.v2.PortalRealm;
import oracle.portal.provider.v2.ProviderSubscription;
import oracle.portal.provider.v2.personalize.PortletReference;

import oracle.security.jazn.realm.Realm;
import oracle.security.jazn.realm.RealmUser;
import oracle.portal.log.LogManager;

import java.util.Locale;

// Servlet class
import javax.servlet.http.HttpServletRequest;
/**
 * Interface for objects representing an invalidation object. It is used to 
 * set up and execute an invalidation request. This is done by setting up an
 * <code>InvalidationContext</code> type object and then building up
 * the invalidation request by setting various cache keys.<p>
 * There are two sets of methods. The first allows requests to be set up from
 * within the context of a provider (using JPDK objects).
 * The second set enables external code to set up requests using object ids and
 * names.
 * NOTE: The set methods in this interface do not accept null values
 */
public abstract class InvalidationContext
{
    // The following set methods specify cache keys that are to be used in an
    // invalidation request, using Provider objects.

    /**
     * Use a <code>Provider</code> object to set up an invalidation request.
     *
     * @param pr the provider whose content will be invalidated
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setProvider(ProviderInstance pr)
        throws InvalidationException;

    /**
     * Use a <code>Portlet</code> object to set up an invalidation request. The
     * underlying implementation class should use <code>Provider</code> info as 
     * well as <code>Portlet</code> info in the invalidation request.
     *
     * @param pt portlet whose content will be invalidated
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setPortlet(PortletInstance pt)
        throws InvalidationException;

    /**
     * Use a <code>PortletInstance<code> as a key for an invalidation request.
     *
     * The default implementation is included so that implementation classes 
     * built against previous versions of the interface still work. 
     *
     * @param pInst the object from which invalidation keys will be generated.
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public void setPortletInstance(PortletInstance pInst)
        throws InvalidationException
    {
        String msg = "Method not supported";
        InvalidationException ie = new InvalidationException(msg);
        LogManager.throwing(msg, ie);
        throw ie;
    }

    /**
     * Invalidate content using a <code>PortletReference</code> object. This object
     * encapsulates the provider, portlet, portlet instance name, user name and 
     * language.
     *
     * @param pRef the portlet reference whose content will be invalidated
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setPortletReference(PortletReference pref)
        throws InvalidationException;

    /**
     * Use a provider user as a key for the invalidation request.
     *
     * @param pu the provider user object.
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setUser(RealmUser pu) throws InvalidationException;

    /**
     * Set the subscription id as an invalidation key
     *
     * @param ps the JPDK object containing the invalidation key
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setProviderSubscription(ProviderSubscription ps)
        throws InvalidationException;

    /**
     * Set the subscription id as an invalidation key
     *
     * @param id the invalidation key
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setProviderSubscription(String id) 
        throws InvalidationException;
    
    /**
     * Set the user's realm name as an invalidation key
     *
     * @param ps the JPDK object containing the invalidation key
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setPortalRealm(PortalRealm pr) 
        throws InvalidationException;

    /**
     * Set the user's realm name as an invalidation key
     *
     * @param name the realm name
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setPortalRealm(String name) 
        throws InvalidationException;

    /**
     * Set a provider id for this invalidation request. 
     *
     * @param id the id of the provider whose content will be invalidated
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setProvider(String id) 
        throws InvalidationException;

    /**
     * Set a portlet id for this invalidation request.
     *
     * @param id the id of the portlet whose content will be invalidated
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setPortlet(long id) throws InvalidationException;

    /**
     * Set the user name as a key for the invalidation request
     *
     * @param pu the provider user name
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setUsername(String user) throws InvalidationException;

    /**
     * Set a portlet instance as key for an invalidation request. This method 
     * sets an invalidation key based on the instance name alone.
     *
     * @param instanceName the name of the portlet instance whose content 
     * will be invalidated.
     *
     * @exception InvalidationException thrown if a null parameter is passed
     */
    public abstract void setPortletInstanceName(String instanceName)
        throws InvalidationException;

    /**
     * Set authentication level as an invalidation request key
     *
     * @param level the authentication level, e.g 1
     */
    public abstract void setAuthenticationLevel(int level);

    /**
     * Set locale as an invalidation key.
     *
     * The default implementation is included so that implementation classes 
     * built against previous versions of the interface still work. 
     *
     * @param locale the locale object to be used as an invalidation key 
     *
     * @exception InvalidationException thrown if null parameter is passed or
     *            the method is not defined in the implementation class             
     */
    public void setLocale(Locale locale) throws InvalidationException
    {
        String msg = "Method not supported";
        InvalidationException ie = new InvalidationException(msg);
        LogManager.throwing(msg, ie);
        throw ie;
    }
    
    /**
     * Clear all of the cache keys so that an object of this type can be used
     * to make repeated invalidation requests.
     */
    public abstract void clearAllKeys();
    
    /**
     * Execute the invalidation.
     *
     * @return the number of objects invalidated by the request.
     *
     * @exception InvalidationException throw if there is a problem during
     *            invalidation
     */
    public abstract int invalidate() throws InvalidationException;
    
    /**
     * Invalidates cached documents using an arbitrary host, port, 
     * folder prefix and regular expression suffix.
     *
     * <p>Use this method to invalidate an arbitrary URI that has been cached.
     *
     * <p>Use this method to invalidate an arbitrary URI that has been cached.
     *
     * <p>Example usages:
     * <ul>
     * <li>
     * <pre>
     * int numInvalidations = invalidationContext.invalidateURI(
     *     "myhost.us.oracle.com:7777", "/public/documents/jsp/", "info\\.jsp");
     * </pre>
     * </li>
     * <li>
     * <pre>
     * int numInvalidations = invalidationContext.invalidateURI(
     *     "myhost.us.oracle.com:7777", "/public/documents/jsp/", "info.*jsp");
     * </pre>
     * </li>
     * </ul>
     *
     * @param uriHost the host and port of the document(s) to be invalidated.
     *        Must have the format "hostname:port".
     * @param uriPrefix the folder that prefixes the document(s).
     *        Must have the format "/folder1/.../folderN/". 
     *        Note that there must be opening and closing '/' slashes.
     * @param uriExpression a <a href="http://www.cs.utah.edu/dept/old/texinfo/regex/regex_toc.html">
     *        regular expression </a> corresponding to the URL of the 
     *        document(s) to be invalidated underneath the uriPrefix
     * @return the number of cached entries invalidated
     * @exception InvalidationException if there is a problem during
     *            invalidation
     */
    public int invalidateURI(String uriHost, String uriPrefix,
        String uriExpression) throws InvalidationException
    {
        throw new InvalidationException("Method not supported.");
    }
}
