001/*
002 * (C) Copyright 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 *     Antoine Taillefer <ataillefer@nuxeo.com>
018 */
019package org.nuxeo.drive.service;
020
021import java.security.Principal;
022import java.util.Map;
023
024import org.nuxeo.drive.adapter.FileSystemItem;
025import org.nuxeo.drive.adapter.FolderItem;
026import org.nuxeo.drive.service.impl.AbstractFileSystemItemFactory;
027import org.nuxeo.drive.service.impl.DefaultFileSystemItemFactory;
028import org.nuxeo.ecm.core.api.DocumentModel;
029import org.nuxeo.ecm.core.api.Lock;
030
031/**
032 * Interface for the classes contributed to the {@code fileSystemItemFactory} extension point of the
033 * {@link FileSystemItemAdapterService}.
034 * <p>
035 * Allows to get a {@link FileSystemItem} for a given {@link DocumentModel} or a given {@link FileSystemItem} id.
036 *
037 * @author Antoine Taillefer
038 * @see AbstractFileSystemItemFactory
039 * @see DefaultFileSystemItemFactory
040 * @see VersioningFileSystemItemFactory
041 * @see TopLevelFolderItemFactory
042 */
043public interface FileSystemItemFactory {
044
045    /**
046     * Gets the factory unique name.
047     */
048    String getName();
049
050    /**
051     * Sets the factory unique name.
052     */
053    void setName(String name);
054
055    /**
056     * Handles the factory parameters contributed through the {@code fileSystemItemFactory} contribution.
057     */
058    void handleParameters(Map<String, String> parameters);
059
060    /**
061     * Returns true if the given {@link DocumentModel} is adaptable as a {@link FileSystemItem}.
062     *
063     * @see #isFileSystemItem(DocumentModel, boolean)
064     */
065    boolean isFileSystemItem(DocumentModel doc);
066
067    /**
068     * Returns true if the given {@link DocumentModel} is adaptable as a {@link FileSystemItem}. If
069     * {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state, else if the document is in
070     * this state it is not considered as adaptable as a {@link FileSystemItem}, thus the method returns false.
071     */
072    boolean isFileSystemItem(DocumentModel doc, boolean includeDeleted);
073
074    /**
075     * Returns true if the given {@link DocumentModel} is adaptable as a {@link FileSystemItem}.
076     * <p>
077     * If {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state, else if the document is
078     * in this state it is not considered as adaptable as a {@link FileSystemItem}, thus the method returns false.
079     * <p>
080     * If {@code relaxSyncRootConstraint} is true no filter is applied on the synchronization root aspect for the
081     * current user.
082     */
083    boolean isFileSystemItem(DocumentModel doc, boolean includeDeleted, boolean relaxSyncRootConstraint);
084
085    /**
086     * Gets the {@link FileSystemItem} for the given {@link DocumentModel}.
087     *
088     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
089     *         {@link FileSystemItem}
090     * @see #isFileSystemItem(DocumentModel)
091     * @see #getFileSystemItem(DocumentModel, boolean)
092     */
093    FileSystemItem getFileSystemItem(DocumentModel doc);
094
095    /**
096     * Gets the {@link FileSystemItem} for the given {@link DocumentModel}. If {@code includeDeleted} is true no filter
097     * is applied on the "deleted" life cycle state, else if the document is in this state it is not considered as
098     * adaptable as a {@link FileSystemItem}, thus the method returns null.
099     *
100     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
101     *         {@link FileSystemItem}
102     * @see #isFileSystemItem(DocumentModel, boolean)
103     */
104    FileSystemItem getFileSystemItem(DocumentModel doc, boolean includeDeleted);
105
106    /**
107     * Gets the {@link FileSystemItem} for the given {@link DocumentModel}.
108     * <p>
109     * If {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state, else if the document is
110     * in this state it is not considered as adaptable as a {@link FileSystemItem}, thus the method returns null.
111     * <p>
112     * If {@code relaxSyncRootConstraint} is true no filter is applied on the synchronization root aspect for the
113     * current user.
114     *
115     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
116     *         {@link FileSystemItem}
117     * @see #isFileSystemItem(DocumentModel, boolean, boolean)
118     */
119    FileSystemItem getFileSystemItem(DocumentModel doc, boolean includeDeleted, boolean relaxSyncRootConstraint);
120
121    /**
122     * Gets the {@link FileSystemItem} for the given {@link DocumentModel}.
123     * <p>
124     * If {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state, else if the document is
125     * in this state it is not considered as adaptable as a {@link FileSystemItem}, thus the method returns null.
126     * <p>
127     * If {@code relaxSyncRootConstraint} is true no filter is applied on the synchronization root aspect for the
128     * current user.
129     * <p>
130     * If {@code getLockInfo} is true the {@link Lock} is fetched from the {@link DocumentModel} and set on the returned
131     * {@link FileSystemItem}.
132     *
133     * @since 8.3
134     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
135     *         {@link FileSystemItem}
136     * @see #isFileSystemItem(DocumentModel, boolean, boolean)
137     */
138    FileSystemItem getFileSystemItem(DocumentModel doc, boolean includeDeleted, boolean relaxSyncRootConstraint,
139            boolean getLockInfo);
140
141    /**
142     * Gets the {@link FileSystemItem} for the given {@link DocumentModel} forcing its parent with the given
143     * {@code parentItem}.
144     *
145     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
146     *         {@link FileSystemItem}
147     * @see #getFileSystemItem(DocumentModel, FolderItem, boolean)
148     */
149    FileSystemItem getFileSystemItem(DocumentModel doc, FolderItem parentItem);
150
151    /**
152     * Gets the {@link FileSystemItem} for the given {@link DocumentModel} forcing its parent with the given
153     * {@code parentItem}. If {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state,
154     * else if the document is in this state it is not considered as adaptable as a {@link FileSystemItem}, thus the
155     * method returns null.
156     *
157     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
158     *         {@link FileSystemItem}
159     */
160    FileSystemItem getFileSystemItem(DocumentModel doc, FolderItem parentItem, boolean includeDeleted);
161
162    /**
163     * Gets the {@link FileSystemItem} for the given {@link DocumentModel} forcing its parent with the given
164     * {@code parentItem}.
165     * <p>
166     * If {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state, else if the document is
167     * in this state it is not considered as adaptable as a {@link FileSystemItem}, thus the method returns null.
168     * <p>
169     * If {@code relaxSyncRootConstraint} is true no filter is applied on the synchronization root aspect for the
170     * current user.
171     *
172     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
173     *         {@link FileSystemItem}
174     */
175    FileSystemItem getFileSystemItem(DocumentModel doc, FolderItem parentItem, boolean includeDeleted,
176            boolean relaxSyncRootConstraint);
177
178    /**
179     * Gets the {@link FileSystemItem} for the given {@link DocumentModel} forcing its parent with the given
180     * {@code parentItem}.
181     * <p>
182     * If {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state, else if the document is
183     * in this state it is not considered as adaptable as a {@link FileSystemItem}, thus the method returns null.
184     * <p>
185     * If {@code relaxSyncRootConstraint} is true no filter is applied on the synchronization root aspect for the
186     * current user.
187     * <p>
188     * If {@code getLockInfo} is true the {@link Lock} is fetched from the {@link DocumentModel} and set on the returned
189     * {@link FileSystemItem}.
190     *
191     * @since 8.3
192     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
193     *         {@link FileSystemItem}
194     */
195    FileSystemItem getFileSystemItem(DocumentModel doc, FolderItem parentItem, boolean includeDeleted,
196            boolean relaxSyncRootConstraint, boolean getLockInfo);
197
198    /**
199     * Returns true if the given {@link FileSystemItem} id can be handled by this factory. It is typically the case when
200     * the factory has been responsible for generating the {@link FileSystemItem}.
201     */
202    boolean canHandleFileSystemItemId(String id);
203
204    /**
205     * Returns true if a {@link FileSystemItem} with the given id exists for the given principal.
206     */
207    boolean exists(String id, Principal principal);
208
209    /**
210     * Gets the {@link FileSystemItem} with the given id using a core session fetched with the given principal.
211     *
212     * @return the {@link FileSystemItem} or null if none matches the given id
213     */
214    FileSystemItem getFileSystemItemById(String id, Principal principal);
215
216    /**
217     * Gets the {@link FileSystemItem} with the given id and parent id using a core session fetched with the given
218     * principal.
219     *
220     * @return the {@link FileSystemItem} or null if none matches the given id and parent id
221     * @since 6.0
222     */
223    FileSystemItem getFileSystemItemById(String id, String parentId, Principal principal);
224
225    /**
226     * Gets the {@link DocumentModel} bound to the given {@link FileSystemItem} id using a core session fetched with the
227     * given principal.
228     *
229     * @deprecated since 7.2
230     * @return the {@link DocumentModel}
231     * @since 6.0
232     */
233    @Deprecated
234    DocumentModel getDocumentByFileSystemId(String id, Principal principal);
235
236}