001/*
002 * (C) Copyright 2006-2012 Nuxeo SA (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 *     Thierry Delprat
016 *     Antoine Taillefer
017 */
018package org.nuxeo.ecm.webapp.documentsLists;
019
020import java.util.List;
021
022import org.jboss.seam.annotations.Observer;
023import org.nuxeo.ecm.core.api.DocumentModel;
024import org.nuxeo.ecm.webapp.helpers.EventNames;
025
026/**
027 * Seam component used to manage named lists of documents.
028 * <p>
029 * Managing the DM lists into this component insteed of directly inside the Seam context offers the following
030 * advantages:
031 * <ul>
032 * <li>DM Lists life cycle management can be done transparently, the DocumentsListsManager can use internal fields or
033 * differently scoped variables (Conversation, Process ...)
034 * <li>DocumentsListsManager provides (will) an Extension Point mechanisme to register new names lists
035 * <li>DocumentsListsManager provides add configurations to each lists
036 * <ul>
037 * <li>List Name
038 * <li>List Icone
039 * <li>List append behavior
040 * <li>Category of the list
041 * <li>...
042 * </ul>
043 * <li>DocumentsListsManager provides helpers features for merging and resetting lists
044 * </ul>
045 *
046 * @author tiry
047 */
048public interface DocumentsListsManager {
049
050    /**
051     * List identifier: Default working list.
052     */
053    String DEFAULT_WORKING_LIST = "DEFAULT";
054
055    /**
056     * List identifier: Clipboard list.
057     */
058    String CLIPBOARD = "CLIPBOARD";
059
060    /**
061     * List identifier: Stores the current selection of documents.
062     */
063    String CURRENT_DOCUMENT_SELECTION = "CURRENT_SELECTION";
064
065    /**
066     * List identifier: Stores the current selection of deleted documents.
067     */
068    String CURRENT_DOCUMENT_TRASH_SELECTION = "CURRENT_SELECTION_TRASH";
069
070    /**
071     * List identifier: Stores the current selection of published documents.
072     */
073    String CURRENT_DOCUMENT_SECTION_SELECTION = "CURRENT_SELECTION_SECTIONS";
074
075    /**
076     * List identifier: Stores the current selection of versions.
077     *
078     * @since 5.6
079     */
080    String CURRENT_VERSION_SELECTION = "CURRENT_SELECTION_VERSIONS";
081
082    /**
083     * Creates (declares) a new named list of documents.
084     *
085     * @param listName Name of the list
086     */
087    void createWorkingList(String listName, DocumentsListDescriptor descriptor);
088
089    /**
090     * Returns the list listName.
091     *
092     * @param listName Name of the list
093     * @return
094     */
095    List<DocumentModel> getWorkingList(String listName);
096
097    /**
098     * Returns the default list.
099     *
100     * @return
101     */
102    List<DocumentModel> getWorkingList();
103
104    /**
105     * Returns the list of document types contained into the list ListName.
106     *
107     * @param listName Name of the list to retrieve
108     * @return the DocumentModel List or null if the ListName is unknown
109     */
110    List<String> getWorkingListTypes(String listName);
111
112    /**
113     * Returns the list of document types contained in the default list.
114     *
115     * @return the DocumentModel List
116     */
117    List<String> getWorkingListTypes();
118
119    /**
120     * Updates the list listName.
121     *
122     * @param listName Name of the list to update
123     * @param docList the DocumentModel list to store in the list ListName
124     */
125    void setWorkingList(String listName, List<DocumentModel> docList);
126
127    /**
128     * Updates the default list.
129     *
130     * @param docList the DocumentModel list to store in the default list
131     */
132    void setWorkingList(List<DocumentModel> docList);
133
134    /**
135     * Adds one document to the list listName.
136     *
137     * @param listName the name of the list to update
138     * @param doc the doc to append
139     * @return the updated list of DocumentModels
140     */
141    List<DocumentModel> addToWorkingList(String listName, DocumentModel doc);
142
143    /**
144     * Adds one document to the default list.
145     *
146     * @param doc
147     * @return the updated list of DocumentModels
148     */
149    List<DocumentModel> addToWorkingList(DocumentModel doc);
150
151    /**
152     * Adds a list of DocumentModels to the list ListName.
153     *
154     * @param listName the name of the list to update
155     * @param docList the DocumentModels list to append
156     * @return the updated list of DocumentModels
157     */
158    List<DocumentModel> addToWorkingList(String listName, List<DocumentModel> docList);
159
160    /**
161     * Adds a list of DocumentModels to the list ListName.
162     *
163     * @param listName the name of the list to update
164     * @param docList the DocumentModels list to append
165     * @param forceAppend force the new elements to be appened even if the list default behaviour is reset
166     * @return the updated list of DocumentModels
167     */
168    List<DocumentModel> addToWorkingList(String listName, List<DocumentModel> docList, Boolean forceAppend);
169
170    /**
171     * Adds a list of DocumentModels to the default list.
172     *
173     * @param docList
174     * @return the updated list of DocumentModels
175     */
176    List<DocumentModel> addToWorkingList(List<DocumentModel> docList);
177
178    /**
179     * Removes one DocumentModel from the list ListName.
180     *
181     * @param listName
182     * @param doc
183     * @return the updated list of DocumentModels
184     */
185    List<DocumentModel> removeFromWorkingList(String listName, DocumentModel doc);
186
187    List<DocumentModel> removeFromWorkingList(String listName, List<DocumentModel> lst);
188
189    /**
190     * Removes one DocumentModel from the default list.
191     *
192     * @param doc
193     * @return the updated list of DocumentModels
194     */
195    List<DocumentModel> removeFromWorkingList(DocumentModel doc);
196
197    /**
198     * Removes DocumentModels from the list ListName.
199     *
200     * @param listName
201     * @return the updated list of DocumentModels
202     */
203    List<DocumentModel> resetWorkingList(String listName);
204
205    /**
206     * Removes DocumentModels from the default list.
207     *
208     * @return the updated list of DocumentModels
209     */
210    List<DocumentModel> resetWorkingList();
211
212    /**
213     * Resets list listName and fill it with newDocList.
214     *
215     * @param listName
216     * @param newDocList
217     * @return
218     */
219    List<DocumentModel> resetWorkingList(String listName, List<DocumentModel> newDocList);
220
221    /**
222     * Resets default list and fills it with newDocList.
223     *
224     * @param newDocList
225     * @return the updated list of DocumentModels
226     */
227    List<DocumentModel> resetWorkingList(List<DocumentModel> newDocList);
228
229    /**
230     * Check is list listName is empty.
231     *
232     * @param listName
233     * @return true if the list is Empty
234     */
235    boolean isWorkingListEmpty(String listName);
236
237    /**
238     * Checks if default list is empty.
239     *
240     * @return true if the list is Empty
241     */
242    boolean isWorkingListEmpty();
243
244    /**
245     * Method called by Seam event service to reset lists.
246     */
247    @Observer(value = { EventNames.DOCUMENT_SELECTION_CHANGED }, create = false)
248    void refreshLists(DocumentModel currentDocument);
249
250    /**
251     * Removes documentsToRemove from all lists.
252     *
253     * @param documentsToRemove
254     */
255    void removeFromAllLists(List<DocumentModel> documentsToRemove);
256
257    /**
258     * Init Method (replaces for now Registry initialization that will be done by the extension point and the Runtime).
259     */
260    void initListManager();
261
262    /**
263     * Returns the availables lists names for a given category.
264     *
265     * @param categoryName
266     * @return the names of the available lists
267     */
268    List<String> getWorkingListNamesForCategory(String categoryName);
269
270    /**
271     * Gets the descriptor (meta-data) of a given list.
272     *
273     * @param listName
274     * @return the Descriptor of the DocumentModel list
275     */
276    DocumentsListDescriptor getWorkingListDescriptor(String listName);
277
278    /**
279     * Gets the descriptor (meta-data) of a default list.
280     *
281     * @return the Descriptor of the DocumentModel list
282     */
283    DocumentsListDescriptor getWorkingListDescriptor();
284
285}