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