1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.chemistry.opencmis.client.api;
20
21 import java.util.List;
22 import java.util.Map;
23 import java.util.Set;
24
25 import org.apache.chemistry.opencmis.commons.data.Ace;
26 import org.apache.chemistry.opencmis.commons.data.Acl;
27 import org.apache.chemistry.opencmis.commons.data.AllowableActions;
28 import org.apache.chemistry.opencmis.commons.data.CmisExtensionElement;
29 import org.apache.chemistry.opencmis.commons.enums.AclPropagation;
30 import org.apache.chemistry.opencmis.commons.enums.Action;
31 import org.apache.chemistry.opencmis.commons.enums.ExtensionLevel;
32 import org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException;
33
34 /**
35 * Base interface for all CMIS objects.
36 */
37 public interface CmisObject extends ObjectId, CmisObjectProperties {
38
39 // object
40
41 /**
42 * Returns the allowable actions if they have been fetched for this object.
43 *
44 * @return the allowable actions or {@code null} if the allowable actions
45 * have not been requested or no allowable actions are returned by
46 * the repository
47 *
48 * @cmis 1.0
49 */
50 AllowableActions getAllowableActions();
51
52 /**
53 * Returns if a given action in the Allowable Actions.
54 *
55 * @param action
56 * the action to test, must not be {@code null}
57 * @return {@code true} if the action was found in the Allowable Actions,
58 * {@code false} if the action was not found in the Allowable
59 * Actions
60 * @throws IllegalStateException
61 * if the Allowable Actions haven't been fetched or provided by
62 * the repository
63 *
64 * @cmis 1.0
65 */
66 boolean hasAllowableAction(Action action);
67
68 /**
69 * Returns the relationships if they have been fetched for this object.
70 *
71 * @return the relationships to or from this object or {@code null} if the
72 * relationships have not been requested or no relationships are
73 * returned by the repository
74 *
75 * @cmis 1.0
76 */
77 List<Relationship> getRelationships();
78
79 /**
80 * Returns the ACL if it has been fetched for this object.
81 *
82 * @cmis 1.0
83 */
84 Acl getAcl();
85
86 /**
87 * Returns all permissions for the given principal from the ACL.
88 *
89 * @param principalId
90 * the principal ID, must not be {@code null}
91 * @return the set of permissions for this user, or an empty set if
92 * principal is not in the ACL
93 * @throws IllegalStateException
94 * if the ACL hasn't been fetched or provided by the repository
95 *
96 * @cmis 1.0
97 */
98 Set<String> getPermissionsForPrincipal(String principalId);
99
100 // object service
101
102 /**
103 * Deletes this object. If this object is a document, the whole version
104 * series is deleted.
105 *
106 * @cmis 1.0
107 */
108 void delete();
109
110 /**
111 * Deletes this object.
112 *
113 * @param allVersions
114 * if this object is a document this parameter defines whether
115 * only this version ({@code false}) or all versions
116 * ({@code true} ) should be deleted, the parameter is ignored
117 * for all other object types
118 *
119 * @cmis 1.0
120 */
121 void delete(boolean allVersions);
122
123 /**
124 * Updates the provided properties and refreshes this object afterwards. If
125 * the repository created a new object, for example a new version, this new
126 * object is returned. Otherwise the current object is returned.
127 *
128 * @param properties
129 * the properties to update
130 *
131 * @return the updated object
132 *
133 * @cmis 1.0
134 */
135 CmisObject updateProperties(Map<String, ?> properties);
136
137 /**
138 * Updates the provided properties. If the repository created a new object,
139 * for example a new version, the object ID of the new object is returned.
140 * Otherwise the object ID of the current object is returned.
141 *
142 * @param properties
143 * the properties to update
144 * @param refresh
145 * {@code true} if this object should be refreshed after the
146 * update, {@code false} if not
147 *
148 * @return the object ID of the updated object
149 *
150 * @cmis 1.0
151 */
152 ObjectId updateProperties(Map<String, ?> properties, boolean refresh);
153
154 /**
155 * Updates the provided properties and refreshes this object afterwards. If
156 * the repository created a new object, for example a new version, this new
157 * object is returned. Otherwise the current object is returned.
158 *
159 * Secondary types must be supported by the repository and must have been
160 * retrieved for this object.
161 *
162 * @param properties
163 * the properties to update
164 * @param addSecondaryTypeIds
165 * list of secondary type IDs that should be added, may be
166 * {@code null}
167 * @param removeSecondaryTypeIds
168 * list of secondary type IDs that should be removed, may be
169 * {@code null}
170 *
171 * @return the updated object
172 *
173 * @cmis 1.1
174 */
175 CmisObject updateProperties(Map<String, ?> properties, List<String> addSecondaryTypeIds,
176 List<String> removeSecondaryTypeIds);
177
178 /**
179 * Updates the provided properties. If the repository created a new object,
180 * for example a new version, the object ID of the new object is returned.
181 * Otherwise the object ID of the current object is returned.
182 *
183 * Secondary types must be supported by the repository and must have been
184 * retrieved for this object.
185 *
186 * @param properties
187 * the properties to update
188 * @param addSecondaryTypeIds
189 * list of secondary type IDs that should be added, may be
190 * {@code null}
191 * @param removeSecondaryTypeIds
192 * list of secondary type IDs that should be removed, may be
193 * {@code null}
194 * @param refresh
195 * {@code true} if this object should be refreshed after the
196 * update, {@code false} if not
197 *
198 * @return the object ID of the updated object
199 *
200 * @cmis 1.1
201 */
202 ObjectId updateProperties(Map<String, ?> properties, List<String> addSecondaryTypeIds,
203 List<String> removeSecondaryTypeIds, boolean refresh);
204
205 /**
206 * Renames this object (changes the value of {@code cmis:name}). If the
207 * repository created a new object, for example a new version, this new
208 * object is returned. Otherwise the current object is returned.
209 *
210 * @param newName
211 * the new name, not {@code null} or empty
212 *
213 * @return the updated object
214 *
215 * @cmis 1.0
216 */
217 CmisObject rename(String newName);
218
219 /**
220 * Renames this object (changes the value of {@code cmis:name}). If the
221 * repository created a new object, for example a new version, the object id
222 * of the new object is returned. Otherwise the object id of the current
223 * object is returned.
224 *
225 * @param newName
226 * the new name, not {@code null} or empty
227 * @param refresh
228 * {@code true} if this object should be refreshed after the
229 * update, {@code false} if not
230 *
231 * @return the object ID of the updated object
232 *
233 * @cmis 1.0
234 */
235 ObjectId rename(String newName, boolean refresh);
236
237 // renditions
238
239 /**
240 * Returns the renditions if they have been fetched for this object.
241 *
242 * @return the renditions of this object or {@code null} if the renditions
243 * have not been requested or no renditions exist for this object
244 *
245 * @cmis 1.0
246 */
247 List<Rendition> getRenditions();
248
249 // policy service
250
251 /**
252 * Applies the provided policies and refreshes this object afterwards.
253 *
254 * @param policyIds
255 * the IDs of the policies to be applied
256 *
257 * @cmis 1.0
258 */
259 void applyPolicy(ObjectId... policyIds);
260
261 /**
262 * Applies the provided policy.
263 *
264 * @param policyId
265 * the ID of the policy to be applied
266 * @param refresh
267 * {@code true} if this object should be refreshed after the
268 * update, {@code false} if not
269 *
270 * @cmis 1.0
271 */
272 void applyPolicy(ObjectId policyId, boolean refresh);
273
274 /**
275 * Removes the provided policies and refreshes this object afterwards.
276 *
277 * @param policyIds
278 * the IDs of the policies to be removed
279 *
280 * @cmis 1.0
281 */
282 void removePolicy(ObjectId... policyIds);
283
284 /**
285 * Removes the provided policy.
286 *
287 * @param policyId
288 * the ID of the policy to be removed
289 * @param refresh
290 * {@code true} if this object should be refreshed after the
291 * update, {@code false} if not
292 *
293 * @cmis 1.0
294 */
295 void removePolicy(ObjectId policyId, boolean refresh);
296
297 /**
298 * Returns the applied policies if they have been fetched for this object.
299 * This method fetches the policy objects from the repository when this
300 * method is called for the first time. Policy objects that don't exist are
301 * ignored.
302 *
303 * @return the list of policies applied to this object or {@code null} if
304 * the policies have not been requested or no policies are applied
305 * to this object
306 *
307 * @see #getPolicyIds()
308 *
309 * @cmis 1.0
310 */
311 List<Policy> getPolicies();
312
313 /**
314 * Returns the applied policy IDs if they have been fetched for this object.
315 * All applied policy IDs are returned, even IDs of policies that don't
316 * exist.
317 *
318 * @return the list of IDs of applied policies or {@code null} if the
319 * policies have not been requested or no policies are applied to
320 * this object
321 *
322 * @see #getPolicies()
323 *
324 * @cmis 1.0
325 */
326 List<ObjectId> getPolicyIds();
327
328 // ACL service
329
330 /**
331 * Adds and removes ACEs to the object and refreshes this object afterwards.
332 *
333 * @return the new ACL of this object
334 *
335 * @cmis 1.0
336 */
337 Acl applyAcl(List<Ace> addAces, List<Ace> removeAces, AclPropagation aclPropagation);
338
339 /**
340 * Adds ACEs to the object and refreshes this object afterwards.
341 *
342 * @return the new ACL of this object
343 *
344 * @cmis 1.0
345 */
346 Acl addAcl(List<Ace> addAces, AclPropagation aclPropagation);
347
348 /**
349 * Removes ACEs to the object and refreshes this object afterwards.
350 *
351 * @return the new ACL of this object
352 *
353 * @cmis 1.0
354 */
355 Acl removeAcl(List<Ace> removeAces, AclPropagation aclPropagation);
356
357 /**
358 * Removes the direct ACE of this object, sets the provided ACEs to the
359 * object and refreshes this object afterwards.
360 *
361 * @return the new ACL of this object
362 *
363 * @cmis 1.0
364 */
365 Acl setAcl(List<Ace> aces);
366
367 // extensions
368
369 /**
370 * Returns the extensions for the given level.
371 *
372 * @param level
373 * the level
374 *
375 * @return the extensions at that level or {@code null} if there no
376 * extensions
377 *
378 * @cmis 1.0
379 */
380 List<CmisExtensionElement> getExtensions(ExtensionLevel level);
381
382 // adapters
383
384 /**
385 * Returns an adapter based on the given interface.
386 *
387 * @return an adapter object or {@code null} if no adapter object could be
388 * created
389 */
390 <T> T getAdapter(Class<T> adapterInterface);
391
392 // session handling
393
394 /**
395 * Returns the timestamp of the last refresh.
396 *
397 * @return the difference, measured in milliseconds, between the last
398 * refresh time and midnight, January 1, 1970 UTC.
399 */
400 long getRefreshTimestamp();
401
402 /**
403 * Reloads this object from the repository.
404 *
405 * @throws CmisObjectNotFoundException
406 * if the object doesn't exist anymore in the repository
407 */
408 void refresh();
409
410 /**
411 * Reloads the data from the repository if the last refresh did not occur
412 * within {@code durationInMillis}.
413 *
414 * @throws CmisObjectNotFoundException
415 * if the object doesn't exist anymore in the repository
416 */
417 void refreshIfOld(long durationInMillis);
418 }