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