001/*
002 * (C) Copyright 2014 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 *     <a href="mailto:grenard@nuxeo.com">Guillaume</a>
018 */
019package org.nuxeo.ecm.collections.api;
020
021import java.util.List;
022
023import org.nuxeo.ecm.core.api.CoreSession;
024import org.nuxeo.ecm.core.api.DocumentModel;
025
026/**
027 * @since 5.9.3
028 */
029public interface CollectionManager {
030
031    /**
032     * Add a document to a collection.
033     *
034     * @param collection the collection
035     * @param documentToBeAdded the document to be added
036     * @param session the core session
037     */
038    void addToCollection(final DocumentModel collection, final DocumentModel documentToBeAdded,
039            final CoreSession session);
040
041    /**
042     * Add a list of document to a collection.
043     *
044     * @param collection the collection
045     * @param documentListToBeAdded the list of document to be added
046     * @param session the core session
047     */
048    void addToCollection(final DocumentModel collection, final List<DocumentModel> documentListToBeAdded,
049            final CoreSession session);
050
051    /**
052     * Add a document to a new collection.
053     *
054     * @param newTitle the title of the new collection
055     * @param newDescription the description of the new collection
056     * @param documentToBeAdded the document to be added
057     * @param session the core session
058     */
059    void addToNewCollection(String newTitle, String newDescription, DocumentModel documentToBeAdded, CoreSession session);
060
061    /**
062     * Add a list of document to a new collection.
063     *
064     * @param newTitle the title of the new collection
065     * @param newDescription the description of the new collection
066     * @param documentListToBeAdded the list of document to be added
067     * @param session the core session
068     */
069    void addToNewCollection(String newTitle, String newDescription, List<DocumentModel> documentListToBeAdded,
070            CoreSession documentManager);
071
072    /**
073     * Check that a document is a collection and that the given core session has permission to add document inside.
074     *
075     * @param collection the collection
076     * @param session the core session
077     * @return true if the given document is a Collection and the core session has permission to add document inside,
078     *         false otherwise
079     */
080    boolean canAddToCollection(final DocumentModel collection, final CoreSession session);
081
082    /**
083     * Check that the given core session has permission to manage the collection.
084     *
085     * @param collection the collection
086     * @param session the core session
087     * @return true if the core session has permission to manage the collection
088     */
089    boolean canManage(final DocumentModel collection, final CoreSession session);
090
091    /**
092     * Get the list of collection of a document. The resulting list will only contain the collections visible by the
093     * given core session (i.e. the collections on which the given core session has at least READ permission).
094     *
095     * @param collectionMember the document
096     * @param session the core session
097     * @return the list of visible collections the collectionMember belong to
098     */
099    List<DocumentModel> getVisibleCollection(final DocumentModel collectionMember, final CoreSession session);
100
101    /**
102     * Get the list of collection of a document. The resulting list will only contain the collections visible by the
103     * given core session (i.e. the collections on which the given core session has at least READ permission). The
104     * resulting list's size will be limited to masResult.
105     *
106     * @param collectionMember the document
107     * @param maxResult the limit
108     * @param session the core session
109     * @return the list of maxResult first visible collections the collectionMember belong to
110     */
111    List<DocumentModel> getVisibleCollection(final DocumentModel collectionMember, final int maxResult,
112            final CoreSession session);
113
114    /**
115     * Check that the given core session has READ permission on at least one collection of the given document.
116     *
117     * @param collectionMember the document
118     * @param session the core session
119     * @return true if collectionMember has at least one collection on which the session has READ permission
120     */
121    boolean hasVisibleCollection(final DocumentModel collectionMember, final CoreSession session);
122
123    /**
124     * Check that a document can be added to a collection.
125     *
126     * @param document the document
127     * @return true if the document can be added to the collection
128     */
129    boolean isCollectable(final DocumentModel document);
130
131    /**
132     * Check that a document has already been added to a collection.
133     *
134     * @param document the document
135     * @return true if the document has already been added to a collection
136     */
137    boolean isCollected(final DocumentModel document);
138
139    /**
140     * Check that a document is a collection.
141     *
142     * @param document the document
143     * @return true if the document is a collection
144     */
145    boolean isCollection(final DocumentModel document);
146
147    /**
148     * Check whether a document is in a given collection.
149     *
150     * @param collection the collection
151     * @param document the document to check
152     * @param session the session
153     * @since 5.9.4
154     */
155    boolean isInCollection(final DocumentModel collection, final DocumentModel document, final CoreSession session);
156
157    /**
158     * Move the member1 right after the member2 within the collection. If the member2 is null, then the member1 is
159     * moved to first position of the collection.
160     *
161     * @param session the session
162     * @param collection the collection
163     * @param member1 the member1
164     * @param member2 the member2
165     * @return true if successfully moved
166     * @since 8.4
167     */
168    boolean moveMembers(final CoreSession session, final DocumentModel collection, final DocumentModel member1,
169            final DocumentModel member2);
170
171    /**
172     * Update all documents referenced by a collection to add a reference back the collection. This is used when a
173     * creation is created by copy in order to tell the members of a copied collection that they also belongs to the
174     * newly created collection.
175     *
176     * @param collection the collection
177     */
178    void processCopiedCollection(final DocumentModel collection);
179
180    /**
181     * Update all documents referenced by a collection to remove the reference to the collection. This is used after the
182     * complete deletion of a collection.
183     *
184     * @param collection the collection
185     */
186    void processRemovedCollection(final DocumentModel collection);
187
188    /**
189     * Update all collections referenced by a document. This is used after the complete deletion of a document to remove
190     * its reference from all collections it belongs to.
191     *
192     * @param collectionMember the document
193     */
194    void processRemovedCollectionMember(final DocumentModel collectionMember);
195
196    /**
197     * Restore the collection members of the version.
198     *
199     * @param collection the collection
200     * @param collection the version
201     *
202     * @since 7.3
203     */
204    void processRestoredCollection(final DocumentModel collection, final DocumentModel version);
205
206    /**
207     * Remove a list of document from a given collection.
208     *
209     * @param collection the collection
210     * @param documentListToBeRemoved the document to be removed
211     * @param session the core session
212     */
213    void removeAllFromCollection(final DocumentModel collection, final List<DocumentModel> documentListToBeRemoved,
214            final CoreSession session);
215
216    /**
217     * Remove a document from a collection.
218     *
219     * @param collection the collection
220     * @param documentToBeRemoved the document to be removed
221     * @param session the core session
222     */
223    void removeFromCollection(final DocumentModel collection, final DocumentModel documentToBeRemoved,
224            final CoreSession session);
225
226    /**
227     * Create a collection with a given name, description and path.
228     *
229     * @param session
230     * @param title
231     * @param description
232     * @param path
233     * @return
234     * @since 5.9.4
235     */
236    DocumentModel createCollection(final CoreSession session, String title, String description, String path);
237
238    /**
239     * Get user collections root document.
240     *
241     * @param context contextual document
242     * @param session the core session
243     * @return the user collections root document
244     * @since 6.0
245     */
246    DocumentModel getUserDefaultCollections(final DocumentModel context, final CoreSession session);
247
248    /**
249     * @param documentToBeRemoved
250     * @param collectionId
251     * @param session
252     * @since 6.0
253     */
254    void doRemoveFromCollection(DocumentModel documentToBeRemoved, String collectionId, CoreSession session);
255
256}