001/*
002 * (C) Copyright 2006-2007 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     Nuxeo - initial API and implementation
016 *
017 * $Id: URLPolicyService.java 28924 2008-01-10 14:04:05Z sfermigier $
018 */
019
020package org.nuxeo.ecm.platform.ui.web.rest.api;
021
022import javax.faces.context.FacesContext;
023import javax.servlet.ServletContext;
024import javax.servlet.http.HttpServletRequest;
025import javax.servlet.http.HttpServletResponse;
026
027import org.nuxeo.ecm.platform.ui.web.auth.NXAuthConstants;
028import org.nuxeo.ecm.platform.ui.web.rest.StaticNavigationHandler;
029import org.nuxeo.ecm.platform.ui.web.rest.descriptors.URLPatternDescriptor;
030import org.nuxeo.ecm.platform.url.api.DocumentView;
031import org.nuxeo.ecm.platform.url.api.DocumentViewCodecManager;
032
033/**
034 * Service used on the web layer to handle navigation using meaningful URLs.
035 * <p>
036 * It handles a document context description, and also performs JSF model related operations.
037 * <p>
038 * It holds pattern descriptors used to interact with the {@link DocumentViewCodecManager}.
039 *
040 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
041 */
042public interface URLPolicyService {
043
044    String POST_OUTCOME_REQUEST_KEY = "PostOutcome";
045
046    String DOCUMENT_VIEW_REQUEST_KEY = "DocumentView";
047
048    String DISABLE_ACTION_BINDING_KEY = "DisableActionBinding";
049
050    /**
051     * @deprecated: use {@link NXAuthConstants#DISABLE_REDIRECT_REQUEST_KEY} instead
052     */
053    @Deprecated
054    String DISABLE_REDIRECT_REQUEST_KEY = "nuxeo.disable.redirect.wrapper";
055
056    String FORCE_URL_ENCODING_REQUEST_KEY = "nuxeo.force.url.encoding";
057
058    /**
059     * Returns true if request is a GET request and filter preprocessing is turned on.
060     */
061    boolean isCandidateForDecoding(HttpServletRequest httpRequest);
062
063    /**
064     * Returns true if request is a POST request and filter redirection is turned on.
065     */
066    boolean isCandidateForEncoding(HttpServletRequest httpRequest);
067
068    /**
069     * Adds document view to the request for later retrieval.
070     *
071     * @param request the current request.
072     * @param docView to save
073     */
074    void setDocumentViewInRequest(HttpServletRequest request, DocumentView docView);
075
076    /**
077     * Builds the document view from request information.
078     * <p>
079     * Delegates call to a document view codec found thanks to the default URL pattern descriptor.
080     */
081    DocumentView getDocumentViewFromRequest(HttpServletRequest request);
082
083    /**
084     * Builds the document view from request information.
085     * <p>
086     * Delegates call to a document view codec found thanks given pattern name.
087     */
088    DocumentView getDocumentViewFromRequest(String pattern, HttpServletRequest request);
089
090    /**
091     * Returns a URL given a document view.
092     * <p>
093     * Delegates call to a document view codec found thanks to the default URL pattern descriptor.
094     */
095    String getUrlFromDocumentView(DocumentView docView, String baseUrl);
096
097    /**
098     * Returns a URL given a document view.
099     * <p>
100     * Delegates call to a document view codec found thanks given pattern name.
101     */
102    String getUrlFromDocumentView(String pattern, DocumentView docView, String baseUrl);
103
104    /**
105     * Extracts parameters from request attributes.
106     * <p>
107     * Apply them to the model using EL value bindings described on URL pattern descriptors.
108     * <p>
109     * We look for binding values to set on the request attribute and on the document view parameters.
110     */
111    void applyRequestParameters(FacesContext facesContext);
112
113    /**
114     * Appends parameters to request so that the model can be restored after request.
115     * <p>
116     * Extract them using EL value bindings described on URL pattern descriptors.
117     * <p>
118     * If the document view is not null, values are set on its parameters. If the document view is null, values are set
119     * on the request parameters.
120     */
121    void appendParametersToRequest(FacesContext facesContext);
122
123    /**
124     * Performs redirection action.
125     * <p>
126     * Extract it using an EL action binding described on URL pattern descriptors.
127     * <p>
128     * The action binding is called using given document view as parameter. If a sub URI is found, do nothing (may be an
129     * invalid resource URL).
130     */
131    String navigate(FacesContext context);
132
133    // registry of pattern descriptors
134
135    /**
136     * Returns the default pattern descriptor name
137     */
138    String getDefaultPatternName();
139
140    /**
141     * Returns true if the service holds a pattern descriptor with given name
142     *
143     * @since 5.5
144     */
145    boolean hasPattern(String name);
146
147    void addPatternDescriptor(URLPatternDescriptor pattern);
148
149    void removePatternDescriptor(URLPatternDescriptor pattern);
150
151    void clear();
152
153    /**
154     * Initializes the view id manager {@link StaticNavigationHandler} using the given servlet context.
155     *
156     * @since 5.5
157     * @since 6.0, passes the request and response too
158     */
159    void initViewIdManager(ServletContext context, HttpServletRequest request, HttpServletResponse response);
160
161    /**
162     * Returns the view id given an outcome, to dispatch to the right view given an outcome.
163     * <p>
164     * For instance, will return "/view_documents.xhtml" given "view_documents".
165     *
166     * @since 5.5
167     */
168    String getViewIdFromOutcome(String outcome, HttpServletRequest httpRequest);
169
170    /**
171     * Returns an outcome given a view id, to fill a document view when parsing a standard JSF URL.
172     * <p>
173     * For instance, will return "view_documents" given "/view_documents.xhtml" or "/view_documents.faces".
174     *
175     * @since 5.5
176     */
177    String getOutcomeFromViewId(String viewId, HttpServletRequest httpRequest);
178
179    /**
180     * Returns an outcome given a url, to fill a document view when parsing a standard JSF URL.
181     * <p>
182     * It parses the given url to extract the outcome, and then calls
183     * {@link #getOutcomeFromViewId(String, HttpServletRequest)}
184     *
185     * @since 5.5
186     */
187    String getOutcomeFromUrl(String url, HttpServletRequest httpRequest);
188
189    /**
190     * Flushes the URLPolicyService cache, to be called when hot reload is performed for instance.
191     *
192     * @since 5.5
193     */
194    void flushCache();
195
196}