001/*
002 * (C) Copyright 2007 Nuxeo SAS (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 *     Nuxeo - initial API and implementation
016 *
017 * $Id$
018 */
019
020package org.nuxeo.ecm.platform.api.ws;
021
022
023/**
024 * Nuxeo EP remoting API.
025 *
026 * @author <a href="mailto:ja@nuxeo.com">Julien Anguenot</a>
027 */
028public interface NuxeoRemoting extends BaseNuxeoWebService {
029
030    /**
031     * Gets the current repository name.
032     *
033     * @param sid the session id
034     * @return the repository name
035     */
036    String getRepositoryName(String sid);
037
038    /**
039     * Gets the root document descriptor.
040     *
041     * @return the root document
042     */
043    DocumentDescriptor getRootDocument(String sessionId);
044
045    /**
046     * Gets the doc descriptor given the doc UUID.
047     *
048     * @param sessionId the session id
049     * @param uuid the doc uuid
050     * @return the descriptor
051     */
052    DocumentDescriptor getDocument(String sessionId, String uuid);
053
054    /**
055     * Gets the children of the given document.
056     *
057     * @param sessionId the session id
058     * @param uuid the doc uuid
059     * @return the children descriptors
060     */
061    DocumentDescriptor[] getChildren(String sessionId, String uuid);
062
063    /**
064     * Returns the relative path as a displayable path with parent titles.
065     * <p>
066     * Example: <i>/Workspaces/My Workspaces/Nice Document</i>
067     *
068     * @param sessionId : the session id
069     * @param uuid : the document uuid
070     * @return a relative path
071     */
072    String getRelativePathAsString(String sessionId, String uuid);
073
074    /**
075     * Gets the versions of the given document.
076     *
077     * @param sid
078     * @param uid
079     * @return
080     */
081    DocumentDescriptor[] getVersions(String sid, String uid);
082
083    /**
084     * Gets the current version of the given document.
085     *
086     * @param sid
087     * @return
088     */
089    DocumentDescriptor getCurrentVersion(String sid, String uid);
090
091    /**
092     * Gets the document that created the version specified by the given uid.
093     *
094     * @param sid
095     * @param uid
096     * @return
097     */
098    DocumentDescriptor getSourceDocument(String sid, String uid);
099
100    /**
101     * Returns the document properties.
102     * <p>
103     * All property are returned even blobs. All values are converted to strings.
104     * <p>
105     * It includes the perm link of the document.
106     * <p>
107     * No need to includes blobs here. See the dedicated API.
108     *
109     * @param uuid uuid of the document.
110     * @return a map from name of the property to its value
111     */
112    DocumentProperty[] getDocumentProperties(String sid, String uuid);
113
114    /**
115     * Same as {@link #getDocumentProperties(String, String)} but skips blobs.
116     *
117     * @param sid
118     * @param uuid
119     * @return
120     */
121    DocumentProperty[] getDocumentNoBlobProperties(String sid, String uuid);
122
123    /**
124     * Returns the document blobs only using byte[] format
125     *
126     * @param uuid the uuid of the document.
127     * @return an array of document blob instances.
128     */
129    DocumentBlob[] getDocumentBlobs(String sid, String uuid);
130
131    /**
132     * Returns the document blobs only.
133     *
134     * @param uuid the uuid of the document.
135     * @param useDownloadUrl defines if blob are exported as download url or as byte|[]
136     * @return an array of document blob instances.
137     */
138    DocumentBlob[] getDocumentBlobsExt(String sid, String uuid, boolean useDownloadUrl);
139
140    /**
141     * Returns the merged ACL of the document (contains all ACEs defined on the document and its parents).
142     * <p>
143     * It includes all ACLs for each ACP.
144     *
145     * @param uuid the uuid of the document
146     * @return the ordered list of ACLs
147     */
148    WsACE[] getDocumentACL(String sid, String uuid);
149
150    /**
151     * Returns the merged ACL of the document (contains all ACEs defined on the document, filtering the inherited ones).
152     * <p>
153     * It includes all ACLs for each ACP.
154     *
155     * @param uuid the uuid of the document
156     * @return the ordered list of ACLs
157     */
158    WsACE[] getDocumentLocalACL(String sid, String uuid);
159
160    /**
161     * Checks the given permission for the current user on the given document.
162     *
163     * @param sid
164     * @param uuid
165     * @param permission
166     * @return
167     */
168    boolean hasPermission(String sid, String uuid, String permission);
169
170    /**
171     * Returns the list of all users.
172     * <p>
173     * This method supports pagination in case of large user dbs.
174     * <p>
175     * <b>Pagination is not yet working!</b>
176     *
177     * @param from pagination start
178     * @param to pagination stop
179     * @return an array of principal names
180     */
181    String[] listUsers(String sid, int from, int to);
182
183    /**
184     * Return the list of all groups.
185     * <p>
186     * This method supports pagination in case of large user dbs
187     * <p>
188     * <b>Pagination is not yet working!</b>
189     *
190     * @param from pagination start
191     * @param to pagination stop
192     * @return an array of group names
193     */
194    String[] listGroups(String sid, int from, int to);
195
196    /**
197     * Get all users inside the given group. If the group is null then return all users in the system.
198     *
199     * @param sid the session id
200     * @param parentGroup the parent group
201     */
202    String[] getUsers(String sid, String parentGroup);
203
204    /**
205     * Gets all sub-groups inside the given group. If the parent group is null returns all top level groups.
206     *
207     * @param sid the session id
208     * @param parentGroup the parent group
209     * @return
210     */
211    String[] getGroups(String sid, String parentGroup);
212
213    String uploadDocument(String sid, String path, String type, String[] properties);
214
215    /**
216     * Gets all properties and ACLs from a document uses byte[] format to export blob
217     *
218     * @param sid the session id
219     * @param uuid the doc uuid
220     * @return
221     */
222    DocumentSnapshot getDocumentSnapshot(String sid, String uuid);
223
224    /**
225     * Gets all properties and ACLs from a document
226     *
227     * @param sid the session id
228     * @param uuid the doc uuid
229     * @param useDownloadUrl define blob export format
230     * @return
231     */
232    DocumentSnapshot getDocumentSnapshotExt(String sid, String uuid, boolean useDownloadUrl);
233}