0001: /**********************************************************************************
0002: * $URL: https://source.sakaiproject.org/svn/content/tags/sakai_2-4-1/content-api/api/src/java/org/sakaiproject/content/api/ContentHostingService.java $
0003: * $Id: ContentHostingService.java 28750 2007-04-12 01:56:52Z ajpoland@iupui.edu $
0004: ***********************************************************************************
0005: *
0006: * Copyright (c) 2003, 2004, 2005, 2006, 2007 The Sakai Foundation.
0007: *
0008: * Licensed under the Educational Community License, Version 1.0 (the "License");
0009: * you may not use this file except in compliance with the License.
0010: * You may obtain a copy of the License at
0011: *
0012: * http://www.opensource.org/licenses/ecl1.php
0013: *
0014: * Unless required by applicable law or agreed to in writing, software
0015: * distributed under the License is distributed on an "AS IS" BASIS,
0016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0017: * See the License for the specific language governing permissions and
0018: * limitations under the License.
0019: *
0020: **********************************************************************************/package org.sakaiproject.content.api;
0021:
0022: import java.util.Collection;
0023: import java.util.Comparator;
0024: import java.util.List;
0025: import java.util.Map;
0026: import java.util.Set;
0027: import java.util.Stack;
0028: import java.util.TreeSet;
0029:
0030: import org.sakaiproject.entity.api.Entity;
0031: import org.sakaiproject.entity.api.EntityProducer;
0032: import org.sakaiproject.entity.api.ResourceProperties;
0033: import org.sakaiproject.entity.api.ResourcePropertiesEdit;
0034: import org.sakaiproject.exception.IdInvalidException;
0035: import org.sakaiproject.exception.IdLengthException;
0036: import org.sakaiproject.exception.IdUniquenessException;
0037: import org.sakaiproject.exception.IdUnusedException;
0038: import org.sakaiproject.exception.IdUsedException;
0039: import org.sakaiproject.exception.InUseException;
0040: import org.sakaiproject.exception.InconsistentException;
0041: import org.sakaiproject.exception.OverQuotaException;
0042: import org.sakaiproject.exception.PermissionException;
0043: import org.sakaiproject.exception.ServerOverloadException;
0044: import org.sakaiproject.exception.TypeException;
0045: import org.sakaiproject.time.api.Time;
0046: import org.w3c.dom.Document;
0047:
0048: /**
0049: * <p>
0050: * ContentHostingService is the Interface for Sakai Content Hosting services. This service is based on WebDAV for terminology and capability, although it may be implemented using some other content management framework.
0051: * </p>
0052: * <p>
0053: * The ContentHostingService manages shared content resources and collections. A resource is a file of some media type (MIME, such as image/gif, text/html, etc), with a resource id (a URI) and properties (name value pairs), as described in WebDAV.
0054: * </p>
0055: * <p>
0056: * Resources are organized in collections. A collection is a list of resource ids, and is itself a resource with a resource id. In the spirit of WebDAV, a resource must be placed into a collection, and the containing collection must exist before the
0057: * resource is added.
0058: * </p>
0059: * <p>
0060: * Resource ids used in the API with the service are relative to the root "/" collection of the service. The full URL to a resource can be accessed from the service or from a resource object.
0061: * </p>
0062: * <p>
0063: * Resources have any number of properties. A property is defined by a name, which includes an XML namespace, and a value, which is any string. Some properties are pre-defined (by the DAV: namespace), and are "live"; the value is generated by the service.
0064: * Other properties are "dead", the values are maintained by the users. Properties from namespaces other than "DAV:" are accepted.
0065: * </p>
0066: * <p>
0067: * TO DO:
0068: * <ul>
0069: * <li>add copy, move to collection and resource</li>
0070: * <li>add lock</li>
0071: * <li>add version control</li>
0072: * </ul>
0073: * </p>
0074: * <p>
0075: * The ContentHostingService can be asked:
0076: * <ul>
0077: * <li>access, create or delete a collection resource.</li>
0078: * <li>access, create or delete a non-collection resource in a collection.</li>
0079: * <li>access, add to or delete properties of a resource.</li>
0080: * </ul>
0081: * See the methods in this API for details.
0082: * </p>
0083: * <p>
0084: * Security is enforced and Usage Events are generated when there are these accesses:
0085: * <ul>
0086: * <li>create a resource: content.new</li>
0087: * <li>read a resource: content.read</li>
0088: * <li>update the contents/properties of a resource: content.revise</li>
0089: * <li>removing a resource: content.delete</li>
0090: * </ul>
0091: * </p>
0092: */
0093: public interface ContentHostingService extends EntityProducer {
0094: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
0095: static final String APPLICATION_ID = "sakai:content";
0096:
0097: /** This string starts the references to resources in this service. */
0098: public static final String REFERENCE_ROOT = Entity.SEPARATOR
0099: + "content";
0100:
0101: /** Name of the event when creating a resource. */
0102: public static final String EVENT_RESOURCE_ADD = "content.new";
0103:
0104: /** Name of the event when reading a resource. */
0105: public static final String EVENT_RESOURCE_READ = "content.read";
0106:
0107: /** Name of the event when writing a resource. */
0108: public static final String EVENT_RESOURCE_WRITE = "content.revise";
0109:
0110: /** Name of the event when removing a resource. */
0111: public static final String EVENT_RESOURCE_REMOVE = "content.delete";
0112:
0113: /** Security function for creating a resource. */
0114: public static final String AUTH_RESOURCE_ADD = "content.new";
0115:
0116: /** Security function for reading a resource. */
0117: public static final String AUTH_RESOURCE_READ = "content.read";
0118:
0119: /** Security function for writing any resource. */
0120: public static final String AUTH_RESOURCE_WRITE_ANY = "content.revise.any";
0121:
0122: /** Security function for writing own resource. */
0123: public static final String AUTH_RESOURCE_WRITE_OWN = "content.revise.own";
0124:
0125: /** Security function for removing any resource. */
0126: public static final String AUTH_RESOURCE_REMOVE_ANY = "content.delete.any";
0127:
0128: /** Security function for removing own resource. */
0129: public static final String AUTH_RESOURCE_REMOVE_OWN = "content.delete.own";
0130:
0131: /** Security function granted to users who will then have membership in all site groups based on their site membership. */
0132: public static final String AUTH_RESOURCE_ALL_GROUPS = "content.all.groups";
0133:
0134: /** Security function for accessing a resource belonging to a group. */
0135: public static final String AUTH_GROUP_RESOURCE_READ = "content.read_group_resources";
0136:
0137: /** Security function for those who may OWN a dropbox. */
0138: public static final String AUTH_DROPBOX_OWN = "dropbox.own";
0139:
0140: /** Security function for those who may maintain dropboxes. */
0141: public static final String AUTH_DROPBOX_MAINTAIN = "dropbox.maintain";
0142:
0143: /** Security function for accessing hidden entities */
0144: public static final String AUTH_RESOURCE_HIDDEN = "content.hidden";
0145:
0146: /** Property name on a Resource that will cause getUrl() and getRefernce() to return an alternal root reference. */
0147: public static final String PROP_ALTERNATE_REFERENCE = "sakai:reference-root";
0148:
0149: /** The maximum number of characters allowed in a new resource ID: make is so the reference, /content/<id>, is 255 or less */
0150: public static final int MAXIMUM_RESOURCE_ID_LENGTH = 247;
0151:
0152: /** Number of times to attempt to find a unique resource id when copying or moving a resource */
0153: public static final int MAXIMUM_ATTEMPTS_FOR_UNIQUENESS = 100;
0154:
0155: /**
0156: * When assigning default priority (for "priority" sort) folders come before files,
0157: * so files get "priority" much higher than folders. Add the offset to folder priorities
0158: * to force all files to sort after folders
0159: */
0160: public static final int CONTENT_RESOURCE_PRIORITY_OFFSET = Integer.MAX_VALUE / 8;
0161:
0162: /** The collection id for the attachments collection */
0163: public static final String ATTACHMENTS_COLLECTION = "/attachment/";
0164:
0165: /** Collection id for the user sites. */
0166: public static final String COLLECTION_USER = "/user/";
0167:
0168: /** Collection id for the non-user sites. */
0169: public static final String COLLECTION_SITE = "/group/";
0170:
0171: /** The content root collection for dropboxes. */
0172: public static final String COLLECTION_DROPBOX = "/group-user/";
0173:
0174: /** The content root collection for items that are public. */
0175: public static final String COLLECTION_PUBLIC = "/public/";
0176:
0177: /** The content root collection for meleteDocs */
0178: public static final String COLLECTION_MELETE_DOCS = "/meleteDocs/";
0179:
0180: /** A "list" of all root-level collections */
0181: public static final Set<String> ROOT_COLLECTIONS = new TreeSet<String>();
0182:
0183: /**
0184: * For a given id, return its UUID (creating it if it does not already exist)
0185: */
0186: public String getUuid(String id);
0187:
0188: /**
0189: *
0190: * @param id id of the resource to set the UUID for
0191: * @param uuid the new UUID of the resource
0192: * @throws IdInvalidException if the given resource already has a UUID set
0193: */
0194: public void setUuid(String id, String uuid)
0195: throws IdInvalidException;
0196:
0197: /**
0198: * For a given UUID, attempt to lookup and return the corresponding id (URI)
0199: */
0200:
0201: public String resolveUuid(String uuid);
0202:
0203: /**
0204: * check permissions for addCollection().
0205: *
0206: * @param channelId
0207: * The channel id.
0208: * @return true if the user is allowed to addCollection(id), false if not.
0209: */
0210: public boolean allowAddCollection(String id);
0211:
0212: /**
0213: * Create a new collection with the given resource id.
0214: *
0215: * @param id
0216: * The id of the collection.
0217: * @param properties
0218: * A ResourceProperties object with the properties to add to the new collection.
0219: * @exception IdUsedException
0220: * if the id is already in use.
0221: * @exception IdInvalidException
0222: * if the id is invalid.
0223: * @exception PermissionException
0224: * if the user does not have permission to add a collection, or add a member to a collection.
0225: * @exception InconsistentException
0226: * if the containing collection does not exist.
0227: * @return a new ContentCollection object.
0228: * @deprecated Suggest use of {@link #addCollection(String)} followed by {@link #Edit.getPropertiesEdit()},
0229: * and {@link #commitCollection(ContentCollectionEdit)}
0230: */
0231: public ContentCollection addCollection(String id,
0232: ResourceProperties properties) throws IdUsedException,
0233: IdInvalidException, PermissionException,
0234: InconsistentException;
0235:
0236: /**
0237: * Create a new collection with the given resource id.
0238: *
0239: * @param id
0240: * The id of the collection.
0241: * @param properties
0242: * A ResourceProperties object with the properties to add to the new collection.
0243: * @param groups
0244: * The (possibly empty) collection (String) of reference-strings for groups to be associated with this entity.
0245: *
0246: * @exception IdUsedException
0247: * if the id is already in use.
0248: * @exception IdInvalidException
0249: * if the id is invalid.
0250: * @exception PermissionException
0251: * if the user does not have permission to add a collection, or add a member to a collection.
0252: * @exception InconsistentException
0253: * if the containing collection does not exist.
0254: * @return a new ContentCollection object.
0255: * @throws InconsistentException
0256: * @throws PermissionException
0257: * @throws IdInvalidException
0258: * @throws IdUsedException
0259: * @deprecated Suggest use of {@link #addCollection(String)} followed by {@link #Edit.getPropertiesEdit()},
0260: * {@link #GroupAwareEdit.setGroupAccess(Collection)} and {@link #commitCollection(ContentCollectionEdit)}
0261: */
0262: public ContentCollection addCollection(String id,
0263: ResourceProperties properties, Collection groups)
0264: throws IdUsedException, IdInvalidException,
0265: PermissionException, InconsistentException;
0266:
0267: /**
0268: * Create a new collection with the given resource id.
0269: *
0270: * @param id
0271: * The id of the collection.
0272: * @param properties
0273: * A ResourceProperties object with the properties to add to the new collection.
0274: * @param groups
0275: * The (possibly empty) collection (String) of reference-strings for groups to be associated with this entity.
0276: * @param hidden
0277: * A flag indicating that the entity should be hidden from users unless they created the entity or have permission to modify it.
0278: * @param releaseDate
0279: * The time at which the entity becomes available to most users. The entity should be available immediately if this value is null.
0280: * @param retractDate
0281: * The date after which the entity is no longer available to most users. The entity should be available indefinitely if this value is null.
0282: *
0283: * @exception IdUsedException
0284: * if the id is already in use.
0285: * @exception IdInvalidException
0286: * if the id is invalid.
0287: * @exception PermissionException
0288: * if the user does not have permission to add a collection, or add a member to a collection.
0289: * @exception InconsistentException
0290: * if the containing collection does not exist.
0291: * @return a new ContentCollection object.
0292: * @throws InconsistentException
0293: * @throws PermissionException
0294: * @throws IdInvalidException
0295: * @throws IdUsedException
0296: * @deprecated Suggest use of {@link #addCollection(String)} followed by {@link #Edit.getPropertiesEdit()},
0297: * {@link #GroupAwareEdit.setGroupAccess(Collection)}, {@link #GroupAwareEdit.setAvailability(boolean, Time, Time)}
0298: * and {@link #commitCollection(ContentCollectionEdit)}
0299: */
0300: public ContentCollection addCollection(String id,
0301: ResourceProperties properties, Collection groups,
0302: boolean hidden, Time releaseDate, Time retractDate)
0303: throws IdUsedException, IdInvalidException,
0304: PermissionException, InconsistentException;
0305:
0306: /**
0307: * Create a new collection with the given resource id, locked for update. Must commitCollection() to make official, or cancelCollection() when done!
0308: *
0309: * @param id
0310: * The id of the collection.
0311: * @exception IdUsedException
0312: * if the id is already in use.
0313: * @exception IdInvalidException
0314: * if the id is invalid.
0315: * @exception PermissionException
0316: * if the user does not have permission to add a collection, or add a member to a collection.
0317: * @exception InconsistentException
0318: * if the containing collection does not exist.
0319: * @return a new ContentCollection object.
0320: */
0321: public ContentCollectionEdit addCollection(String id)
0322: throws IdUsedException, IdInvalidException,
0323: PermissionException, InconsistentException;
0324:
0325: /**
0326: * Check permissions for getCollection().
0327: *
0328: * @param id
0329: * The id of the collection.
0330: * @return true if the user is allowed to getCollection(id), false if not.
0331: */
0332: public boolean allowGetCollection(String id);
0333:
0334: /**
0335: * Check access to the collection with this local resource id.
0336: *
0337: * @param id
0338: * The id of the collection.
0339: * @exception IdUnusedException
0340: * if the id does not exist.
0341: * @exception TypeException
0342: * if the resource exists but is not a collection.
0343: * @exception PermissionException
0344: * if the user does not have permissions to see this collection (or read through containing collections).
0345: */
0346: public void checkCollection(String id) throws IdUnusedException,
0347: TypeException, PermissionException;
0348:
0349: /**
0350: * Access the collection with this local resource id. The collection internal members and properties are accessible from the returned Collection object.
0351: *
0352: * @param id
0353: * The id of the collection.
0354: * @exception IdUnusedException
0355: * if the id does not exist.
0356: * @exception TypeException
0357: * if the resource exists but is not a collection.
0358: * @exception PermissionException
0359: * if the user does not have permissions to see this collection (or read through containing collections).
0360: * @return The ContentCollection object found.
0361: */
0362: public ContentCollection getCollection(String id)
0363: throws IdUnusedException, TypeException,
0364: PermissionException;
0365:
0366: /**
0367: * Count the number of (recursive) children for a given id. examples: With a nested collection structure exactly like this: /a /a/b /a/b/1 /a/b/2 getCollectionSize(/a) returns 3 (due to these three children: /a/b /a/b/1 /a/b/2) getCollectionSize(/a/b)
0368: * returns 2 (due to these two children: /a/b/1 /a/b/2) getCollectionSize(/a/b/1) returns 0 (nothing falls below this collection)
0369: *
0370: * @param id
0371: * The id of the collection.
0372: * @exception IdUnusedException
0373: * if the id does not exist.
0374: * @exception TypeException
0375: * if the resource exists but is not a collection.
0376: * @exception PermissionException
0377: * if the user does not have permissions to see this collection (or read through containing collections).
0378: * @return The number of internal members
0379: */
0380: public int getCollectionSize(String id) throws IdUnusedException,
0381: TypeException, PermissionException;
0382:
0383: /**
0384: * Access a List of ContentEntities (resources and collections) objects in this path (and below) to which the current user has access.
0385: *
0386: * @param id
0387: * A collection id.
0388: * @return a List of the ContentEntity objects.
0389: */
0390: public List getAllEntities(String id);
0391:
0392: /**
0393: * Access a List of all the ContentResource objects in this path (and below) which the current user has access.
0394: *
0395: * @param id
0396: * A collection id.
0397: * @return a List of the ContentResource objects.
0398: */
0399: public List getAllResources(String id);
0400:
0401: /**
0402: * check permissions for editCollection()
0403: *
0404: * @param id
0405: * The id of the collection.
0406: * @return true if the user is allowed to update the collection, false if not.
0407: */
0408: public boolean allowUpdateCollection(String id);
0409:
0410: /**
0411: * Access the collection with this local resource id, locked for update. Must commitCollection() to make official, or cancelCollection() when done! The collection internal members and properties are accessible from the returned Collection object.
0412: *
0413: * @param id
0414: * The id of the collection.
0415: * @exception IdUnusedException
0416: * if the id does not exist.
0417: * @exception TypeException
0418: * if the resource exists but is not a collection.
0419: * @exception PermissionException
0420: * if the user does not have permissions to see this collection (or read through containing collections).
0421: * @exception InUseException
0422: * if the Collection is locked by someone else.
0423: * @return The ContentCollection object found.
0424: */
0425: public ContentCollectionEdit editCollection(String id)
0426: throws IdUnusedException, TypeException,
0427: PermissionException, InUseException;
0428:
0429: /**
0430: * check permissions for removeCollection().
0431: *
0432: * @param id
0433: * The id of the collection.
0434: * @return true if the user is allowed to removeCollection(id), false if not.
0435: */
0436: public boolean allowRemoveCollection(String id);
0437:
0438: /**
0439: * Remove a collection and all members of the collection, internal or deeper.
0440: *
0441: * @param id
0442: * The id of the collection.
0443: * @exception IdUnusedException
0444: * if the id does not exist.
0445: * @exception TypeException
0446: * if the resource exists but is not a collection.
0447: * @exception PermissionException
0448: * if the user does not have permissions to remove this collection, read through any containing
0449: * @exception InUseException
0450: * if the collection or a contained member is locked by someone else. collections, or remove any members of the collection.
0451: * @exception ServerOverloadException
0452: * if the server is configured to write the resource body to the filesystem and an attempt to access the resource body of any collection member fails.
0453: */
0454: public void removeCollection(String id) throws IdUnusedException,
0455: TypeException, PermissionException, InUseException,
0456: ServerOverloadException;
0457:
0458: /**
0459: * Remove just a collection. It must be empty.
0460: *
0461: * @param collection
0462: * The collection to remove.
0463: * @exception TypeException
0464: * if the resource exists but is not a collection.
0465: * @exception PermissionException
0466: * if the user does not have permissions to remove this collection, read through any containing
0467: * @exception InconsistentException
0468: * if the collection has members, so that the removal would leave things in an inconsistent state.
0469: * @exception ServerOverloadException
0470: * if the server is configured to write the resource body to the filesystem and an attempt to access the resource body of any collection member fails.
0471: */
0472: public void removeCollection(ContentCollectionEdit edit)
0473: throws TypeException, PermissionException,
0474: InconsistentException, ServerOverloadException;
0475:
0476: /**
0477: * Commit the changes made, and release the lock. The Object is disabled, and not to be used after this call.
0478: *
0479: * @param edit
0480: * The ContentCollectionEdit object to commit.
0481: * @throws PermissionException
0482: */
0483: public void commitCollection(ContentCollectionEdit edit);
0484:
0485: /**
0486: * Cancel the changes made object, and release the lock. The Object is disabled, and not to be used after this call.
0487: *
0488: * @param edit
0489: * The ContentCollectionEdit object to commit.
0490: */
0491: public void cancelCollection(ContentCollectionEdit edit);
0492:
0493: /** copy %%%, move * */
0494:
0495: /**
0496: * check permissions for addResource().
0497: *
0498: * @param id
0499: * The id of the new resource.
0500: * @return true if the user is allowed to addResource(id), false if not.
0501: */
0502: public boolean allowAddResource(String id);
0503:
0504: /**
0505: * Create a new resource with the given properties.
0506: *
0507: * @param id
0508: * The id of the new resource.
0509: * @param type
0510: * The mime type string of the resource.
0511: * @param content
0512: * An array containing the bytes of the resource's content.
0513: * @param properties
0514: * A ResourceProperties object with the properties to add to the new resource.
0515: * @param priority
0516: * The notification priority for this commit.
0517: * @exception PermissionException
0518: * if the user does not have permission to add a resource to the containing collection.
0519: * @exception IdUsedException
0520: * if the resource id is already in use.
0521: * @exception IdInvalidException
0522: * if the resource id is invalid.
0523: * @exception InconsistentException
0524: * if the containing collection does not exist.
0525: * @exception OverQuotaException
0526: * if this would result in being over quota.
0527: * @exception ServerOverloadException
0528: * if the server is configured to write the resource body to the filesystem and the save fails.
0529: * @return a new ContentResource object.
0530: */
0531: public ContentResource addResource(String id, String type,
0532: byte[] content, ResourceProperties properties, int priority)
0533: throws PermissionException, IdUsedException,
0534: IdInvalidException, InconsistentException,
0535: OverQuotaException, ServerOverloadException;
0536:
0537: /**
0538: * Create a new resource with the given resource name used as a resource id within the
0539: * specified collection or (if that id is already in use) with a resource id based on
0540: * a variation on the name to achieve a unique id, provided a unique id can be found
0541: * before a limit is reached on the number of attempts to achieve uniqueness.
0542: *
0543: * @param name
0544: * The name of the new resource (such as a filename).
0545: * @param collectionId
0546: * The id of the collection to which the resource should be added.
0547: * @param limit
0548: * The maximum number of attempts at finding a unique id based on the given id.
0549: * @param type
0550: * The mime type string of the resource.
0551: * @param content
0552: * An array containing the bytes of the resource's content.
0553: * @param properties
0554: * A ResourceProperties object with the properties to add to the new resource.
0555: * @param priority
0556: * The notification priority for this commit.
0557: * @exception PermissionException
0558: * if the user does not have permission to add a resource to the containing collection.
0559: * @exception IdUniquenessException
0560: * if a unique resource id cannot be found before the limit on the number of attempts is reached.
0561: * @exception IdLengthException
0562: * if the resource id exceeds the maximum number of characters for a valid resource id.
0563: * @exception IdInvalidException
0564: * if the resource id is invalid.
0565: * @exception InconsistentException
0566: * if the containing collection does not exist.
0567: * @exception OverQuotaException
0568: * if this would result in being over quota.
0569: * @exception ServerOverloadException
0570: * if the server is configured to write the resource body to the filesystem and the save fails.
0571: * @return a new ContentResource object.
0572: */
0573: public ContentResource addResource(String name,
0574: String collectionId, int limit, String type,
0575: byte[] content, ResourceProperties properties, int priority)
0576: throws PermissionException, IdUniquenessException,
0577: IdLengthException, IdInvalidException,
0578: InconsistentException, IdLengthException,
0579: OverQuotaException, ServerOverloadException;
0580:
0581: /**
0582: * Create a new resource with the given id and attributes, including group awareness.
0583: *
0584: * @param id
0585: * The id of the new resource.
0586: * @param type
0587: * The mime type string of the resource.
0588: * @param content
0589: * An array containing the bytes of the resource's content.
0590: * @param properties
0591: * A ResourceProperties object with the properties to add to the new resource.
0592: * @param groups
0593: * A collection (String) of references to Group objects representing the site subgroups that should have access to this entity.
0594: * May be empty to indicate access is not limited to a group or groups.
0595: * @param priority
0596: * The notification priority for this commit.
0597: * @exception PermissionException
0598: * if the user does not have permission to add a resource to the containing collection.
0599: * @exception IdUsedException
0600: * if the resource id is already in use.
0601: * @exception IdInvalidException
0602: * if the resource id is invalid.
0603: * @exception InconsistentException
0604: * if the containing collection does not exist.
0605: * @exception OverQuotaException
0606: * if this would result in being over quota.
0607: * @exception ServerOverloadException
0608: * if the server is configured to write the resource body to the filesystem and the save fails.
0609: * @return a new ContentResource object.
0610: */
0611: public ContentResource addResource(String id, String type,
0612: byte[] content, ResourceProperties properties,
0613: Collection groups, int priority)
0614: throws PermissionException, IdUsedException,
0615: IdInvalidException, InconsistentException,
0616: OverQuotaException, ServerOverloadException;
0617:
0618: /**
0619: * Create a new resource with the given resource name used as a resource id within the
0620: * specified collection or (if that id is already in use) with a resource id based on
0621: * a variation on the name to achieve a unique id, provided a unique id can be found
0622: * before a limit is reached on the number of attempts to achieve uniqueness.
0623: *
0624: * @param name
0625: * The name of the new resource (such as a filename).
0626: * @param collectionId
0627: * The id of the collection to which the resource should be added.
0628: * @param limit
0629: * The maximum number of attempts at finding a unique id based on the given id.
0630: * @param type
0631: * The mime type string of the resource.
0632: * @param content
0633: * An array containing the bytes of the resource's content.
0634: * @param properties
0635: * A ResourceProperties object with the properties to add to the new resource.
0636: * @param groups
0637: * A collection (String) of references to Group objects representing the site subgroups that should have access to this entity.
0638: * May be empty to indicate access is not limited to a group or groups.
0639: * @param priority
0640: * The notification priority for this commit.
0641: * @exception PermissionException
0642: * if the user does not have permission to add a resource to the containing collection.
0643: * @exception IdUniquenessException
0644: * if a unique resource id cannot be found before the limit on the number of attempts is reached.
0645: * @exception IdLengthException
0646: * if the resource id exceeds the maximum number of characters for a valid resource id.
0647: * @exception IdInvalidException
0648: * if the resource id is invalid.
0649: * @exception InconsistentException
0650: * if the containing collection does not exist.
0651: * @exception OverQuotaException
0652: * if this would result in being over quota.
0653: * @exception ServerOverloadException
0654: * if the server is configured to write the resource body to the filesystem and the save fails.
0655: * @return a new ContentResource object.
0656: */
0657: public ContentResource addResource(String name,
0658: String collectionId, int limit, String type,
0659: byte[] content, ResourceProperties properties,
0660: Collection groups, int priority)
0661: throws PermissionException, IdUniquenessException,
0662: IdLengthException, IdInvalidException,
0663: InconsistentException, IdLengthException,
0664: OverQuotaException, ServerOverloadException;
0665:
0666: /**
0667: * Create a new resource with the given resource name used as a resource id within the
0668: * specified collection or (if that id is already in use) with a resource id based on
0669: * a variation on the name to achieve a unique id, provided a unique id can be found
0670: * before a limit is reached on the number of attempts to achieve uniqueness.
0671: *
0672: * @param name
0673: * The name of the new resource (such as a filename).
0674: * @param collectionId
0675: * The id of the collection to which the resource should be added.
0676: * @param limit
0677: * The maximum number of attempts at finding a unique id based on the given id.
0678: * @param type
0679: * The mime type string of the resource.
0680: * @param content
0681: * An array containing the bytes of the resource's content.
0682: * @param properties
0683: * A ResourceProperties object with the properties to add to the new resource.
0684: * @param groups
0685: * A collection (String) of references to Group objects representing the site subgroups that should have access to this entity.
0686: * May be empty to indicate access is not limited to a group or groups.
0687: * @param hidden
0688: * A flag indicating that the entity should be hidden from users unless they created the entity or have permission to modify it.
0689: * @param releaseDate
0690: * The time at which the entity becomes available to most users. The entity should be available immediately if this value is null.
0691: * @param retractDate
0692: * The date after which the entity is no longer available to most users. The entity should be available indefinitely if this value is null.
0693: * @param priority
0694: * The notification priority for this commit.
0695: * @exception PermissionException
0696: * if the user does not have permission to add a resource to the containing collection.
0697: * @exception IdUniquenessException
0698: * if a unique resource id cannot be found before the limit on the number of attempts is reached.
0699: * @exception IdLengthException
0700: * if the resource id exceeds the maximum number of characters for a valid resource id.
0701: * @exception IdInvalidException
0702: * if the resource id is invalid.
0703: * @exception InconsistentException
0704: * if the containing collection does not exist.
0705: * @exception OverQuotaException
0706: * if this would result in being over quota.
0707: * @exception ServerOverloadException
0708: * if the server is configured to write the resource body to the filesystem and the save fails.
0709: * @return a new ContentResource object.
0710: */
0711: public ContentResource addResource(String name,
0712: String collectionId, int limit, String type,
0713: byte[] content, ResourceProperties properties,
0714: Collection groups, boolean hidden, Time releaseDate,
0715: Time retractDate, int priority) throws PermissionException,
0716: IdUniquenessException, IdLengthException,
0717: IdInvalidException, InconsistentException,
0718: IdLengthException, OverQuotaException,
0719: ServerOverloadException;
0720:
0721: /**
0722: * Create a new resource with the given resource id, locked for update. Must commitResource() to make official, or cancelResource() when done!
0723: *
0724: * @param id
0725: * The id of the new resource.
0726: * @exception PermissionException
0727: * if the user does not have permission to add a resource to the containing collection.
0728: * @exception IdUsedException
0729: * if the resource id is already in use.
0730: * @exception IdInvalidException
0731: * if the resource id is invalid.
0732: * @exception InconsistentException
0733: * if the containing collection does not exist.
0734: * @exception ServerOverloadException
0735: * if the server is configured to write the resource body to the filesystem and the save fails.
0736: * @return a new ContentResource object.
0737: */
0738: public ContentResourceEdit addResource(String id)
0739: throws PermissionException, IdUsedException,
0740: IdInvalidException, InconsistentException,
0741: ServerOverloadException;
0742:
0743: /**
0744: * check permissions for addAttachmentResource().
0745: *
0746: * @return true if the user is allowed to addAttachmentResource(), false if not.
0747: */
0748: public boolean allowAddAttachmentResource();
0749:
0750: /**
0751: * Check whether a resource id or collection id references an entity in the attachments collection.
0752: * This method makes no guarantees that a resource actually exists with this id.
0753: * @param id Assumed to be a valid resource id or collection id.
0754: * @return true if the id (assuming it is a valid id for an existing resource or collection)
0755: * references an entity in the hidden attachments area created through one of this class's
0756: * addAttachmentResource methods.
0757: */
0758: public boolean isAttachmentResource(String id);
0759:
0760: /**
0761: * Create a new resource as an attachment to some other resource in the system. The new resource will be placed
0762: * into a newly created collecion in the attachment collection, with an auto-generated id, and given the specified
0763: * resource name within this collection.
0764: *
0765: * @param name
0766: * The name of the new resource, i.e. a partial id relative to the collection where it will live.
0767: * @param type
0768: * The mime type string of the resource.
0769: * @param content
0770: * An array containing the bytes of the resource's content.
0771: * @param properties
0772: * A ResourceProperties object with the properties to add to the new resource.
0773: * @exception IdUsedException
0774: * if the resource name is already in use (not likely, as the containing collection is auto-generated!)
0775: * @exception IdInvalidException
0776: * if the resource name is invalid.
0777: * @exception InconsistentException
0778: * if the containing collection (or it's containing collection...) does not exist.
0779: * @exception PermissionException
0780: * if the user does not have permission to add a collection, or add a member to a collection.
0781: * @exception OverQuotaException
0782: * if this would result in being over quota.
0783: * @exception ServerOverloadException
0784: * if the server is configured to write the resource body to the filesystem and the save fails.
0785: * @return a new ContentResource object.
0786: */
0787: public ContentResource addAttachmentResource(String name,
0788: String type, byte[] content, ResourceProperties properties)
0789: throws IdInvalidException, InconsistentException,
0790: IdUsedException, PermissionException, OverQuotaException,
0791: ServerOverloadException;
0792:
0793: /**
0794: * Create a new resource as an attachment to some other resource in the system. The new resource will be placed
0795: * into a newly created collection in the site collection within the attachment collection. The new collection
0796: * will have an auto-generated id, and it will be given the specified resource name within the site collection.
0797: *
0798: * @param name
0799: * The name of the new resource, i.e. a partial id relative to the collection where it will live.
0800: * @param site
0801: * The string identifier for the site where the attachment is being added within the attachments collection.
0802: * @param tool
0803: * The display-name for the tool through which the attachment is being added within the site's attachments collection.
0804: * @param type
0805: * The mime type string of the resource.
0806: * @param content
0807: * An array containing the bytes of the resource's content.
0808: * @param properties
0809: * A ResourceProperties object with the properties to add to the new resource.
0810: * @exception IdUsedException
0811: * if the resource name is already in use (not likely, as the containing collection is auto-generated!)
0812: * @exception IdInvalidException
0813: * if the resource name is invalid.
0814: * @exception InconsistentException
0815: * if the containing collection (or it's containing collection...) does not exist.
0816: * @exception PermissionException
0817: * if the user does not have permission to add a collection, or add a member to a collection.
0818: * @exception OverQuotaException
0819: * if this would result in being over quota.
0820: * @exception ServerOverloadException
0821: * if the server is configured to write the resource body to the filesystem and the save fails.
0822: * @return a new ContentResource object.
0823: */
0824: public ContentResource addAttachmentResource(String name,
0825: String site, String tool, String type, byte[] content,
0826: ResourceProperties properties) throws IdInvalidException,
0827: InconsistentException, IdUsedException,
0828: PermissionException, OverQuotaException,
0829: ServerOverloadException;
0830:
0831: /**
0832: * Create a new resource as an attachment to some other resource in the system, locked for update. Must commitResource()
0833: * to make official, or cancelResource() when done! The new resource will be placed into a newly created collecion in the
0834: * attachment collection, with an auto-generated id, and given the specified resource name within this collection.
0835: *
0836: * @param name
0837: * The name of the new resource, i.e. a partial id relative to the collection where it will live.
0838: * @exception IdUsedException
0839: * if the resource name is already in use (not likely, as the containing collection is auto-generated!)
0840: * @exception IdInvalidException
0841: * if the resource name is invalid.
0842: * @exception InconsistentException
0843: * if the containing collection (or it's containing collection...) does not exist.
0844: * @exception PermissionException
0845: * if the user does not have permission to add a collection, or add a member to a collection.
0846: * @exception ServerOverloadException
0847: * if the server is configured to write the resource body to the filesystem and the save fails.
0848: * @return a new ContentResource object.
0849: */
0850: public ContentResourceEdit addAttachmentResource(String name)
0851: throws IdInvalidException, InconsistentException,
0852: IdUsedException, PermissionException,
0853: ServerOverloadException;
0854:
0855: /**
0856: * check permissions for updateResource().
0857: *
0858: * @param id
0859: * The id of the new resource.
0860: * @return true if the user is allowed to updateResource(id), false if not.
0861: */
0862: public boolean allowUpdateResource(String id);
0863:
0864: /**
0865: * Update the body and or content type of an existing resource with the given resource id.
0866: *
0867: * @param id
0868: * The id of the resource.
0869: * @param type
0870: * The mime type string of the resource (if null, no change).
0871: * @param content
0872: * An array containing the bytes of the resource's content (if null, no change).
0873: * @exception PermissionException
0874: * if the user does not have permission to add a resource to the containing collection or write the resource.
0875: * @exception IdUnusedException
0876: * if the resource id is not defined.
0877: * @exception TypeException
0878: * if the resource is a collection.
0879: * @exception InUseException
0880: * if the resource is locked by someone else.
0881: * @exception OverQuotaException
0882: * if this would result in being over quota.
0883: * @exception ServerOverloadException
0884: * if the server is configured to write the resource body to the filesystem and the save fails.
0885: * @return a new ContentResource object.
0886: */
0887: public ContentResource updateResource(String id, String type,
0888: byte[] content) throws PermissionException,
0889: IdUnusedException, TypeException, InUseException,
0890: OverQuotaException, ServerOverloadException;
0891:
0892: /**
0893: * Access the resource with this resource id, locked for update. For non-collection resources only. Must commitEdit() to make official, or cancelEdit() when done! The resource content and properties are accessible from the returned Resource object.
0894: *
0895: * @param id
0896: * The id of the resource.
0897: * @exception PermissionException
0898: * if the user does not have permissions to read the resource or read through any containing collection.
0899: * @exception IdUnusedException
0900: * if the resource id is not found.
0901: * @exception TypeException
0902: * if the resource is a collection.
0903: * @exception InUseException
0904: * if the resource is locked by someone else.
0905: * @return the ContentResource object found.
0906: */
0907: public ContentResourceEdit editResource(String id)
0908: throws PermissionException, IdUnusedException,
0909: TypeException, InUseException;
0910:
0911: /**
0912: * check permissions for getResource().
0913: *
0914: * @param id
0915: * The id of the new resource.
0916: * @return true if the user is allowed to getResource(id), false if not.
0917: */
0918: public boolean allowGetResource(String id);
0919:
0920: /**
0921: * Check access to the resource with this local resource id. For non-collection resources only.
0922: *
0923: * @param id
0924: * The id of the resource.
0925: * @exception PermissionException
0926: * if the user does not have permissions to read the resource or read through any containing collection.
0927: * @exception IdUnusedException
0928: * if the resource id is not found.
0929: * @exception TypeException
0930: * if the resource is a collection.
0931: */
0932: public void checkResource(String id) throws PermissionException,
0933: IdUnusedException, TypeException;
0934:
0935: /**
0936: * Access the resource with this resource id. For non-collection resources only. The resource content and properties are accessible from the returned Resource object.
0937: *
0938: * @param id
0939: * The id of the resource.
0940: * @exception PermissionException
0941: * if the user does not have permissions to read the resource or read through any containing collection.
0942: * @exception IdUnusedException
0943: * if the resource id is not found.
0944: * @exception TypeException
0945: * if the resource is a collection.
0946: * @return the ContentResource object found.
0947: */
0948: public ContentResource getResource(String id)
0949: throws PermissionException, IdUnusedException,
0950: TypeException;
0951:
0952: /**
0953: * check permissions for removeResource().
0954: *
0955: * @param id
0956: * The id of the new resource.
0957: * @return true if the user is allowed to removeResource(id), false if not.
0958: */
0959: public boolean allowRemoveResource(String id);
0960:
0961: /**
0962: * Remove a resource. For non-collection resources only.
0963: *
0964: * @param id
0965: * The id of the resource.
0966: * @exception PermissionException
0967: * if the user does not have permissions to read a containing collection, or to remove this resource.
0968: * @exception IdUnusedException
0969: * if the resource id is not found.
0970: * @exception TypeException
0971: * if the resource is a collection.
0972: * @exception InUseException
0973: * if the resource is locked by someone else.
0974: */
0975: public void removeResource(String id) throws PermissionException,
0976: IdUnusedException, TypeException, InUseException;
0977:
0978: /**
0979: * Remove a resource that is locked for update.
0980: *
0981: * @param edit
0982: * The ContentResourceEdit object to remove.
0983: * @exception PermissionException
0984: * if the user does not have permissions to read a containing collection, or to remove this resource.
0985: */
0986: public void removeResource(ContentResourceEdit edit)
0987: throws PermissionException;
0988:
0989: /**
0990: * check permissions for rename().
0991: *
0992: * @param id
0993: * The id of the existing resource.
0994: * @return true if the user is allowed to rename(id), false if not.
0995: */
0996: public boolean allowRename(String id, String new_id);
0997:
0998: /**
0999: * Rename a resource or collection.
1000: *
1001: * @param id
1002: * The id of the resource or collection.
1003: * @param new_id
1004: * The desired id of the resource or collection.
1005: * @return The full id of the resource after the rename is completed.
1006: * @exception PermissionException
1007: * if the user does not have permissions to read a containing collection, or to rename this resource.
1008: * @exception IdUnusedException
1009: * if the resource id is not found.
1010: * @exception TypeException
1011: * if the resource is a collection.
1012: * @exception InUseException
1013: * if the resource is locked by someone else.
1014: * @exception IdUsedException
1015: * if copied item is a collection and the new id is already in use or if the copied item is not a collection and a unique id cannot be found in some arbitrary number of attempts (@see MAXIMUM_ATTEMPTS_FOR_UNIQUENESS).
1016: * @exception ServerOverloadException
1017: * if the server is configured to write the resource body to the filesystem and the save fails.
1018: */
1019: public String rename(String id, String new_id)
1020: throws PermissionException, IdUnusedException,
1021: TypeException, InUseException, OverQuotaException,
1022: InconsistentException, IdUsedException,
1023: ServerOverloadException;
1024:
1025: /**
1026: * check permissions for copy().
1027: *
1028: * @param id
1029: * The id of the new resource.
1030: * @param new_id
1031: * The desired id of the new resource.
1032: * @return true if the user is allowed to copy(id,new_id), false if not.
1033: */
1034: public boolean allowCopy(String id, String new_id);
1035:
1036: /**
1037: * Copy a resource.
1038: *
1039: * @param id
1040: * The id of the resource.
1041: * @param new_id
1042: * The desired id of the new resource.
1043: * @return The full id of the new copy of the resource.
1044: * @exception PermissionException
1045: * if the user does not have permissions to read a containing collection, or to remove this resource.
1046: * @exception IdUnusedException
1047: * if the resource id is not found.
1048: * @exception TypeException
1049: * if the resource is a collection.
1050: * @exception InUseException
1051: * if the resource is locked by someone else.
1052: * @exception IdUsedException
1053: * if copied item is a collection and the new id is already in use or if the copied item is not a collection and a unique id cannot be found in some arbitrary number of attempts (@see MAXIMUM_ATTEMPTS_FOR_UNIQUENESS).
1054: * @exception ServerOverloadException
1055: * if the server is configured to write the resource body to the filesystem and the save fails.
1056: */
1057: public String copy(String id, String new_id)
1058: throws PermissionException, IdUnusedException,
1059: TypeException, InUseException, OverQuotaException,
1060: IdUsedException, ServerOverloadException;
1061:
1062: /**
1063: * Copy a collection or resource from one location to another. Creates a new collection with an id similar to new_folder_id and recursively copies all nested collections and resources within thisCollection to the new collection.
1064: *
1065: * @param id
1066: * The id of the resource.
1067: * @param folder_id
1068: * The id of the folder in which the copy should be created.
1069: * @return The full id of the new copy of the resource.
1070: * @exception PermissionException
1071: * if the user does not have permissions to read a containing collection, or to remove this resource.
1072: * @exception IdUnusedException
1073: * if the resource id is not found.
1074: * @exception TypeException
1075: * if the resource is a collection.
1076: * @exception InUseException
1077: * if the resource is locked by someone else.
1078: * @exception IdLengthException
1079: * if the new id of the copied item (or any nested item) is longer than the maximum length of an id.
1080: * @exception IdUniquenessException
1081: * if a unique id cannot be found in the new folder.
1082: * @exception InconsistentException
1083: * if the destination folder (folder_id) is contained within the source folder (id).
1084: * @exception IdUsedException
1085: * if a unique resource id cannot be found after some arbitrary number of attempts (@see MAXIMUM_ATTEMPTS_FOR_UNIQUENESS).
1086: * @exception ServerOverloadException
1087: * if the server is configured to write the resource body to the filesystem and the save fails.
1088: */
1089: public String copyIntoFolder(String id, String folder_id)
1090: throws PermissionException, IdUnusedException,
1091: TypeException, InUseException, OverQuotaException,
1092: IdUsedException, ServerOverloadException,
1093: InconsistentException, IdLengthException,
1094: IdUniquenessException;
1095:
1096: /**
1097: * Move a resource or collection to a (different) folder. This may be accomplished by renaming the resource or by recursively renaming the collection and all enclosed members (no matter how deep) to effectively change their locations. Alternatively,
1098: * it may be accomplished by copying the resource and recursively copying collections from their existing collection to the new collection and ultimately deleting the original resource(s) and/or collections(s).
1099: *
1100: * @param id
1101: * The id of the resource or collection to be moved.
1102: * @param folder_id
1103: * The id of the folder to which the resource should be moved.
1104: * @return The full id of the resource after the move is completed.
1105: * @exception PermissionException
1106: * if the user does not have permissions to read a containing collection, or to remove this resource.
1107: * @exception IdUnusedException
1108: * if the resource id is not found.
1109: * @exception TypeException
1110: * if the resource is a collection.
1111: * @exception InUseException
1112: * if the resource is locked by someone else.
1113: * @exception InconsistentException
1114: * if the containing collection does not exist.
1115: * @exception InconsistentException
1116: * if the destination folder (folder_id) is contained within the source folder (id).
1117: * @exception IdUsedException
1118: * if a unique resource id cannot be found after some arbitrary number of attempts (@see MAXIMUM_ATTEMPTS_FOR_UNIQUENESS).
1119: * @exception ServerOverloadException
1120: * if the server is configured to write the resource body to the filesystem and the save fails.
1121: */
1122: public String moveIntoFolder(String id, String folder_id)
1123: throws PermissionException, IdUnusedException,
1124: TypeException, InUseException, OverQuotaException,
1125: IdUsedException, InconsistentException,
1126: ServerOverloadException;
1127:
1128: /**
1129: * Commit the changes made, and release the lock. The Object is disabled, and not to be used after this call.
1130: *
1131: * @param edit
1132: * The ContentResourceEdit object to commit.
1133: * @exception OverQuotaException
1134: * if this would result in being over quota (the edit is then cancled).
1135: * @exception ServerOverloadException
1136: * if the server is configured to write the resource body to the filesystem and the save fails.
1137: */
1138: public void commitResource(ContentResourceEdit edit)
1139: throws OverQuotaException, ServerOverloadException;
1140:
1141: /**
1142: * Commit the changes made, and release the lock. The Object is disabled, and not to be used after this call.
1143: *
1144: * @param edit
1145: * The ContentResourceEdit object to commit.
1146: * @param priority
1147: * The notification priority of this commit.
1148: * @exception OverQuotaException
1149: * if this would result in being over quota (the edit is then cancled).
1150: * @exception ServerOverloadException
1151: * if the server is configured to write the resource body to the filesystem and the save fails.
1152: */
1153: public void commitResource(ContentResourceEdit edit, int priority)
1154: throws OverQuotaException, ServerOverloadException;
1155:
1156: /**
1157: * Cancel the changes made object, and release the lock. The Object is disabled, and not to be used after this call.
1158: *
1159: * @param edit
1160: * The ContentResourceEdit object to commit.
1161: */
1162: public void cancelResource(ContentResourceEdit edit);
1163:
1164: /** %%% copy, move * */
1165:
1166: /**
1167: * check permissions for getProperties().
1168: *
1169: * @param id
1170: * The id of the new resource.
1171: * @return true if the user is allowed to getProperties(id), false if not.
1172: */
1173: public boolean allowGetProperties(String id);
1174:
1175: /**
1176: * Access the properties of a resource with this resource id, either collection or resource.
1177: *
1178: * @param id
1179: * The id of the resource.
1180: * @exception PermissionException
1181: * if the user does not have permissions to read properties on this object or read through containing collections.
1182: * @exception IdUnusedException
1183: * if the resource id is not found.
1184: * @return the ResourceProperties object for this resource.
1185: */
1186: public ResourceProperties getProperties(String id)
1187: throws PermissionException, IdUnusedException;
1188:
1189: /**
1190: * check permissions for addProperty().
1191: *
1192: * @param id
1193: * The id of the new resource.
1194: * @return true if the user is allowed to addProperty(id), false if not.
1195: */
1196: public boolean allowAddProperty(String id);
1197:
1198: /**
1199: * Add / update a property for a collection or resource.
1200: *
1201: * @param id
1202: * The id of the resource.
1203: * @param name
1204: * The properties name to add or update
1205: * @param value
1206: * The new value for the property.
1207: * @exception PermissionException
1208: * if the user does not have premissions to write properties on this object or read through containing collections.
1209: * @exception IdUnusedException
1210: * if the resource id is not found.
1211: * @exception TypeException
1212: * if any property requested cannot be set (it may be live).
1213: * @exception InUseException
1214: * if the resource is locked by someone else.
1215: * @exception ServerOverloadException
1216: * if the server is configured to write the resource body to the filesystem and the save fails.
1217: * @return the ResourceProperties object for this resource.
1218: */
1219: public ResourceProperties addProperty(String id, String name,
1220: String value) throws PermissionException,
1221: IdUnusedException, TypeException, InUseException,
1222: ServerOverloadException;
1223:
1224: /**
1225: * check permissions for removeProperty().
1226: *
1227: * @param id
1228: * The id of the new resource.
1229: * @return true if the user is allowed to removeProperty(id), false if not.
1230: */
1231: public boolean allowRemoveProperty(String id);
1232:
1233: /**
1234: * Remove a property from a collection or resource.
1235: *
1236: * @param id
1237: * The id of the resource.
1238: * @param name
1239: * The property name to be removed from the resource.
1240: * @exception PermissionException
1241: * if the user does not have premissions to write properties on this object or read through containing collections.
1242: * @exception IdUnusedException
1243: * if the resource id is not found.
1244: * @exception TypeException
1245: * if the property named cannot be removed.
1246: * @exception InUseException
1247: * if the resource is locked by someone else.
1248: * @exception ServerOverloadException
1249: * if the server is configured to write the resource body to the filesystem and the save fails.
1250: * @return the ResourceProperties object for this resource.
1251: */
1252: public ResourceProperties removeProperty(String id, String name)
1253: throws PermissionException, IdUnusedException,
1254: TypeException, InUseException, ServerOverloadException;
1255:
1256: /**
1257: * Access an iterator (Strings) on the names of all properties used in the hosted resources and collections.
1258: *
1259: * @return An iterator (Strings) on the names of all properties used in the hosted resources and collections (may be empty).
1260: */
1261: // %%%public Iterator getPropertyNames();
1262: /**
1263: * Access the resource URL from a resource id.
1264: *
1265: * @param id
1266: * The resource id.
1267: * @return The resource URL.
1268: */
1269: public String getUrl(String id);
1270:
1271: /**
1272: * Access the alternate URL which can be used to access the entity.
1273: *
1274: * @param id
1275: * The resource id.
1276: * @param rootProperty
1277: * The name of the entity property whose value controls which alternate reference URL is requested. If null, the native 'raw' URL is requested.
1278: * @return The resource URL.
1279: */
1280: public String getUrl(String id, String rootProperty);
1281:
1282: /**
1283: * Access the internal reference from a resource id.
1284: *
1285: * @param id
1286: * The resource id.
1287: * @return The internal reference from a resource id.
1288: */
1289: public String getReference(String id);
1290:
1291: /**
1292: * Access the resource id of the collection which contains this collection or resource.
1293: *
1294: * @param id
1295: * The resource id (reference, or URL) of the ContentCollection or ContentResource
1296: * @return the resource id (reference, or URL, depending on the id parameter) of the collection which contains this resource.
1297: */
1298: public String getContainingCollectionId(String id);
1299:
1300: /**
1301: * Get the depth of the resource/collection object in the hireachy based on the given collection id
1302: *
1303: * @param resourceId
1304: * The Id of the resource/collection object to be tested
1305: * @param baseCollectionId
1306: * The Id of the collection as the relative root level
1307: * @return the integer value reflecting the relative hierarchy depth of the test resource/collection object based on the given base collection level
1308: */
1309: public int getDepth(String resourceId, String baseCollectionId);
1310:
1311: /**
1312: * Test if this id (reference, or URL) refers to the root collection.
1313: *
1314: * @param id
1315: * The resource id (reference, or URL) of a ContentCollection
1316: * @return true if this is the root collection
1317: */
1318: public boolean isRootCollection(String id);
1319:
1320: /**
1321: * Construct a stand-alone, not associated with any particular resource, ResourceProperties object.
1322: *
1323: * @return The new ResourceProperties object.
1324: */
1325: public ResourcePropertiesEdit newResourceProperties();
1326:
1327: /**
1328: * Return the collection id of the root collection for this site id.
1329: *
1330: * @param siteId
1331: * The site id.
1332: * @return The collection id which is the root collection for this site.
1333: */
1334: String getSiteCollection(String siteId);
1335:
1336: /**
1337: * Archive the specified list of resources.
1338: *
1339: * @param resources
1340: * A list of the resources to archive.
1341: * @param doc
1342: * The document to contain the xml.
1343: * @param stack
1344: * The stack of elements, the top of which will be the containing element of the "service.name" element.
1345: * @param archivePath
1346: * The path to the folder where we are writing auxilary files.
1347: * @return A log of status messages from the archive.
1348: */
1349: String archiveResources(List resources, Document doc, Stack stack,
1350: String archivePath);
1351:
1352: /**
1353: * Gets all locks set on the resource with this local resource id.
1354: *
1355: * @param id
1356: * @return
1357: */
1358: Collection getLocks(String id);
1359:
1360: /**
1361: * Locks an object (resource or collection) with specified local resource id. Initially, the WebDAV concepts of expiration, exclusive vs shared, and inheritable are not supported; instead, all locks are exclusive. Programmatically created locks may be
1362: * designated as "system" locks, in which case, users may not remove them via WebDAV lock management tools. Since only exclusive locks are permitted, a user can only lock a resource if it is not already locked; however, multiple system locks can be
1363: * put in place, because system locks imply that no user is permitted to change the resource.
1364: *
1365: * @param id
1366: * @param lockId
1367: * @param subject -
1368: * the reason for this lock e.g. "being graded"
1369: * @param system -
1370: * when true, it is not possible for a user to remove this lock
1371: */
1372: public void lockObject(String id, String lockId, String subject,
1373: boolean system /* Date expiration , boolean exclusive, boolean inheritable */);
1374:
1375: /**
1376: * Removes lock with given Id from object (resource or collection) specified by this local resource id. Note that other locks could exist, so it does not necessarily fully unlock the object.
1377: *
1378: * @param id
1379: * @param lockId
1380: */
1381: public void removeLock(String id, String lockId);
1382:
1383: /**
1384: * Convenience method to determine whether any locks exist for the Resource or Collection with the given local resource id
1385: *
1386: * @param id
1387: * @return true when there are one or more locks on the given id
1388: */
1389: public boolean isLocked(String id);
1390:
1391: /**
1392: * Returns true if this Collection or any of its contents has a lock. It is likely much more efficient than recursively iterating through all of the contained resources.
1393: *
1394: * @param id
1395: * @return
1396: */
1397: public boolean containsLockedNode(String id);
1398:
1399: /**
1400: * Convenience method that permanently removes any lock associated with qualifier
1401: *
1402: * @param id
1403: */
1404: public void removeAllLocks(String id);
1405:
1406: /**
1407: * Does this resource support public view?
1408: *
1409: * @param id
1410: * The resource id to check.
1411: * @return true if this resource supports public view, false if not.
1412: */
1413: public boolean isPubView(String id);
1414:
1415: /**
1416: * Does this resource inherit public view by having it set in a containing folder (not counting it's own setting)?
1417: *
1418: * @param id
1419: * The resource id to check.
1420: * @return true if this resource inherits public view, false if not.
1421: */
1422: public boolean isInheritingPubView(String id);
1423:
1424: /**
1425: * Set this resource or collection to the pubview setting.
1426: *
1427: * @param id
1428: * The resource or collection id.
1429: * @param pubview
1430: * The desired public view setting.
1431: */
1432: public void setPubView(String id, boolean pubview);
1433:
1434: /**
1435: * Find the resources this user has read access to from all worksites of the appropriate type.
1436: *
1437: * @param type
1438: * this is the ResourceProperties.PROP_STRUCTOBJ_TYPE for stuctured objects or ResourceProperties.FILE_TYPE for file resources or null for all resources.
1439: * @param primaryMimeType
1440: * The primary mime type (ie. the "text" of "text/xml") This may be null to include all resources
1441: * @param subMimeType
1442: * The sub type (ie, the "xml" of "text/xml") This may be null to include all resources of the primary mime type if specified.
1443: * @return List of ContentResource objects that match the search criteria
1444: */
1445: public List findResources(String type, String primaryMimeType,
1446: String subMimeType);
1447:
1448: /**
1449: * Return a map of Worksite collections roots that the user has access to.
1450: *
1451: * @return Map of worksite resource root id (String) to worksite title (String)
1452: */
1453: public Map getCollectionMap();
1454:
1455: /**
1456: * Eliminate from the collection any duplicates as well as any items that are contained within another item whose resource-id is in the collection.
1457: *
1458: * @param resourceIds
1459: * A collection of strings (possibly empty) identifying items and/or collections.
1460: */
1461: public void eliminateDuplicates(Collection resourceIds);
1462:
1463: /**
1464: * Create the current site's dropbox collection and one for each qualified user that the current user can make.
1465: */
1466: public void createDropboxCollection();
1467:
1468: /**
1469: * Create the site's dropbox collection and one for each qualified user that the current user can make.
1470: *
1471: * @param siteId
1472: * the Site id.
1473: */
1474: public void createDropboxCollection(String siteId);
1475:
1476: /**
1477: * Access the default dropbox collection id for the current request.<br />
1478: * If the current user is a dropbox maintainer for the current site, return the site's dropbox area.<br />
1479: * Otherwis return the current user's collection within the site's dropbox.
1480: *
1481: * @return The default dropbox collection id for the current request.
1482: */
1483: public String getDropboxCollection();
1484:
1485: /**
1486: * Create an individual dropbox collection for the current user if the site-level dropbox exists
1487: * and the current user has EVENT_DROPBOX_OWN permission for the site.
1488: *
1489: * @param siteId
1490: * the Site id.
1491: */
1492: public void createIndividualDropbox(String siteId);
1493:
1494: /**
1495: * Access the default dropbox collection id for the current request.<br />
1496: * If the current user is a dropbox maintainer for the current site, return the site's dropbox area.<br />
1497: * Otherwis return the current user's collection within the site's dropbox.
1498: *
1499: * @param siteId
1500: * The site id.
1501: * @return The default dropbox collection id for the site.
1502: */
1503: public String getDropboxCollection(String siteId);
1504:
1505: /**
1506: * Determine whether the default dropbox collection id for this user in this site is the site's entire dropbox collection or just the current user's collection within the site's dropbox.
1507: *
1508: * @return True if user sees all dropboxes in the site, false otherwise.
1509: */
1510: public boolean isDropboxMaintainer();
1511:
1512: /**
1513: * Determine whether the default dropbox collection id for this user in some site is the site's entire dropbox collection or just the current user's collection within the site's dropbox.
1514: *
1515: * @return True if user sees all dropboxes in the site, false otherwise.
1516: */
1517: public boolean isDropboxMaintainer(String siteId);
1518:
1519: /**
1520: * Access the default dropbox collection display name for the current request. If the current user has permission to modify the site's dropbox collection, this is returned. Otherwise, the current user's collection within the site's dropbox is
1521: * returned.
1522: *
1523: * @return The default dropbox collection display name for the current request.
1524: */
1525: public String getDropboxDisplayName();
1526:
1527: /**
1528: * Access the default dropbox collection display name for the site. If the current user has permission to modify the site's dropbox collection, this is returned. Otherwise, the current user's collection within the site's dropbox is returned.
1529: *
1530: * @param siteId
1531: * the Site id.
1532: * @return The default dropbox collection display name for the site.
1533: */
1534: public String getDropboxDisplayName(String siteId);
1535:
1536: /**
1537: * Check whether an id would identify an entity in a dropbox. Does not determine existence of the entity,
1538: * just whether its id indicates it is a dropbox or contained within a dropbox.
1539: * @return true if the entity is a dropbox or in a dropbox, false otherwise.
1540: */
1541: public boolean isInDropbox(String entityId);
1542:
1543: /**
1544: * Construct a content hosting comparator.
1545: *
1546: * @param property
1547: * The property name used for the sort.
1548: * @param asc
1549: * true if the sort is to be ascending (false for descending).
1550: */
1551: public Comparator newContentHostingComparator(String property,
1552: boolean ascending);
1553:
1554: /**
1555: * Access a collection (Group) of groups to which this user has access and whose members have "content.read" permission in the collection.
1556: * In effect, this method returns a collection that identifies groups that are defined for the collection (locally or inherited) that
1557: * this user can access. If access to the collection is determined by group-membership, the return is limited to groups that have
1558: * access to the specified collection. If access is not defined by groups (i.e. it is "site" access), the return includes all groups
1559: * defined in the site for which this user has read permission.
1560: *
1561: *
1562: * @param collectionId
1563: * The id for the collection.
1564: */
1565: public Collection getGroupsWithReadAccess(String collectionId);
1566:
1567: /**
1568: * Access a collection (Group) of groups to which this user has access and whose members have "content.new" permission in the collection.
1569: * In effect, this method returns a collection that identifies groups that are defined for the collection (locally or inherited) in which
1570: * this user has permission to add content entities. If access to the collection is determined by group-membership, the return is limited
1571: * to groups that have "add" permission in the specified collection. If access is not defined by groups (i.e. it is "site" access), the return
1572: * includes all groups defined in the site for which this user has add permission in this collection.
1573: *
1574: * @param collectionId
1575: * The id for the collection.
1576: */
1577: public Collection getGroupsWithAddPermission(String collectionId);
1578:
1579: /**
1580: * Access a collection (Group) of groups to which this user has access and whose members have "content.delete" permission in the collection.
1581: * In effect, this method returns a collection that identifies groups that are defined for the collection (locally or inherited) in which
1582: * this user has permission to remove content entities. If access to the collection is determined by group-membership, the return is limited
1583: * to groups that have "remove" permission in the specified collection. If access is not defined by groups (i.e. it is "site" access), the return
1584: * includes all groups defined in the site for which this user has remove permission in this collection.
1585: *
1586: * @param collectionId
1587: * The id for the collection.
1588: */
1589: public Collection getGroupsWithRemovePermission(String collectionId);
1590:
1591: /**
1592: * Access the shortRefs configuration. Short refs allow resource URLs without full prefix (may have "~" instead of /user/, or be missing /group/).
1593: *
1594: * @return true if shortRefs is enabled, false if not.
1595: */
1596: public boolean isShortRefs();
1597:
1598: /**
1599: * Access flag indicating whether entities can be hidden (scheduled or otherwise).
1600: * @return true if the availability features are enabled, false otherwise.
1601: */
1602: public boolean isAvailabilityEnabled();
1603:
1604: /**
1605: * Determine whether an entity is available to this user at this time, taking into account whether the item is hidden and the user's
1606: * status with respect to viewing hidden entities in this context.
1607: * @param entityId
1608: * @return true if the item is not hidden or it's hidden but the user has permissions to view hidden items in this context (site? folder? group?),
1609: * and false otherwise.
1610: */
1611: public boolean isAvailable(String entityId);
1612:
1613: /**
1614: * Access flag indicating whether sorting by "priority" is enabled.
1615: * @return true if the custom sort by priority is enabled, false otherwise.
1616: */
1617: public boolean isSortByPriorityEnabled();
1618:
1619: /**
1620: * Access flag indicating whether the ResourceTypeRegistry is being used
1621: * @return
1622: */
1623: public boolean usingResourceTypeRegistry();
1624:
1625: /**
1626: * Determine whether the entityId parameter identifies a collection (as opposed to a resource).
1627: * This method does not necessarily verify that a ContentEntity with this id exists.
1628: * It merely determines whether the id could identify a collection.
1629: * @param entityId
1630: * @return true if the entityId could identify a collection, false otherwise.
1631: */
1632: public boolean isCollection(String entityId);
1633:
1634: /**
1635: * Attempt to create a new resource in a particular collection. Ideally, this method will create
1636: * a new resource in the collection identified by the first parameter, collectionId, with a name
1637: * formed by concatenating the basename and the extension. If the extension is not null or empty
1638: * and does not start with a period ('.'), a period will be prepended to the extension. If the name
1639: * formed by concatenating the basename and the extension, some number of attempts may be made to
1640: * find a unique name for the resource in the collection by adding a dash ('-') and a number to the
1641: * basename. The fourth parameter, "maximum_tries", will determine the number of attempts to find
1642: * a unique name for the resource in the collection. The numbers appended to the basename will start
1643: * with '1' and increase by 1 until a unique name is found or the maximum value is reached.
1644: *
1645: * @param collectionId
1646: * @param basename
1647: * @param extension
1648: * @param maximum_tries
1649: * @exception PermissionException
1650: * if the user does not have permission to add a resource to the containing collection.
1651: * @exception IdUnusedException
1652: * if the collectionId does not identify an existing collection.
1653: * @exception IdUniquenessException
1654: * if a unique resource id cannot be found before the limit on the number of attempts is reached.
1655: * @exception IdLengthException
1656: * if the resource id exceeds the maximum number of characters for a valid resource id.
1657: * @exception IdInvalidException
1658: * if the resource id is invalid.
1659: * @exception InconsistentException
1660: * if the containing collection does not exist.
1661: * @exception OverQuotaException
1662: * if this would result in being over quota.
1663: * @exception ServerOverloadException
1664: * if the server is configured to write the resource body to the filesystem and the save fails.
1665: * @return
1666: */
1667: public ContentResourceEdit addResource(String collectionId,
1668: String basename, String extension, int maximum_tries)
1669: throws PermissionException, IdUniquenessException,
1670: IdLengthException, IdInvalidException, IdUnusedException,
1671: OverQuotaException, ServerOverloadException;
1672:
1673: /**
1674: * @param collectionId
1675: * @param name
1676: * @return
1677: * @exception PermissionException
1678: * if the user does not have permission to add a resource to the containing collection.
1679: * @exception TypeException
1680: * if the collectionId is not in the form to identify a collection.
1681: * @exception IdUnusedException
1682: * if the collectionId does not identify an existing collection.
1683: * @exception IdUnusedException
1684: * if the collection id for the proposed name already exists in this collection.
1685: * @exception IdLengthException
1686: * if the new collection id exceeds the maximum number of characters for a valid collection id.
1687: * @exception IdInvalidException
1688: * if the resource id is invalid.
1689: */
1690: public ContentCollectionEdit addCollection(String collectionId,
1691: String name) throws PermissionException, IdUnusedException,
1692: IdUsedException, IdLengthException, IdInvalidException,
1693: TypeException;
1694:
1695: /**
1696: * gets the quota for a site collection or for a user's my workspace collection
1697: *
1698: * @param collection the collection on which to test for a quota. this can be the collection for a site
1699: * or a user's workspace collection
1700: * @return the quota in kb
1701: */
1702: public long getQuota(
1703: org.sakaiproject.content.api.ContentCollection collection);
1704:
1705: }
|