org.apache.myfaces.trinidad.context.DialogService Maven / Gradle / Ivy
Show all versions of trinidad-api Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.myfaces.trinidad.context;
import java.util.Map;
import javax.faces.component.UIComponent;
import javax.faces.component.UIViewRoot;
import javax.faces.context.FacesContext;
import org.apache.myfaces.trinidad.event.ReturnEvent;
/**
* The DialogService API defines a number of
* APIs that are needed to implement Apache Trinidad dialogs,
* but will only rarely be called by page authors.
* They are instead intended for developers of controller
* frameworks and component developers.
*/
abstract public class DialogService
{
/**
* Configuration parameter for setting the prefix used in
* dialog navigation.
*/
public static final String DIALOG_NAVIGATION_PREFIX_PARAM_NAME =
"org.apache.myfaces.trinidad.DIALOG_NAVIGATION_PREFIX";
/**
* Configuration parameter for setting the prefix used in
* dialog navigation. This can either be set as a WEB-INF/web.xml
* or programatically set as a ServletContext attribute.
*/
public static final String DISABLE_DIALOG_OUTCOMES_PARAM_NAME =
"org.apache.myfaces.trinidad.DISABLE_DIALOG_OUTCOMES";
/**
* Create an DialogService.
*/
protected DialogService()
{
}
/**
* Push a UIViewRoot onto a stack in preparation
* for navigating to a subflow.
*/
public abstract void pushView(UIViewRoot viewRoot);
/**
* Pop a UIViewRoot from a stack. If navigateToPopped is true,
* this method may result in calls to
* FacesContext.renderResponse() or even
* FacesContext.responseComplete().
*
* @param navigateToPopped If true, navigate to the view popped
* of the stack with FacesContext.setViewRoot().
* If false, simply drop the view.
*/
public abstract void popView(boolean navigateToPopped);
/**
* Returns the UIViewRoot that is topmost on the stack,
* of pushed view, without popping it.
*/
public abstract UIViewRoot peekView();
/**
* Creates a {@link org.apache.myfaces.trinidad.event.ReturnEvent} for
* a component. This method will generally be called from
* a Renderer's or UIComponent's decode() method if there is
* any possibility that it launched a dialog on a prior request.
* There is no requirement that the component directly supports
* {@link org.apache.myfaces.trinidad.event.ReturnListener}; decode()
* can simply use the return value and discard the event.
*
* This method will return null in the case where no dialog
* had been launched with this component as the source. If
* it returns a non-null event, the component or renderer should
* not process the request any further in decode(), but simply
* process the ReturnEvent, either by using its return value
* or queueing it for delivery.
*
* @param source the component that may have launched a dialog
* @return a ReturnEvent containing the
* {@link RequestContext#returnFromDialog return value} from the
* dialog.
*/
public abstract ReturnEvent getReturnEvent(UIComponent source);
/**
* Returns the value last set by {@link #setCurrentLaunchSource}.
* =-=AEW Make this abstract?
*/
public UIComponent getCurrentLaunchSource()
{
return _currentLaunchSource;
}
/**
* A component that is
* delivering an ActionEvent to the default ActionListener
* should call this method to allow a NavigationHandler to
* properly launch a dialog, and should reset the
* value to null afterwards.
* =-=AEW Make this abstract?
*/
public void setCurrentLaunchSource(UIComponent component)
{
_currentLaunchSource = component;
}
/**
* Launches a dialog without pushing a process scope.
* This method should only be used by controller framework
* code; all others should use
* {@link RequestContext#launchDialog RequestContext.launchDialog()}.
* The process scope must be {@link PageFlowScopeProvider#pushPageFlowScope pushed}
* before calling this method.
*/
public abstract void launchDialog(
UIViewRoot dialogRoot,
Map dialogParameters,
UIComponent source,
boolean useWindow,
Map windowProperties);
/**
* Returns from a dialog without popping a process scope.
* This method should only be used by controller framework
* code; all others should use
* {@link RequestContext#returnFromDialog RequestContext.returnFromDialog()}.
* The process scope must be {@link PageFlowScopeProvider#popPageFlowScope popped}
* after calling this method.
*
* @return true if pages accessing that dialog are necessarily permanently
* inaccessible. For example, a dialog displayed in a popup
* window is inacessible once the window has closed, but a dialog
* displayed within the same window might be reached by the back button.
*/
public abstract boolean returnFromDialog(Object returnValue,
Map returnParameters);
/**
* Queues a LaunchEvent that will result in a dialog being started, using
* {@link #getCurrentLaunchSource current launch source} as the source
* for launching the dialogRoot parameter.
* The process scope must be {@link PageFlowScopeProvider#pushPageFlowScope pushed}
* before calling this method. If {@link #getCurrentLaunchSource}
* returns null, a basic dialog will be started without
* using a window or passing any additional parameters. Developers
* should not call
* {@link javax.faces.context.FacesContext#setViewRoot
* FacesContext.setViewRoot()} when using this method.
*/
public abstract void queueLaunchEvent(UIViewRoot dialogRoot);
/**
* Queues a ReturnEvent, using
* {@link #getCurrentLaunchSource current launch source} as the source
* for launching the dialogRoot parameter. This method should
* be used by a NavigationHandler that can identify
* a return value from a dialog without actually launching the dialog.
*/
public abstract void queueReturnEvent(
Object returnValue,
Map returnParams);
/**
* Returns the prefix that, when used for navigational outcomes,
* will trigger the dialog framework.
*/
public String getDialogNavigationPrefix()
{
if (_dialogPrefix == null)
{
FacesContext context = FacesContext.getCurrentInstance();
_dialogPrefix = context.getExternalContext().getInitParameter(
DIALOG_NAVIGATION_PREFIX_PARAM_NAME);
if(_dialogPrefix == null)
{
_dialogPrefix = _DEFAULT_DIALOG_NAVIGATION_PREFIX;
}
}
return _dialogPrefix;
}
private UIComponent _currentLaunchSource;
private static String _dialogPrefix;
private static final String _DEFAULT_DIALOG_NAVIGATION_PREFIX = "dialog:";
}