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