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 }