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: JOOoConvertPluginImpl.java 18651 2007-05-13 20:28:53Z sfermigier $
018 */
019
020package org.nuxeo.ecm.platform.ui.web.api;
021
022import java.util.List;
023
024import org.nuxeo.ecm.core.api.CoreSession;
025import org.nuxeo.ecm.core.api.DocumentModel;
026import org.nuxeo.ecm.core.api.DocumentModelList;
027import org.nuxeo.ecm.core.api.DocumentRef;
028import org.nuxeo.ecm.core.api.VersionModel;
029import org.nuxeo.ecm.platform.ui.web.pathelements.PathElement;
030import org.nuxeo.ecm.platform.util.RepositoryLocation;
031
032/**
033 * Stateful Seam component.
034 * <ul>
035 * <li>manages the navigation context variables
036 * <li>outjects them for compatibility
037 * <li>provides getters and setters for navigation context variables (ie : hide what Seam scope is used for that)
038 * <li>provides basic navigation features by leveraging Core API + Distributed cache + internal cache
039 * </ul>
040 * This Seam component should ideally serve only DocumentModel, lists of DMs and Trees of DMs: no UI related structure.
041 */
042public interface NavigationContext {
043
044    /**
045     * Callback for component initialization.
046     */
047    void init();
048
049    /**
050     * @return current repository location or null if no server is connected
051     */
052    RepositoryLocation getCurrentServerLocation();
053
054    /**
055     * @return current selected repository location or null
056     * @deprecated use getCurrentServerLocation instead
057     */
058    @Deprecated
059    RepositoryLocation getSelectedServerLocation();
060
061    /**
062     * Current Domain, <strong>if user has read permission on it</strong>. Use
063     *
064     * @link{getCurrentDomainPath if you are in a situation where it is not guaranteed that the user has read permission
065     *                            on the domain.
066     * @return the current domain.
067     */
068    DocumentModel getCurrentDomain();
069
070    /**
071     * Finds the path to current domain.
072     * <p>
073     * This method tries hard to always returns an answer: the path to current domain is deduced from the path of
074     * current document (assuming that it would be the first element of this path).
075     * <p>
076     * If current document is null, the same logic is applied to the first document found amongst all documents user has
077     * access to.
078     */
079    String getCurrentDomainPath();
080
081    void setCurrentDomain(DocumentModel currentDomain);
082
083    /**
084     * Current Document other than Domain or Workspace.
085     */
086    DocumentModel getCurrentDocument();
087
088    /**
089     * Returns the currentSuperSpace (Section, Workspace...). Uses SuperSpace facet for that.
090     */
091    DocumentModel getCurrentSuperSpace();
092
093    void setCurrentDocument(DocumentModel documentModel);
094
095    /**
096     * This is used for documents about to be created, which are not yet persisted thus not all their fields might be
097     * valid (like its reference).
098     */
099    DocumentModel getChangeableDocument();
100
101    void setChangeableDocument(DocumentModel changeableDocument);
102
103    /**
104     * Saves the current copy of the document to server.
105     */
106    void saveCurrentDocument();
107
108    List<PathElement> getCurrentPathList();
109
110    /**
111     * Returns a list of the DocumentsModels (to build the BreadCrumb for example).
112     */
113    DocumentModelList getCurrentPath();
114
115    /**
116     * @return the URL that can be used to refer the current document from outside current context
117     */
118    String getCurrentDocumentUrl();
119
120    /**
121     * @return the URL that can be used to refer the current document from outside current context
122     */
123    String getCurrentDocumentFullUrl();
124
125    /**
126     * Updates the current document in the (session) context and resets the other common structures (breadcrumbs, etc).
127     *
128     * @param doc DocumentModel that will be set as current document
129     */
130    void updateDocumentContext(DocumentModel doc);
131
132    /**
133     * Resets all context variables.
134     */
135    void resetCurrentContext();
136
137    /**
138     * Performs context updates and returns the view associated with the document and action passed.
139     *
140     * @return document view associated with the result
141     */
142    String getActionResult(DocumentModel doc, UserAction action);
143
144    /**
145     * go to the root server, the root document or to the dashboard if the latest document are not accessible.
146     */
147    String goHome();
148
149    String goBack();
150
151    /**
152     * Updates the context and returns the view for the given document id.
153     */
154    String navigateToId(String documentId);
155
156    /**
157     * Updates the context and returns the view for the given document ref.
158     */
159    String navigateToRef(DocumentRef docRef);
160
161    /**
162     * Updates the context with given document and returns its default view.
163     * <p>
164     * The default view is configured on the UI document type definition.
165     */
166    String navigateToDocument(DocumentModel doc);
167
168    /**
169     * Initializes the context for the given doc and returns its given view.
170     * <p>
171     * If view is not found, use default view.
172     *
173     * @param doc
174     * @param viewId for the document as defined in its type
175     * @return navigation view for the document
176     */
177    String navigateToDocument(DocumentModel doc, String viewId);
178
179    /**
180     * Initializes the context for the given doc and returns its given view.
181     * <p>
182     * If view is not found, use default view set on the UI document type. This is an alias to
183     * <code>navigateToDocument(DocumentModel doc, String viewId)</code>, to resolve ambiguity when method is invoked by
184     * an EL expression.
185     *
186     * @param doc
187     * @param viewId for the document as defined in its type
188     * @return navigation view for the document
189     */
190    String navigateToDocumentWithView(DocumentModel doc, String viewId);
191
192    /**
193     * Initializes the context for the given refs and returns the default view for the doc.
194     */
195    String navigateTo(RepositoryLocation serverLocation, DocumentRef docRef);
196
197    /**
198     * Initializes the context for the given refs and returns the default view for the doc.
199     */
200    String navigateToURL(String documentUrl);
201
202    /**
203     * Initializes the context for the given refs and returns the default view for the doc.
204     * <p>
205     * Takes parameter String docRef from the Request.
206     */
207    String navigateToURL();
208
209    // --- do not call these methods directly
210    // --- they are listeners - called by Seam
211    void selectionChanged();
212
213    /**
214     * Switch to a new server location by updating the context and updating to the CoreSession (aka the
215     * 'documentManager' Seam component).
216     *
217     * @param serverLocation new server location to connect to
218     */
219    void setCurrentServerLocation(RepositoryLocation serverLocation);
220
221    /**
222     * Returns the current documentManager if any or create a new session to the currently selected repository location.
223     */
224    CoreSession getOrCreateDocumentManager();
225
226    String navigateToDocument(DocumentModel docModel, VersionModel versionModel);
227
228    /**
229     * Gets the currentDocument and puts it in Page context.
230     */
231    DocumentModel factoryCurrentDocument();
232
233    /**
234     * Gets the currentDomain and puts it in Page context.
235     */
236    DocumentModel factoryCurrentDomain();
237
238    /**
239     * Gets the currentWorkspace and puts it in Page context.
240     */
241    DocumentModel factoryCurrentWorkspace();
242
243    /**
244     * Gets the currentSuperSpace and puts it in Page context.
245     */
246    DocumentModel factoryCurrentSuperSpace();
247
248    /**
249     * Gets the currentContentRootWorkspace and puts it in Page context.
250     */
251    DocumentModel factoryCurrentContentRoot();
252
253    /**
254     * Gets the current ServerLocation and puts it in Page Context.
255     */
256    RepositoryLocation factoryCurrentServerLocation();
257
258    /**
259     * Gets current document for edition.
260     */
261    DocumentModel factoryChangeableDocument();
262
263    /**
264     * Gets the current Content Root (Workspaces, Sections, Templates...).
265     */
266    DocumentModel getCurrentContentRoot();
267
268    /**
269     * Gets the current Workspace.
270     */
271    DocumentModel getCurrentWorkspace();
272
273    /**
274     * Sets the current ContentRoot.
275     */
276    void setCurrentContentRoot(DocumentModel currentContentRoot);
277
278    /**
279     * Will trigger reloading of current document data from the server.
280     */
281    void invalidateCurrentDocument();
282
283}