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