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     * Update all documents referenced by a collection to add a reference back the collection. This is used when a
159     * creation is created by copy in order to tell the members of a copied collection that they also belongs to the
160     * newly created collection.
161     *
162     * @param collection the collection
163     */
164    void processCopiedCollection(final DocumentModel collection);
165
166    /**
167     * Update all documents referenced by a collection to remove the reference to the collection. This is used after the
168     * complete deletion of a collection.
169     *
170     * @param collection the collection
171     */
172    void processRemovedCollection(final DocumentModel collection);
173
174    /**
175     * Update all collections referenced by a document. This is used after the complete deletion of a document to remove
176     * its reference from all collections it belongs to.
177     *
178     * @param collectionMember the document
179     */
180    void processRemovedCollectionMember(final DocumentModel collectionMember);
181
182    /**
183     * Restore the collection members of the version.
184     *
185     * @param collection the collection
186     * @param collection the version
187     *
188     * @since 7.3
189     */
190    void processRestoredCollection(final DocumentModel collection, final DocumentModel version);
191
192    /**
193     * Remove a list of document from a given collection.
194     *
195     * @param collection the collection
196     * @param documentListToBeRemoved the document to be removed
197     * @param session the core session
198     */
199    void removeAllFromCollection(final DocumentModel collection, final List<DocumentModel> documentListToBeRemoved,
200            final CoreSession session);
201
202    /**
203     * Remove a document from a collection.
204     *
205     * @param collection the collection
206     * @param documentToBeRemoved the document to be removed
207     * @param session the core session
208     */
209    void removeFromCollection(final DocumentModel collection, final DocumentModel documentToBeRemoved,
210            final CoreSession session);
211
212    /**
213     * Create a collection with a given name, description and path.
214     *
215     * @param session
216     * @param title
217     * @param description
218     * @param path
219     * @return
220     * @since 5.9.4
221     */
222    DocumentModel createCollection(final CoreSession session, String title, String description, String path);
223
224    /**
225     * Get user collections root document.
226     *
227     * @param context contextual document
228     * @param session the core session
229     * @return the user collections root document
230     * @since 6.0
231     */
232    DocumentModel getUserDefaultCollections(final DocumentModel context, final CoreSession session);
233
234    /**
235     * @param documentToBeRemoved
236     * @param collectionId
237     * @param session
238     * @since 6.0
239     */
240    void doRemoveFromCollection(DocumentModel documentToBeRemoved, String collectionId, CoreSession session);
241
242}