/*******************************************************************************
 * Copyright (c) 2001, 2008 Oracle Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors:
 *     Oracle Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jst.jsf.designtime.internal.view;

import org.eclipse.core.resources.IFile;
import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IPath;
import org.eclipse.jst.jsf.common.internal.resource.ImmutableLifecycleListener;
import org.eclipse.jst.jsf.designtime.context.DTFacesContext;

/**
 * <p>
 * Defines the basic interface for all design time view handlers that parallel
 * custom runtime view handlers (extenders of ViewHandler).
 * </p>
 * 
 * @author cbateman
 * 
 */
public interface IDTViewHandler
{
    /**
     * <p>
     * Creates and returns the view root. This method <i>may</i> optionally
     * intialize the view root with any data that need only be done once per
     * instance. Generally, this will include providing the root access to
     * itself or its IViewDefnAdapterFactory so that it can refresh itself.
     * </p>
     * 
     * @param facesContext
     * @param viewId
     * @return a designtime view root instance of viewId under the given faces
     *         context
     * @throws ViewHandlerException
     */
    DTUIViewRoot createView(DTFacesContext facesContext, String viewId)
            throws ViewHandlerException;

    /**
     * Calculate the locale for the current view context. The return string must
     * conform to the standard format proscribed by java.util.Locale.
     * 
     * @param context
     * @return the locale string for the view definition referred to by context
     * @throws ViewHandlerException
     */
    String calculateLocale(DTFacesContext context) throws ViewHandlerException;

    /**
     * Given that resource is the view definition source and requestPath is the
     * current servlet uri for a request relative to the web content root, map
     * it to the actual request uri that would be required at runtime to invoke
     * the view definition in resource. DTFacesContext will contain an external
     * context that may be used to derive servlet mapping configuration.
     * 
     * @param context
     * @param resource
     * @param requestPath
     * @return the IPath representing the newly mapped request path
     * @throws ViewHandlerException
     */
    IPath getActionURL(DTFacesContext context, IResource resource,
            IPath requestPath) throws ViewHandlerException;

    /**
     * TODO: if we already have context, must we already know what the source
     * is?
     * 
     * The IResource need not exist.
     * 
     * @param context
     * @param viewId
     * @return the resource containing the view definition for viewId.
     * @throws ViewHandlerException
     */
    IResource getActionDefinition(DTFacesContext context, String viewId)
            throws ViewHandlerException;

    /**
     * Given that a request is made for uri from within the view named by
     * relativeToViewId at runtime, return the path to the resource containing
     * that view definition. The path need not point to a resource that
     * currently exists.
     * 
     * @param context
     * @param relativeToViewId
     * @param uri
     * @return the path to the resource named by uri relative to the view named
     *         by relativeToViewId
     * @throws ViewHandlerException
     */
    IPath getRelativeActionPath(DTFacesContext context,
            String relativeToViewId, String uri) throws ViewHandlerException;

    /**
     * Translate a workspace resource to the view id it will have at runtime.
     * 
     * @param context
     * @param res
     * @return the view id for res or null if there is no meaningful value
     */
    String getViewId(DTFacesContext context, IResource res);

    /**
     * @param context
     * @return a view definition adapter
     * @throws ViewHandlerException
     */
    IViewDefnAdapterFactory getViewMetadataAdapterFactory(DTFacesContext context)
            throws ViewHandlerException;

    /**
     * @param file
     * @return true if the contents of the file is of a format that this view
     *         handler supports. Generally, this is decided by a combination of
     *         content type and, in the case of XML formats, schema.
     */
    boolean supportsViewDefinition(final IFile file);

    /**
     * Releases the handler's in-memory image.
     */
    void dispose();

    /**
     * Called by design time app manager to set a global resource listener
     * for the view handler to use.  View handlers should generally use this
     * listener to reduce the overhead of extra resouce change listeners.
     * 
     * @param listener
     */
    void setLifecycleListener(final ImmutableLifecycleListener listener);

    /**
     * General exception class for problems that a custom view handler wants to
     * propagate to the framework in a well-defined way.
     * 
     */
    public static final class ViewHandlerException extends Exception
    {
        private final Cause _causeCode;

        /**
         * Enumerates the known failure causes
         * 
         */
        public enum Cause
        {
            /**
             * thrown from getELExpression when the context passed does not
             * refer to a parsable EL expression in the view definition
             */
            EL_NOT_FOUND,
            /**
             * thrown from getELExpression when an exception occurs during EL
             * parsing. The ViewHandlerException should wrap the causing
             * exception in this cause
             */
            EL_EXCEPTION_CAUGHT_WHILE_PARSING,
            /**
             * an undefined exception cause indicating something not foreseen by
             * the framework.
             */
            UNDEFINED,

            /**
             * indicates that a bad or null version stamp was encountered. The
             * wrapped exception may provide tracing information to the cause.
             */
            BAD_VERSION_STAMP,

            /**
             * indicates that a bad or null staleness advisor was encountered.
             * The wrapped exception may provide tracing information to the
             * cause.
             */
            BAD_STALENESS_ADVISOR, 
            
            /**
             * a general failure by the view creation to create a new view root.
             */
            UNABLE_TO_CREATE_VIEW
        }

        /**
         * 
         */
        private static final long serialVersionUID = 2109525340402345111L;

        /**
         * Construct an exception with an undefined cause
         */
        public ViewHandlerException()
        {
            this(Cause.UNDEFINED);
        }

        /**
         * @param cause
         */
        public ViewHandlerException(final Cause cause)
        {
            super();
            _causeCode = cause;
        }

        /**
         * @param message
         * @param caught
         * @param cause
         */
        public ViewHandlerException(final String message,
                final Throwable caught, final Cause cause)
        {
            super(message, caught);
            _causeCode = cause;
        }

        /**
         * @param message
         * @param cause
         */
        public ViewHandlerException(final String message, final Cause cause)
        {
            super(message);
            _causeCode = cause;
        }

        /**
         * @param caught
         * @param cause
         */
        public ViewHandlerException(final Throwable caught, final Cause cause)
        {
            super(caught);
            _causeCode = cause;
        }

        /**
         * @return the cause code
         */
        public final Cause getCauseCode()
        {
            return _causeCode;
        }
    }
}