/*******************************************************************************
* 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;
}
}
}