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;
029
030/**
031 * Interface for the classes contributed to the {@code fileSystemItemFactory} extension point of the
032 * {@link FileSystemItemAdapterService}.
033 * <p>
034 * Allows to get a {@link FileSystemItem} for a given {@link DocumentModel} or a given {@link FileSystemItem} id.
035 *
036 * @author Antoine Taillefer
037 * @see AbstractFileSystemItemFactory
038 * @see DefaultFileSystemItemFactory
039 * @see VersioningFileSystemItemFactory
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} forcing its parent id with the given id.
122     *
123     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
124     *         {@link FileSystemItem}
125     * @see #isFileSystemItem(DocumentModel)
126     * @see #getFileSystemItem(DocumentModel, String, boolean)
127     */
128    FileSystemItem getFileSystemItem(DocumentModel doc, FolderItem parentItem);
129
130    /**
131     * Gets the {@link FileSystemItem} for the given {@link DocumentModel} forcing its parent id with the given id. If
132     * {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state, else if the document is in
133     * this state it is not considered as adaptable as a {@link FileSystemItem}, thus the method returns null.
134     *
135     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
136     *         {@link FileSystemItem}
137     * @see #isFileSystemItem(DocumentModel, boolean)
138     */
139    FileSystemItem getFileSystemItem(DocumentModel doc, FolderItem parentItem, boolean includeDeleted);
140
141    /**
142     * Gets the {@link FileSystemItem} for the given {@link DocumentModel} forcing its parent id with the given id.
143     * <p>
144     * If {@code includeDeleted} is true no filter is applied on the "deleted" life cycle state, else if the document is
145     * in this state it is not considered as adaptable as a {@link FileSystemItem}, thus the method returns null.
146     * <p>
147     * If {@code relaxSyncRootConstraint} is true no filter is applied on the synchronization root aspect for the
148     * current user.
149     *
150     * @return the {@link FileSystemItem} or null if the {@link DocumentModel} is not adaptable as a
151     *         {@link FileSystemItem}
152     * @see #isFileSystemItem(DocumentModel, boolean, boolean)
153     */
154    FileSystemItem getFileSystemItem(DocumentModel doc, FolderItem parentItem, boolean includeDeleted,
155            boolean relaxSyncRootConstraint);
156
157    /**
158     * Returns true if the given {@link FileSystemItem} id can be handled by this factory. It is typically the case when
159     * the factory has been responsible for generating the {@link FileSystemItem}.
160     */
161    boolean canHandleFileSystemItemId(String id);
162
163    /**
164     * Returns true if a {@link FileSystemItem} with the given id exists for the given principal.
165     */
166    boolean exists(String id, Principal principal);
167
168    /**
169     * Gets the {@link FileSystemItem} with the given id using a core session fetched with the given principal.
170     *
171     * @return the {@link FileSystemItem} or null if none matches the given id
172     */
173    FileSystemItem getFileSystemItemById(String id, Principal principal);
174
175    /**
176     * Gets the {@link FileSystemItem} with the given id and parent id using a core session fetched with the given
177     * principal.
178     *
179     * @return the {@link FileSystemItem} or null if none matches the given id and parent id
180     * @since 6.0
181     */
182    FileSystemItem getFileSystemItemById(String id, String parentId, Principal principal);
183
184    /**
185     * Gets the {@link DocumentModel} bound to the given {@link FileSystemItem} id using a core session fetched with the
186     * given principal.
187     *
188     * @deprecated since 7.2
189     * @return the {@link DocumentModel}
190     * @since 6.0
191     */
192    @Deprecated
193    DocumentModel getDocumentByFileSystemId(String id, Principal principal);
194
195}