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