0001: /*
0002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
0003: */
0004: package javax.jcr;
0005:
0006: import javax.jcr.lock.Lock;
0007: import javax.jcr.lock.LockException;
0008: import javax.jcr.nodetype.*;
0009: import javax.jcr.version.Version;
0010: import javax.jcr.version.VersionException;
0011: import javax.jcr.version.VersionHistory;
0012: import java.io.InputStream;
0013: import java.util.Calendar;
0014: import java.math.BigDecimal;
0015:
0016: /**
0017: * The <code>Node</code> interface represents a node in the hierarchy that
0018: * makes up the repository.
0019: */
0020: public interface Node extends Item {
0021:
0022: /**
0023: * Creates a new node at <code>relPath</code>. The new node will only be
0024: * persisted on <code>save()</code> if it meets the constraint
0025: * criteria of the parent node's node type.
0026: * <p/>
0027: * In order to save a newly added node, <code>save</code> must be called
0028: * either on the <code>Session</code>, or on the new node's parent or higher-order
0029: * ancestor (grandparent, etc.). An attempt to call <code>save</code> <i>only</i>
0030: * on the newly added node will throw a <code>RepositoryException</code>.
0031: * <p/>
0032: * In the context of this method the <code>relPath</code> provided must not
0033: * have an index on its final element. If it does then a <code>RepositoryException</code>
0034: * is thrown.
0035: * <p/>
0036: * Strictly speaking, the parameter is actually a relative path to the parent node
0037: * of the node to be added, appended with the name desired for the
0038: * new node (if the a node is being added directly below <code>this</code> node then only
0039: * the name need be specified). It does not specify a position within the child node
0040: * ordering. If ordering is supported by the node type of
0041: * the parent node then the new node is appended to the end of the
0042: * child node list.
0043: * <p/>
0044: * Since this signature does not allow explicit node type assignment, the new
0045: * node's primary node type will be determined (either immediately or on
0046: * <code>save</code>, depending on the implementation) by the child node definitions in
0047: * the node types of its parent.
0048: * <p/>
0049: * An <code>ItemExistsException</code> will be thrown either immediately (by this
0050: * method), or on <code>save</code>, if an item at the specified path already exists and
0051: * same-name siblings are not allowed. Implementations may differ on when
0052: * this validation is performed.
0053: * <p/>
0054: * A <code>PathNotFoundException</code> will be thrown
0055: * either immediately, or on <code>save</code>, if the specified path
0056: * implies intermediary nodes that do not exist. Implementations may differ
0057: * on when this validation is performed.
0058: * <p/>
0059: * A <code>ConstraintViolationException</code> will
0060: * be thrown either immediately or on <code>save</code> if adding the
0061: * node would violate a node type or implementation-specific constraint or
0062: * if an attempt is made to add a node as the child of a property.
0063: * Implementations may differ on when this validation is performed.
0064: * <p/>
0065: * A <code>VersionException</code> will be thrown either immediately or
0066: * on <code>save</code>, if the node to which the new child is being added is versionable
0067: * and checked-in or is non-versionable but its nearest versionable ancestor
0068: * is checked-in. Implementations may differ on when this validation is
0069: * performed.
0070: * <p/>
0071: * A <code>LockException</code> will be thrown either immediately (by this
0072: * method), or on <code>save</code>, if a lock prevents the addition of the node.
0073: * Implementations may differ on when this validation is performed.
0074: *
0075: * @param relPath The path of the new node to be created.
0076: *
0077: * @return The node that was added.
0078: *
0079: * @throws ItemExistsException if an item at the specified path already exists,
0080: * same-name siblings are not allowed and this implementation performs this
0081: * validation immediately instead of waiting until <code>save</code>.
0082: *
0083: * @throws PathNotFoundException if the specified path implies intermediary
0084: * <code>Node</code>s that do not exist or the last element of
0085: * <code>relPath</code> has an index, and this implementation performs this
0086: * validation immediately instead of waiting until <code>save</code>.
0087: *
0088: * @throws ConstraintViolationException if a node type or implementation-specific constraint
0089: * is violated or if an attempt is made to add a node as the child of a property and this
0090: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0091: *
0092: * @throws VersionException if the node to which the new child is being added is versionable and
0093: * checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this
0094: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0095: *
0096: * @throws LockException if a lock prevents the addition of the node and this
0097: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0098: *
0099: * @throws RepositoryException If the last element of <code>relPath</code> has an index or if another error occurs.
0100: */
0101: public Node addNode(String relPath) throws ItemExistsException,
0102: PathNotFoundException, VersionException,
0103: ConstraintViolationException, LockException,
0104: RepositoryException;
0105:
0106: /**
0107: * Creates a new node at <code>relPath</code> of the specified node type.
0108: * The same as <code>{@link #addNode(String relPath)}</code> except that the primary
0109: * node type of the new node is explictly specified.
0110: * <p/>
0111: * An <code>ItemExistsException</code> will be thrown either immediately (by this
0112: * method), or on <code>save</code>, if an item at the specified path already exists and
0113: * same-name siblings are not allowed. Implementations may differ on when
0114: * this validation is performed.
0115: * <p/>
0116: * A <code>PathNotFoundException</code> will be thrown
0117: * either immediately, or on <code>save</code>, if the specified path
0118: * implies intermediary nodes that do not exist. Implementations may differ
0119: * on when this validation is performed.
0120: * <p/>
0121: * A NoSuchNodeTypeException will be thrown either immediately
0122: * or on <code>save</code>, if the specified node type is not recognized.
0123: * Implementations may differ on when this validation is performed.
0124: * <p/>
0125: * A <code>ConstraintViolationException</code> will
0126: * be thrown either immediately or on <code>save</code> if adding the
0127: * node would violate a node type or implementation-specific constraint or
0128: * if an attempt is made to add a node as the child of a property.
0129: * Implementations may differ on when this validation is performed.
0130: * <p/>
0131: * A <code>VersionException</code> will be thrown either immediately or
0132: * on <code>save</code>, if the node to which the new child is being added is versionable
0133: * and checked-in or is non-versionable but its nearest versionable ancestor
0134: * is checked-in. Implementations may differ on when this validation is
0135: * performed.
0136: * <p/>
0137: * A <code>LockException</code> will be thrown either immediately (by this
0138: * method), or on <code>save</code>, if a lock prevents the addition of the node.
0139: * Implementations may differ on when this validation is performed.
0140: *
0141: * @param relPath the path of the new node to be created.
0142: *
0143: * @param primaryNodeTypeName The name of the primary node type of the new node.
0144: *
0145: * @return the node that was added.
0146: *
0147: * @throws ItemExistsException if an item at the specified path already exists,
0148: * same-name siblings are not allowed and this implementation performs this
0149: * validation immediately instead of waiting until <code>save</code>.
0150: *
0151: * @throws PathNotFoundException if the specified path implies intermediary
0152: * <code>Node</code>s that do not exist or the last element of
0153: * <code>relPath</code> has an index, and this implementation performs this
0154: * validation immediately instead of waiting until <code>save</code>.
0155: *
0156: * @throws NoSuchNodeTypeException if the specified node type is not recognized and this
0157: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0158: *
0159: * @throws ConstraintViolationException if a node type or implementation-specific constraint
0160: * is violated or if an attempt is made to add a node as the child of a property and this
0161: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0162: *
0163: * @throws VersionException if the node to which the new child is being added is versionable and
0164: * checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this
0165: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0166: *
0167: * @throws LockException if a lock prevents the addition of the node and this
0168: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0169: *
0170: * @throws RepositoryException if the last element of <code>relPath</code> has an index or if
0171: * another error occurs.
0172: */
0173: public Node addNode(String relPath, String primaryNodeTypeName)
0174: throws ItemExistsException, PathNotFoundException,
0175: NoSuchNodeTypeException, LockException, VersionException,
0176: ConstraintViolationException, RepositoryException;
0177:
0178: /**
0179: * If this node supports child node ordering, this method inserts the child node at
0180: * <code>srcChildRelPath</code> before its sibling, the child node at <code>destChildRelPath</code>,
0181: * in the child node list.
0182: * <p/>
0183: * To place the node <code>srcChildRelPath</code> at the end of the list, a <code>destChildRelPath</code>
0184: * of <code>null</code> is used.
0185: * <p/>
0186: * Note that (apart from the case where <code>destChildRelPath</code> is <code>null</code>) both of these
0187: * arguments must be relative paths of depth one, in other words they are the names of the child nodes,
0188: * possibly suffixed with an index.
0189: * <p/>
0190: * If <code>srcChildRelPath</code> and <code>destChildRelPath</code> are the same, then no change is made.
0191: * <p/>
0192: * Changes to ordering of child nodes are persisted on <code>save</code> of the parent node. But, if this node
0193: * does not support child node ordering, then a <code>UnsupportedRepositoryOperationException</code>
0194: * thrown.
0195: * <p/>
0196: * If <code>srcChildRelPath</code> is not the relative path to a child node of this node then an
0197: * <code>ItemNotFoundException</code> is thrown.
0198: * <p/>
0199: * If <code>destChildRelPath</code> is neither the relative path to a child node of this node nor
0200: * <code>null</code>, then an <code>ItemNotFoundException</code> is also thrown.
0201: * <p/>
0202: * A <code>ConstraintViolationException</code> will
0203: * be thrown either immediately or on <code>save</code> if this operation would
0204: * violate a node type or implementation-specific constraint.
0205: * Implementations may differ on when this validation is performed.
0206: * <p/>
0207: * A <code>VersionException</code> will be thrown either immediately or
0208: * on <code>save</code>, if this node is versionable
0209: * and checked-in or is non-versionable but its nearest versionable ancestor
0210: * is checked-in. Implementations may differ on when this validation is
0211: * performed.
0212: * <p/>
0213: * A <code>LockException</code> will be thrown either immediately (by this
0214: * method), or on <code>save</code>, if a lock prevents the re-ordering.
0215: * Implementations may differ on when this validation is performed.
0216: *
0217: * @param srcChildRelPath the relative path to the child node (that is, name plus possible index)
0218: * to be moved in the ordering
0219: * @param destChildRelPath the the relative path to the child node (that is, name plus possible index)
0220: * before which the node <code>srcChildRelPath</code> will be placed.
0221: * @throws UnsupportedRepositoryOperationException if ordering is not supported.
0222: * @throws ConstraintViolationException if an implementation-specific ordering restriction is violated
0223: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0224: * @throws ItemNotFoundException if either parameter is not the relative path of a child node of this node.
0225: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0226: * nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead
0227: * of waiting until <code>save</code>..
0228: * @throws LockException if a lock prevents the re-ordering and this implementation performs this validation
0229: * immediately instead of waiting until <code>save</code>..
0230: * @throws RepositoryException if another error occurs.
0231: */
0232: public void orderBefore(String srcChildRelPath,
0233: String destChildRelPath)
0234: throws UnsupportedRepositoryOperationException,
0235: VersionException, ConstraintViolationException,
0236: ItemNotFoundException, LockException, RepositoryException;
0237:
0238: /**
0239: * Sets the specified (single-value) property of this node to the specified
0240: * <code>value</code>. If the property does not yet exist, it is created.
0241: * The property type of the property will be that specified by the node type
0242: * of this node.
0243: * <p/>
0244: * If, based on the <code>name</code> and <code>value</code> passed, there
0245: * is more than one property definition that applies, the repository chooses
0246: * one definition according to some implementation-specific criteria. Once
0247: * property with name <code>P</code> has been created, the behavior of a
0248: * subsequent <code>setProperty(P,V)</code> may differ across implementations.
0249: * Some repositories may allow <code>P</code> to be dynamically re-bound to
0250: * a different property definition (based for example, on the new value being
0251: * of a different type than the original value) while other repositories may
0252: * not allow such dynamic re-binding.
0253: * <p/>
0254: * If the property type of the supplied <code>Value</code> object is different
0255: * from that required, then a best-effort conversion is attempted. If the
0256: * conversion fails, a <code>ValueFormatException</code> is thrown. If another
0257: * error occurs, a <code>RepositoryException</code> is thrown.
0258: * <p/>
0259: * If the node type of this node does not indicate a specific property
0260: * type, then the property type of the supplied <code>Value</code> object
0261: * is used and if the property already exists it assumes both the new value
0262: * and new property type.
0263: * <p/>
0264: * If the property is multi-valued, a <code>ValueFormatException</code>
0265: * is thrown.
0266: * <p/>
0267: * Passing a <code>null</code> as the second parameter removes the property.
0268: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
0269: * object itself. For example, <code>N.setProperty("P", (Value)null)</code> would remove
0270: * property called <code>"P"</code> of the node in <code>N</code>.
0271: * <p/>
0272: * To save the addition or removal of a property, a <code>save</code> call must be
0273: * performed that includes the parent of the property in its scope, that is,
0274: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0275: * save a change to an existing property, a <code>save</code> call that includes that
0276: * property in its scope is required. This means that in addition to the
0277: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0278: * itself will also work.
0279: * <p/>
0280: * A <code>ConstraintViolationException</code> will
0281: * be thrown either immediately or on <code>save</code> if the change
0282: * would violate a node type or implementation-specific constraint.
0283: * Implementations may differ on when this validation is performed.
0284: * <p/>
0285: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0286: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0287: * checked-in. Implementations may differ on when this validation is performed.
0288: * <p/>
0289: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0290: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0291: *
0292: * @param name The name of a property of this node
0293: * @param value The value to be assigned
0294: * @return The updated <code>Property</code> object
0295: *
0296: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified
0297: * property or if the property already exists and is multi-valued.
0298: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0299: * nearest versionable ancestor is checked-in and this
0300: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0301: * @throws LockException if a lock prevents the setting of the property and this
0302: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0303: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0304: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0305: * @throws RepositoryException if another error occurs.
0306: */
0307: public Property setProperty(String name, Value value)
0308: throws ValueFormatException, VersionException,
0309: LockException, ConstraintViolationException,
0310: RepositoryException;
0311:
0312: /**
0313: * Sets the specified (single-value) property to the specified value.
0314: * If the property does not yet exist, it is created.
0315: * <p/>
0316: * The type of the new property is determined by the <code>type</code> parameter specified.
0317: * <p/>
0318: * If the property type of the supplied <code>Value</code> object is different from that
0319: * required, then a best-effort conversion is attempted. If the conversion fails, a
0320: * <code>ValueFormatException</code> is thrown.
0321: * <p/>
0322: * If the property is not single-valued then a <code>ValueFormatException</code> is also thrown.
0323: * <p/>
0324: * If the property already exists it assumes both the new value and the new property type.
0325: * <p/>
0326: * Passing a <code>null</code> as the second parameter removes the property.
0327: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
0328: * object itself. For example, <code>N.setProperty("P", (Value)null, type)</code>
0329: * would remove property called <code>"P"</code> of the node in <code>N</code>.
0330: * <p/>
0331: * To persist the addition or removal of a property, <code>save</code> must be called
0332: * on the <code>Session</code>, this <code>Node</code>, or an ancestor of this <code>Node</code>.
0333: * <p/>
0334: * To save the addition or removal of a property, a <code>save</code> call must be
0335: * performed that includes the parent of the property in its scope, that is,
0336: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0337: * save a change to an existing property, a <code>save</code> call that includes that
0338: * property in its scope is required. This means that in addition to the
0339: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0340: * itself will also work.
0341: * <p/>
0342: * A <code>ConstraintViolationException</code> will
0343: * be thrown either immediately or on <code>save</code> if the change
0344: * would violate a node type or implementation-specific constraint.
0345: * Implementations may differ on when this validation is performed.
0346: * <p/>
0347: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0348: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0349: * checked-in. Implementations may differ on when this validation is performed.
0350: * <p/>
0351: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0352: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0353: *
0354: * @param name the name of the property to be set.
0355: * @param value a <code>Value</code> object.
0356: * @param type the type of the property.
0357: *
0358: * @return the <code>Property</code> object set, or <code>null</code>
0359: * if this method was used to remove a property (by setting its value to <code>null</code>).
0360: *
0361: * @throws ValueFormatException if <code>value</code> cannot be converted to the specified type
0362: * or if the property already exists and is multi-valued.
0363: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0364: * nearest versionable ancestor is checked-in and this
0365: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0366: * @throws LockException if a lock prevents the setting of the property and this
0367: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0368: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0369: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0370: * @throws RepositoryException if another error occurs.
0371: */
0372: public Property setProperty(String name, Value value, int type)
0373: throws ValueFormatException, VersionException,
0374: LockException, ConstraintViolationException,
0375: RepositoryException;
0376:
0377: /**
0378: * Sets the specified (multi-value) property to the specified array of values.
0379: * If the property does not yet exist, it is created. Same as
0380: * {@link #setProperty(String name, Value value)} except that an array of
0381: * <code>Value</code> objects is assigned instead of a single <code>Value</code>.
0382: * <p/>
0383: * The property type of the property will be that specified by the node type of this node.
0384: * If the property type of the supplied <code>Value</code> objects is different from that
0385: * required, then a best-effort conversion is attempted. If the conversion fails, a
0386: * <code>ValueFormatException</code> is thrown.
0387: * <p/>
0388: * All <code>Value</code> objects in the array must be of the same type, otherwise a
0389: * <code>ValueFormatException</code> is thrown. If the property is not multi-valued
0390: * then a <code>ValueFormatException</code> is also thrown. If another error occurs,
0391: * a <code>RepositoryException</code> is thrown.
0392: * <p/>
0393: * If the node type of this node does not indicate a specific property type, then the
0394: * property type of the supplied <code>Value</code> objects is used and if the
0395: * property already exists it assumes both the new values and the new property type.
0396: * <p/>
0397: * Passing a <code>null</code> as the second parameter removes the property.
0398: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
0399: * object itself. For example, <code>N.setProperty("P", (Value[])null)</code>
0400: * would remove property called <code>"P"</code> of the node in <code>N</code>.
0401: * <p/>
0402: * Note that this is different from passing an array that contains <code>null</code>
0403: * elements. In such a case, the array is compacted by removing the <code>null</code>s.
0404: * The resulting set of values never contains nulls. However, the set may be empty:
0405: * <code>N.setProperty("P", new Value[]{null})</code> would set the property to
0406: * the empty set of values.
0407: * <p/>
0408: * To save the addition or removal of a property, a <code>save</code> call must be
0409: * performed that includes the parent of the property in its scope, that is,
0410: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0411: * save a change to an existing property, a <code>save</code> call that includes that
0412: * property in its scope is required. This means that in addition to the
0413: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0414: * itself will also work.
0415: * <p/>
0416: * A <code>ConstraintViolationException</code> will
0417: * be thrown either immediately or on <code>save</code> if the change
0418: * would violate a node type or implementation-specific constraint.
0419: * Implementations may differ on when this validation is performed.
0420: * <p/>
0421: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0422: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0423: * checked-in. Implementations may differ on when this validation is performed.
0424: * <p/>
0425: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0426: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0427: *
0428: * @param name the name of the property to be set.
0429: * @param values an array of <code>Value</code> objects.
0430: * @return the updated <code>Property</code> object.
0431: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
0432: * or if the property already exists and is not multi-valued.
0433: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0434: * nearest versionable ancestor is checked-in and this
0435: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0436: * @throws LockException if a lock prevents the setting of the property and this
0437: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0438: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0439: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0440: * @throws RepositoryException if another error occurs.
0441: */
0442: public Property setProperty(String name, Value[] values)
0443: throws ValueFormatException, VersionException,
0444: LockException, ConstraintViolationException,
0445: RepositoryException;
0446:
0447: /**
0448: * Sets the specified (multi-value) property to the specified array of values.
0449: * If the property does not yet exist, it is created. The type of the property
0450: * is determined by the <code>type</code> parameter specified.
0451: * <p/>
0452: * If the property type of the supplied <code>Value</code> objects is different from that
0453: * specified, then a best-effort conversion is attempted. If the conversion fails, a
0454: * <code>ValueFormatException</code> is thrown.
0455: * <p/>
0456: * If the property already exists it assumes both the new values and the new property type.
0457: * <p/>
0458: * All <code>Value</code> objects in the array must be of the same type, otherwise a
0459: * <code>ValueFormatException</code> is thrown. If the property is not multi-valued
0460: * then a <code>ValueFormatException</code> is also thrown. If another error occurs,
0461: * a <code>RepositoryException</code> is thrown.
0462: * <p/>
0463: * Passing a <code>null</code> as the second parameter removes the property.
0464: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
0465: * object itself. For example, <code>N.setProperty("P", (Value[])null, type)</code>
0466: * would remove property called <code>"P"</code> of the node in <code>N</code>.
0467: * <p/>
0468: * Note that this is different from passing an array that contains <code>null</code>
0469: * elements. In such a case, the array is compacted by removing the <code>null</code>s.
0470: * The resulting set of values never contains nulls. However, the set may be empty:
0471: * <code>N.setProperty("P", new Value[]{null}, type)</code> would set the property to
0472: * the empty set of values.
0473: * <p/>
0474: * To save the addition or removal of a property, a <code>save</code> call must be
0475: * performed that includes the parent of the property in its scope, that is,
0476: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0477: * save a change to an existing property, a <code>save</code> call that includes that
0478: * property in its scope is required. This means that in addition to the
0479: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0480: * itself will also work.
0481: * <p/>
0482: * A <code>ConstraintViolationException</code> will
0483: * be thrown either immediately or on <code>save</code> if the change
0484: * would violate a node type or implementation-specific constraint.
0485: * Implementations may differ on when this validation is performed.
0486: * <p/>
0487: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0488: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0489: * checked-in. Implementations may differ on when this validation is performed.
0490: * <p/>
0491: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0492: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0493: *
0494: * @param name the name of the property to be set.
0495: * @param values an array of <code>Value</code> objects.
0496: * @param type the type of the property.
0497: * @return the updated <code>Property</code> object.
0498: * @throws ValueFormatException if <code>value</code> cannot be converted to the specified type
0499: * or if the property already exists and is not multi-valued.
0500: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0501: * nearest versionable ancestor is checked-in and this
0502: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0503: * @throws LockException if a lock prevents the setting of the property and this
0504: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0505: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0506: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0507: * @throws RepositoryException if another error occurs.
0508: */
0509: public Property setProperty(String name, Value[] values, int type)
0510: throws ValueFormatException, VersionException,
0511: LockException, ConstraintViolationException,
0512: RepositoryException;
0513:
0514: /**
0515: * Sets the specified property to the specified array of values.
0516: * Same as {@link #setProperty(String name, Value[] values)}
0517: * except that the values are specified as <code>String</code>
0518: * objects instead of <code>Value</code> objects.
0519: *
0520: * @param name the name of the property to be set.
0521: * @param values an array of <code>Value</code> objects.
0522: * @return the updated <code>Property</code> object.
0523: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
0524: * or if the property already exists and is not multi-valued.
0525: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0526: * nearest versionable ancestor is checked-in and this
0527: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0528: * @throws LockException if a lock prevents the setting of the property and this
0529: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0530: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0531: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0532: * @throws RepositoryException if another error occurs.
0533: */
0534: public Property setProperty(String name, String[] values)
0535: throws ValueFormatException, VersionException,
0536: LockException, ConstraintViolationException,
0537: RepositoryException;
0538:
0539: /**
0540: * Sets the specified property to the specified array of values and to the specified type.
0541: * Same as {@link #setProperty(String name, Value[] values, int type)}
0542: * except that the values are specified as <code>String</code>
0543: * objects instead of <code>Value</code> objects.
0544: *
0545: * @param name the name of the property to be set.
0546: * @param values an array of <code>Value</code> objects.
0547: * @param type the type of the property.
0548: * @return the updated <code>Property</code> object.
0549: * @throws ValueFormatException if <code>value</code> cannot be converted to the specified type
0550: * or if the property already exists and is not multi-valued.
0551: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0552: * nearest versionable ancestor is checked-in and this
0553: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0554: * @throws LockException if a lock prevents the setting of the property and this
0555: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0556: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0557: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0558: * @throws RepositoryException if another error occurs.
0559: */
0560: public Property setProperty(String name, String[] values, int type)
0561: throws ValueFormatException, VersionException,
0562: LockException, ConstraintViolationException,
0563: RepositoryException;
0564:
0565: /**
0566: * Sets the specified property to the specified value.
0567: * If the property does not yet exist, it is created.
0568: * The property type of the property being set is determined
0569: * by the node type of <code>this</code> node (the one on which
0570: * this method is being called). If this is something other than
0571: * <code>PropertyType.STRING</code>, a best-effort conversion is attempted.
0572: * If the conversion fails, a <code>ValueFormatException</code> is
0573: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
0574: * also thrown. If another error occurs, a <code>RepositoryException</code>
0575: * is thrown.
0576: * <p/>
0577: * If the node type of <code>this</code> node does not
0578: * specify a particular property type for the property being set
0579: * then <code>PropertyType.STRING</code> is used and,
0580: * if the property already exists, it assumes both the new value
0581: * and type <code>PropertyType.STRING</code>.
0582: * <p/>
0583: * Passing a <code>null</code> as the second parameter removes the property.
0584: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
0585: * object itself. For example, <code>N.setProperty("P", (String)null)</code>
0586: * would remove property called <code>"P"</code> of the node in <code>N</code>.
0587: * <p/>
0588: * To save the addition or removal of a property, a <code>save</code> call must be
0589: * performed that includes the parent of the property in its scope, that is,
0590: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0591: * save a change to an existing property, a <code>save</code> call that includes that
0592: * property in its scope is required. This means that in addition to the
0593: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0594: * itself will also work.
0595: * <p/>
0596: * A <code>ConstraintViolationException</code> will
0597: * be thrown either immediately or on <code>save</code> if the change
0598: * would violate a node type or implementation-specific constraint.
0599: * Implementations may differ on when this validation is performed.
0600: * <p/>
0601: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0602: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0603: * checked-in. Implementations may differ on when this validation is performed.
0604: * <p/>
0605: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0606: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0607: *
0608: * @param name The name of a property of this node
0609: * @param value The value to assigned
0610: * @return The updated <code>Property</code> object
0611: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
0612: * or if the property already exists and is multi-valued.
0613: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0614: * nearest versionable ancestor is checked-in and this
0615: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0616: * @throws LockException if a lock prevents the setting of the property and this
0617: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0618: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0619: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0620: * @throws RepositoryException If another error occurs.
0621: */
0622: public Property setProperty(String name, String value)
0623: throws ValueFormatException, VersionException,
0624: LockException, ConstraintViolationException,
0625: RepositoryException;
0626:
0627: /**
0628: * Sets the specified (single-value) property to the specified value.
0629: * If the property does not yet exist, it is created.
0630: * <p/>
0631: * The type of the property is determined by the <code>type</code> parameter specified.
0632: * <p/>
0633: * If the property type specified is not <code>PropertyType.STRING</code>,
0634: * then a best-effort conversion is attempted. If the conversion fails, a
0635: * <code>ValueFormatException</code> is thrown.
0636: * <p/>
0637: * If the property is not single-valued then a <code>ValueFormatException</code> is also thrown.
0638: * <p/>
0639: * If the property already exists it assumes both the new value and the new property type.
0640: * <p/>
0641: * Passing a <code>null</code> as the second parameter removes the property.
0642: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
0643: * object itself. For example, <code>N.setProperty("P", (Value)null, type)</code>
0644: * would remove property called <code>"P"</code> of the node in <code>N</code>.
0645: * <p/>
0646: * To save the addition or removal of a property, a <code>save</code> call must be
0647: * performed that includes the parent of the property in its scope, that is,
0648: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0649: * save a change to an existing property, a <code>save</code> call that includes that
0650: * property in its scope is required. This means that in addition to the
0651: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0652: * itself will also work.
0653: * <p/>
0654: * A <code>ConstraintViolationException</code> will
0655: * be thrown either immediately or on <code>save</code> if the change
0656: * would violate a node type or implementation-specific constraint.
0657: * Implementations may differ on when this validation is performed.
0658: * <p/>
0659: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0660: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0661: * checked-in. Implementations may differ on when this validation is performed.
0662: * <p/>
0663: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0664: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0665: *
0666: * @param name the name of the property to be set.
0667: * @param value a <code>String</code> object.
0668: * @param type the type of the property.
0669: *
0670: * @return the <code>Property</code> object set, or <code>null</code>
0671: * if this method was used to remove a property (by setting its value to <code>null</code>).
0672: *
0673: * @throws ValueFormatException if <code>value</code> cannot be converted to the specified type
0674: * or if the property already exists and is multi-valued.
0675: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0676: * nearest versionable ancestor is checked-in and this
0677: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0678: * @throws LockException if a lock prevents the setting of the property and this
0679: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0680: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0681: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0682: * @throws RepositoryException if another error occurs.
0683: */
0684: public Property setProperty(String name, String value, int type)
0685: throws ValueFormatException, VersionException,
0686: LockException, ConstraintViolationException,
0687: RepositoryException;
0688:
0689: /**
0690: * Sets the specified property to the specified value.
0691: * If the property does not yet exist, it is created.
0692: * The property type of the property being set is determined
0693: * by the node type of <code>this</code> node (the one on which
0694: * this method is being called). If this is something other than
0695: * <code>PropertyType.BINARY</code>, a best-effort conversion is attempted.
0696: * If the conversion fails, a <code>ValueFormatException</code> is
0697: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
0698: * also thrown. If another error occurs, a <code>RepositoryException</code>
0699: * is thrown.
0700: * <p/>
0701: * If the node type of <code>this</code> node does not
0702: * specify a particular property type for the property being set
0703: * then <code>PropertyType.BINARY</code> is used and,
0704: * if the property already exists, it assumes both the new value
0705: * and type <code>PropertyType.BINARY</code>.
0706: * <p/>
0707: * Passing a <code>null</code> as the second parameter removes the property.
0708: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
0709: * object itself. For example, <code>N.setProperty("P", (InputStream)null)</code>
0710: * would remove property called <code>"P"</code> of the node in <code>N</code>.
0711: * <p/>
0712: * To save the addition or removal of a property, a <code>save</code> call must be
0713: * performed that includes the parent of the property in its scope, that is,
0714: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0715: * save a change to an existing property, a <code>save</code> call that includes that
0716: * property in its scope is required. This means that in addition to the
0717: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0718: * itself will also work.
0719: * <p/>
0720: * The passed stream is closed before this method returns either normally or
0721: * because of an exception.
0722: * <p/>
0723: * A <code>ConstraintViolationException</code> will
0724: * be thrown either immediately or on <code>save</code> if the change
0725: * would violate a node type or implementation-specific constraint.
0726: * Implementations may differ on when this validation is performed.
0727: * <p/>
0728: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0729: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0730: * checked-in. Implementations may differ on when this validation is performed.
0731: * <p/>
0732: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0733: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0734: *
0735: * @deprecated As of JCR 2.0, {@link #setProperty(String, Binary)} should
0736: * be used instead.
0737: *
0738: * @param name The name of a property of this node
0739: * @param value The value to assigned
0740: * @return The updated <code>Property</code> object
0741: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
0742: * or if the property already exists and is multi-valued.
0743: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0744: * nearest versionable ancestor is checked-in and this
0745: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0746: * @throws LockException if a lock prevents the setting of the property and this
0747: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0748: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0749: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0750: * @throws RepositoryException If another error occurs.
0751: */
0752: public Property setProperty(String name, InputStream value)
0753: throws ValueFormatException, VersionException,
0754: LockException, ConstraintViolationException,
0755: RepositoryException;
0756:
0757: /**
0758: * Sets the specified property to the specified value.
0759: * If the property does not yet exist, it is created.
0760: * The property type of the property being set is determined
0761: * by the node type of <code>this</code> node (the one on which
0762: * this method is being called). If this is something other than
0763: * <code>PropertyType.BINARY</code>, a best-effort conversion is attempted.
0764: * If the conversion fails, a <code>ValueFormatException</code> is
0765: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
0766: * also thrown. If another error occurs, a <code>RepositoryException</code>
0767: * is thrown.
0768: * <p/>
0769: * If the node type of <code>this</code> node does not
0770: * specify a particular property type for the property being set
0771: * then <code>PropertyType.BINARY</code> is used and,
0772: * if the property already exists, it assumes both the new value
0773: * and type <code>PropertyType.BINARY</code>.
0774: * <p/>
0775: * Passing a <code>null</code> as the second parameter removes the property.
0776: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
0777: * object itself. For example, <code>N.setProperty("P", (Binary)null)</code>
0778: * would remove property called <code>"P"</code> of the node in <code>N</code>.
0779: * <p/>
0780: * To save the addition or removal of a property, a <code>save</code> call must be
0781: * performed that includes the parent of the property in its scope, that is,
0782: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0783: * save a change to an existing property, a <code>save</code> call that includes that
0784: * property in its scope is required. This means that in addition to the
0785: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0786: * itself will also work.
0787: * <p/>
0788: * A <code>ConstraintViolationException</code> will
0789: * be thrown either immediately or on <code>save</code> if the change
0790: * would violate a node type or implementation-specific constraint.
0791: * Implementations may differ on when this validation is performed.
0792: * <p/>
0793: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0794: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0795: * checked-in. Implementations may differ on when this validation is performed.
0796: * <p/>
0797: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0798: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0799: *
0800: * @param name The name of a property of this node
0801: * @param value The value to assigned
0802: * @return The updated <code>Property</code> object
0803: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
0804: * or if the property already exists and is multi-valued.
0805: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0806: * nearest versionable ancestor is checked-in and this
0807: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0808: * @throws LockException if a lock prevents the setting of the property and this
0809: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0810: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0811: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0812: * @throws RepositoryException If another error occurs.
0813: * @since JCR 2.0
0814: */
0815: public Property setProperty(String name, Binary value)
0816: throws ValueFormatException, VersionException,
0817: LockException, ConstraintViolationException,
0818: RepositoryException;
0819:
0820: /**
0821: * Sets the specified property to the specified value.
0822: * If the property does not yet exist, it is created.
0823: * The property type of the property being set is determined
0824: * by the node type of <code>this</code> node (the one on which
0825: * this method is being called). If this is something other than
0826: * <code>PropertyType.BOOLEAN</code>, a best-effort conversion is attempted.
0827: * If the conversion fails, a <code>ValueFormatException</code> is
0828: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
0829: * also thrown. If another error occurs, a <code>RepositoryException</code>
0830: * is thrown.
0831: * <p/>
0832: * If the node type of <code>this</code> node does not
0833: * specify a particular property type for the property being set
0834: * then <code>PropertyType.BOOLEAN</code> is used and,
0835: * if the property already exists, it assumes both the new value
0836: * and type <code>PropertyType.BOOLEAN</code>.
0837: * <p/>
0838: * To save the addition or removal of a property, a <code>save</code> call must be
0839: * performed that includes the parent of the property in its scope, that is,
0840: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0841: * save a change to an existing property, a <code>save</code> call that includes that
0842: * property in its scope is required. This means that in addition to the
0843: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0844: * itself will also work.
0845: * <p/>
0846: * A <code>ConstraintViolationException</code> will
0847: * be thrown either immediately or on <code>save</code> if the change
0848: * would violate a node type or implementation-specific constraint.
0849: * Implementations may differ on when this validation is performed.
0850: * <p/>
0851: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0852: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0853: * checked-in. Implementations may differ on when this validation is performed.
0854: * <p/>
0855: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0856: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0857: *
0858: * @param name The name of a property of this node
0859: * @param value The value to assigned
0860: * @return The updated <code>Property</code> object
0861: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
0862: * or if the property already exists and is multi-valued.
0863: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0864: * nearest versionable ancestor is checked-in and this
0865: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0866: * @throws LockException if a lock prevents the setting of the property and this
0867: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0868: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0869: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0870: * @throws RepositoryException If another error occurs.
0871: */
0872: public Property setProperty(String name, boolean value)
0873: throws ValueFormatException, VersionException,
0874: LockException, ConstraintViolationException,
0875: RepositoryException;
0876:
0877: /**
0878: * Sets the specified property to the specified value.
0879: * If the property does not yet exist, it is created.
0880: * The property type of the property being set is determined
0881: * by the node type of <code>this</code> node (the one on which
0882: * this method is being called). If this is something other than
0883: * <code>PropertyType.DOUBLE</code>, a best-effort conversion is attempted.
0884: * If the conversion fails, a <code>ValueFormatException</code> is
0885: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
0886: * also thrown. If another error occurs, a <code>RepositoryException</code>
0887: * is thrown.
0888: * <p/>
0889: * If the node type of <code>this</code> node does not
0890: * specify a particular property type for the property being set
0891: * then <code>PropertyType.DOUBLE</code> is used and,
0892: * if the property already exists, it assumes both the new value
0893: * and type <code>PropertyType.DOUBLE</code>.
0894: * <p/>
0895: * To save the addition or removal of a property, a <code>save</code> call must be
0896: * performed that includes the parent of the property in its scope, that is,
0897: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0898: * save a change to an existing property, a <code>save</code> call that includes that
0899: * property in its scope is required. This means that in addition to the
0900: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0901: * itself will also work.
0902: * <p/>
0903: * A <code>ConstraintViolationException</code> will
0904: * be thrown either immediately or on <code>save</code> if the change
0905: * would violate a node type or implementation-specific constraint.
0906: * Implementations may differ on when this validation is performed.
0907: * <p/>
0908: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0909: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0910: * checked-in. Implementations may differ on when this validation is performed.
0911: * <p/>
0912: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0913: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0914: *
0915: * @param name The name of a property of this node
0916: * @param value The value to assigned
0917: * @return The updated <code>Property</code> object
0918: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
0919: * or if the property already exists and is multi-valued.
0920: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0921: * nearest versionable ancestor is checked-in and this
0922: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0923: * @throws LockException if a lock prevents the setting of the property and this
0924: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0925: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0926: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0927: * @throws RepositoryException If another error occurs.
0928: */
0929: public Property setProperty(String name, double value)
0930: throws ValueFormatException, VersionException,
0931: LockException, ConstraintViolationException,
0932: RepositoryException;
0933:
0934: /**
0935: * Sets the specified property to the specified value.
0936: * If the property does not yet exist, it is created.
0937: * The property type of the property being set is determined
0938: * by the node type of <code>this</code> node (the one on which
0939: * this method is being called). If this is something other than
0940: * <code>PropertyType.DECIMAL</code>, a best-effort conversion is attempted.
0941: * If the conversion fails, a <code>ValueFormatException</code> is
0942: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
0943: * also thrown. If another error occurs, a <code>RepositoryException</code>
0944: * is thrown.
0945: * <p/>
0946: * If the node type of <code>this</code> node does not
0947: * specify a particular property type for the property being set
0948: * then <code>PropertyType.DECIMAL</code> is used and,
0949: * if the property already exists, it assumes both the new value
0950: * and type <code>PropertyType.DECIMAL</code>.
0951: * <p/>
0952: * To save the addition or removal of a property, a <code>save</code> call must be
0953: * performed that includes the parent of the property in its scope, that is,
0954: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
0955: * save a change to an existing property, a <code>save</code> call that includes that
0956: * property in its scope is required. This means that in addition to the
0957: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
0958: * itself will also work.
0959: * <p/>
0960: * A <code>ConstraintViolationException</code> will
0961: * be thrown either immediately or on <code>save</code> if the change
0962: * would violate a node type or implementation-specific constraint.
0963: * Implementations may differ on when this validation is performed.
0964: * <p/>
0965: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
0966: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
0967: * checked-in. Implementations may differ on when this validation is performed.
0968: * <p/>
0969: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
0970: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
0971: *
0972: * @param name The name of a property of this node
0973: * @param value The value to assigned
0974: * @return The updated <code>Property</code> object
0975: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
0976: * or if the property already exists and is multi-valued.
0977: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
0978: * nearest versionable ancestor is checked-in and this
0979: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0980: * @throws LockException if a lock prevents the setting of the property and this
0981: * implementation performs this validation immediately instead of waiting until <code>save</code>.
0982: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
0983: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
0984: * @throws RepositoryException If another error occurs.
0985: * @since JCR 2.0
0986: */
0987: public Property setProperty(String name, BigDecimal value)
0988: throws ValueFormatException, VersionException,
0989: LockException, ConstraintViolationException,
0990: RepositoryException;
0991:
0992: /**
0993: * Sets the specified property to the specified value.
0994: * If the property does not yet exist, it is created.
0995: * The property type of the property being set is determined
0996: * by the node type of <code>this</code> node (the one on which
0997: * this method is being called). If this is something other than
0998: * <code>PropertyType.LONG</code>, a best-effort conversion is attempted.
0999: * If the conversion fails, a <code>ValueFormatException</code> is
1000: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
1001: * also thrown. If another error occurs, a <code>RepositoryException</code>
1002: * is thrown.
1003: * <p/>
1004: * If the node type of <code>this</code> node does not
1005: * specify a particular property type for the property being set
1006: * then <code>PropertyType.LONG</code> is used and,
1007: * if the property already exists, it assumes both the new value
1008: * and type <code>PropertyType.LONG</code>.
1009: * <p/>
1010: * To save the addition or removal of a property, a <code>save</code> call must be
1011: * performed that includes the parent of the property in its scope, that is,
1012: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
1013: * save a change to an existing property, a <code>save</code> call that includes that
1014: * property in its scope is required. This means that in addition to the
1015: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
1016: * itself will also work.
1017: * <p/>
1018: * A <code>ConstraintViolationException</code> will
1019: * be thrown either immediately or on <code>save</code> if the change
1020: * would violate a node type or implementation-specific constraint.
1021: * Implementations may differ on when this validation is performed.
1022: * <p/>
1023: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
1024: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
1025: * checked-in. Implementations may differ on when this validation is performed.
1026: * <p/>
1027: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
1028: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
1029: *
1030: * @param name The name of a property of this node
1031: * @param value The value to assigned
1032: * @return The updated <code>Property</code> object
1033: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
1034: * or if the property already exists and is multi-valued.
1035: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
1036: * nearest versionable ancestor is checked-in and this
1037: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1038: * @throws LockException if a lock prevents the setting of the property and this
1039: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1040: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
1041: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
1042: * @throws RepositoryException If another error occurs.
1043: */
1044: public Property setProperty(String name, long value)
1045: throws ValueFormatException, VersionException,
1046: LockException, ConstraintViolationException,
1047: RepositoryException;
1048:
1049: /**
1050: * Sets the specified property to the specified value.
1051: * If the property does not yet exist, it is created.
1052: * The property type of the property being set is determined
1053: * by the node type of <code>this</code> node (the one on which
1054: * this method is being called). If this is something other than
1055: * <code>PropertyType.DATE</code>, a best-effort conversion is attempted.
1056: * If the conversion fails, a <code>ValueFormatException</code> is
1057: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
1058: * also thrown. If another error occurs, a <code>RepositoryException</code>
1059: * is thrown.
1060: * <p/>
1061: * If the node type of <code>this</code> node does not
1062: * specify a particular property type for the property being set
1063: * then <code>PropertyType.DATE</code> is used and,
1064: * if the property already exists, it assumes both the new value
1065: * and type <code>PropertyType.DATE</code>.
1066: * <p/>
1067: * Passing a <code>null</code> as the second parameter removes the property.
1068: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
1069: * object itself. For example, <code>N.setProperty("P", (Calendar)null)</code>
1070: * would remove property called <code>"P"</code> of the node in <code>N</code>.
1071: * <p/>
1072: * To save the addition or removal of a property, a <code>save</code> call must be
1073: * performed that includes the parent of the property in its scope, that is,
1074: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
1075: * save a change to an existing property, a <code>save</code> call that includes that
1076: * property in its scope is required. This means that in addition to the
1077: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
1078: * itself will also work.
1079: * <p/>
1080: * A <code>ConstraintViolationException</code> will
1081: * be thrown either immediately or on <code>save</code> if the change
1082: * would violate a node type or implementation-specific constraint.
1083: * Implementations may differ on when this validation is performed.
1084: * <p/>
1085: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
1086: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
1087: * checked-in. Implementations may differ on when this validation is performed.
1088: * <p/>
1089: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
1090: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
1091: *
1092: * @param name The name of a property of this node
1093: * @param value The value to assigned
1094: * @return The updated <code>Property</code> object
1095: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
1096: * or if the property already exists and is multi-valued.
1097: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
1098: * nearest versionable ancestor is checked-in and this
1099: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1100: * @throws LockException if a lock prevents the setting of the property and this
1101: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1102: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
1103: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
1104: * @throws RepositoryException If another error occurs.
1105: */
1106: public Property setProperty(String name, Calendar value)
1107: throws ValueFormatException, VersionException,
1108: LockException, ConstraintViolationException,
1109: RepositoryException;
1110:
1111: /**
1112: * Sets the specified (<code>REFERENCE</code>)property
1113: * to refer to the specified <code>Node</code>.
1114: * If the property does not yet exist, it is created.
1115: * The property type of the property being set is determined
1116: * by the node type of <code>this</code> node (the one on which
1117: * this method is being called). If the property type of this property is
1118: * something other than either <code>PropertyType.REFERENCE</code> or undefined
1119: * then a <code>ValueFormatException</code> is
1120: * thrown. If the property is multi-valued, a <code>ValueFormatException</code> is
1121: * also thrown. If another error occurs, a <code>RepositoryException</code>
1122: * is thrown.
1123: * <p/>
1124: * If the node type of <code>this</code> node does not
1125: * specify a particular property type for the property being set
1126: * then <code>PropertyType.REFERENCE</code> is used and,
1127: * if the property already exists, it assumes both the new value
1128: * and type <code>PropertyType.REFERENCE</code>.
1129: * <p/>
1130: * Passing a <code>null</code> as the second parameter removes the property.
1131: * It is equivalent to calling <code>remove</code> on the <code>Property</code>
1132: * object itself. For example, <code>N.setProperty("P", (Node)null)</code>
1133: * would remove property called <code>"P"</code> of the node in <code>N</code>.
1134: * <p/>
1135: * To save the addition or removal of a property, a <code>save</code> call must be
1136: * performed that includes the parent of the property in its scope, that is,
1137: * a <code>save</code> on either the session, this node, or an ancestor of this node. To
1138: * save a change to an existing property, a <code>save</code> call that includes that
1139: * property in its scope is required. This means that in addition to the
1140: * above-mentioned <code>save</code> options, a <code>save</code> on the changed property
1141: * itself will also work.
1142: * <p/>
1143: * A <code>ConstraintViolationException</code> will
1144: * be thrown either immediately or on <code>save</code> if the change
1145: * would violate a node type or implementation-specific constraint.
1146: * Implementations may differ on when this validation is performed.
1147: * <p/>
1148: * A <code>VersionException</code> will be thrown either immediately or on <code>save</code>
1149: * if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is
1150: * checked-in. Implementations may differ on when this validation is performed.
1151: * <p/>
1152: * A <code>LockException</code> will be thrown either immediately or on <code>save</code>
1153: * if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.
1154: *
1155: * @param name The name of a property of this node
1156: * @param value The value to assigned
1157: * @return The updated <code>Property</code> object
1158: * @throws ValueFormatException if <code>value</code> cannot be converted to the type of the specified property
1159: * or if the property already exists and is multi-valued.
1160: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
1161: * nearest versionable ancestor is checked-in and this
1162: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1163: * @throws LockException if a lock prevents the setting of the property and this
1164: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1165: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
1166: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
1167: * @throws RepositoryException If another error occurs.
1168: */
1169: public Property setProperty(String name, Node value)
1170: throws ValueFormatException, VersionException,
1171: LockException, ConstraintViolationException,
1172: RepositoryException;
1173:
1174: /**
1175: * Returns the node at <code>relPath</code> relative to this node.
1176: * <p/>
1177: * If <code>relPath</code> contains a path element that refers to a node with same-name sibling nodes without
1178: * explicitly including an index using the array-style notation (<code>[x]</code>), then the index [1] is assumed
1179: * (indexing of same name siblings begins at 1, not 0, in order to preserve compatibility with XPath).
1180: * <p/>
1181: * Within the scope of a single <code>Session</code> object, if a <code>Node</code> object has been acquired,
1182: * any subsequent call of <code>getNode</code> reacquiring the same node must return a <code>Node</code> object reflecting
1183: * the same state as the earlier <code>Node</code> object. Whether this object is actually the same <code>Node</code>
1184: * instance, or simply one wrapping the same state, is up to the implementation.
1185: * <p/>
1186: * If no node exists at <code>relPath</code> a <code>PathNotFoundException</code> is thrown.
1187: * This exception is also thrown if the current <code>Session</code> does not have read access to the specified node.
1188: *
1189: * @param relPath The relative path of the node to retrieve.
1190: * @return The node at <code>relPath</code>.
1191: * @throws PathNotFoundException If no node exists at the specified path or the current <code>Session</code> does
1192: * not read access to the node at the specified path.
1193: * @throws RepositoryException If another error occurs.
1194: */
1195: public Node getNode(String relPath) throws PathNotFoundException,
1196: RepositoryException;
1197:
1198: /**
1199: * Returns all child nodes of this node accessible through the current <code>Session</code>.
1200: * Does <i>not</i> include properties of this <code>Node</code>.
1201: * The same reacquisition semantics apply as with {@link #getNode(String)}.
1202: * If this node has no accessible child nodes, then an empty iterator is returned.
1203: *
1204: * @return A <code>NodeIterator</code> over all child <code>Node</code>s of
1205: * this <code>Node</code>.
1206: * @throws RepositoryException If an error occurs.
1207: */
1208: public NodeIterator getNodes() throws RepositoryException;
1209:
1210: /**
1211: * Gets all child nodes of this node accessible through the current
1212: * <code>Session</code> that match <code>namePattern</code>.
1213: * The pattern may be a full name or a partial name with one or more
1214: * wildcard characters ("<code>*</code>"), or a disjunction (using the
1215: * "<code>|</code>" character to represent logical <code>OR</code>) of
1216: * these. For example,
1217: * <p/>
1218: * <code>N.getNodes("jcr:* | myapp:report | my doc")</code>
1219: * <p/>
1220: * would return a <code>NodeIterator</code> holding all accessible child nodes of
1221: * <code>N</code> that are either called '<code>myapp:report</code>', begin
1222: * with the prefix '<code>jcr:</code>' or are called '<code>my doc</code>'.
1223: * <p/>
1224: * Note that leading and trailing whitespace around a disjunct is ignored,
1225: * but whitespace within a disjunct forms part of the pattern to be matched.
1226: * <p/>
1227: * The EBNF for <code>namePattern</code> is:
1228: * <p/>
1229: * <code>
1230: * namePattern ::= disjunct {'|' disjunct}<br>
1231: * disjunct ::= name [':' name]<br>
1232: * name ::= '*' | ['*'] fragment {'*' fragment} ['*']<br>
1233: * fragment ::= char {char}<br>
1234: * char ::= nonspace | ' '<br>
1235: * nonspace ::= Any XML Char (See http://www.w3.org/TR/REC-xml/) except:
1236: * '/', ':', '[', ']', '*', ''', '"', '|' or any whitespace character
1237: * </code>
1238: * <p/>
1239: * The pattern is matched against the names (not the paths)
1240: * of the immediate child nodes of this node.
1241: * <p/>
1242: * If this node has no accessible matching child nodes, then an empty iterator is returned.
1243: * <p/>
1244: * The same reacquisition semantics apply as with <code>{@link #getNode(String)}</code>.
1245: *
1246: * @param namePattern a name pattern
1247: * @return a <code>NodeIterator</code>
1248: * @throws RepositoryException If an unexpected error occurs.
1249: */
1250: public NodeIterator getNodes(String namePattern)
1251: throws RepositoryException;
1252:
1253: /**
1254: * Returns the property at <code>relPath</code> relative to <code>this</code>
1255: * node. The same reacquisition
1256: * semantics apply as with <code>{@link #getNode(String)}</code>.
1257: *
1258: * If no property exists at <code>relPath</code> a <code>PathNotFoundException</code> is thrown.
1259: * This exception is also thrown if the current <code>Session</code> does not have read access
1260: * to the specified property.
1261: *
1262: * @param relPath The relative path of the property to retrieve.
1263: * @return The property at <code>relPath</code>.
1264: * @throws PathNotFoundException If no property exists at the
1265: * specified path.
1266: * @throws RepositoryException If another error occurs.
1267: */
1268: public Property getProperty(String relPath)
1269: throws PathNotFoundException, RepositoryException;
1270:
1271: /**
1272: * Returns all properties of this node accessible through the current <code>Session</code>.
1273: * Does <i>not</i> include child <i>nodes</i> of this node. The same reacquisition
1274: * semantics apply as with <code>{@link #getNode(String)}</code>.
1275: * If this node has no accessible properties, then an empty iterator is returned.
1276: *
1277: * @return A <code>PropertyIterator</code>.
1278: * @throws RepositoryException If an error occurs.
1279: */
1280: public PropertyIterator getProperties() throws RepositoryException;
1281:
1282: /**
1283: * Gets all properties of this node accessible through the current
1284: * <code>Session</code> that match <code>namePattern</code>.
1285: * The pattern may be a full name or a partial name with one or more
1286: * wildcard characters ("<code>*</code>"), or a disjunction (using the
1287: * "<code>|</code>" character to represent logical <code>OR</code>) of
1288: * these. For example,
1289: * <p/>
1290: * <code>N.getProperties("jcr:* | myapp:name | my doc")</code>
1291: * <p/>
1292: * would return a <code>PropertyIterator</code> holding all accessible properties of
1293: * <code>N</code> that are either called '<code>myapp:name</code>', begin
1294: * with the prefix '<code>jcr:</code>' or are called '<code>my doc</code>'.
1295: * <p/>
1296: * Note that leading and trailing whitespace around a disjunct is ignored,
1297: * but whitespace within a disjunct forms part of the pattern to be matched.
1298: * <p/>
1299: * The EBNF for <code>namePattern</code> is:
1300: * <p/>
1301: * <code>
1302: * namePattern ::= disjunct {'|' disjunct}<br>
1303: * disjunct ::= name [':' name]<br>
1304: * name ::= '*' | ['*'] fragment {'*' fragment} ['*']<br>
1305: * fragment ::= char {char}<br>
1306: * char ::= nonspace | ' '<br>
1307: * nonspace ::= Any XML Char (See http://www.w3.org/TR/REC-xml/) except:
1308: * '/', ':', '[', ']', '*', ''', '"', '|' or any whitespace character
1309: * </code>
1310: * <p/>
1311: * The pattern is matched against the names (not the paths)
1312: * of the immediate child properties of this node.
1313: * <p/>
1314: * If this node has no accessible matching properties, then an empty iterator is returned.
1315: * <p/>
1316: * The same reacquisition
1317: * semantics apply as with <code>{@link #getNode(String)}</code>.
1318: *
1319: * @param namePattern a name pattern
1320: * @return a <code>PropertyIterator</code>
1321: * @throws RepositoryException If an unexpected error occurs.
1322: */
1323: public PropertyIterator getProperties(String namePattern)
1324: throws RepositoryException;
1325:
1326: /**
1327: * Returns the primary child item of this node.
1328: * The primary node type of this node may specify one child item (child node or property)
1329: * of this node as the <i>primary child item</i>.
1330: * This method returns that item.
1331: * <p/>
1332: * In cases where the primary child item specifies the name of a set same-name sibling
1333: * child nodes, the node returned will be the one among the same-name siblings with index [1].
1334: * <p/>
1335: * The same reacquisition semantics apply as with <code>{@link #getNode(String)}</code>.
1336: * <p/>
1337: * If this node does not have a primary item,
1338: * either because none is declared in the node type
1339: * or because a declared primary item is not present on this node instance,
1340: * or not accessible through the current <code>Session</code>,
1341: * then this method throws an <code>ItemNotFoundException</code>.
1342: *
1343: * @return the primary child item.
1344: * @throws ItemNotFoundException if this node does not have a primary
1345: * child item, either because none is declared in the node type or
1346: * because a declared primary item is not present on this node instance,
1347: * or not accessible through the current <code>Session</code>
1348: * @throws RepositoryException if another error occurs.
1349: */
1350: public Item getPrimaryItem() throws ItemNotFoundException,
1351: RepositoryException;
1352:
1353: /**
1354: * Returns the UUID of this node as recorded in this node's <code>jcr:uuid</code>
1355: * property. This method only works on nodes of mixin node type
1356: * <code>mix:referenceable</code>.
1357: * <p/>
1358: * On nonreferenceable nodes, this method
1359: * throws an <code>UnsupportedRepositoryOperationException</code>.
1360: * To avoid throwing an exception to determine whether a node has a UUID,
1361: * a call to {@link #isNodeType(String) isNodeType("mix:referenceable")} can be made.
1362: *
1363: * @deprecated As of JCR 2.0, {@link #getIdentifier()} should be used instead.
1364: *
1365: * @return the UUID of this node
1366: * @throws UnsupportedRepositoryOperationException
1367: * If this node nonreferenceable.
1368: * @throws RepositoryException If another error occurs.
1369: */
1370: public String getUUID()
1371: throws UnsupportedRepositoryOperationException,
1372: RepositoryException;
1373:
1374: /**
1375: * Returns the identifier of this node. Applies to both referenceable and
1376: * non-referenceable nodes.
1377: * <p/>
1378: * A <code>RepositoryException</code> is thrown if an error occurs.
1379: *
1380: * @return the identifier of this node
1381: * @throws RepositoryException If an error occurs.
1382: * @since JCR 2.0
1383: */
1384: public String getIdentifier() throws RepositoryException;
1385:
1386: /**
1387: * This method returns the index of this node within the ordered set of its same-name
1388: * sibling nodes. This index is the one used to address same-name siblings using the
1389: * square-bracket notation, e.g., <code>/a[3]/b[4]</code>. Note that the index always starts
1390: * at 1 (not 0), for compatibility with XPath. As a result, for nodes that do not have
1391: * same-name-siblings, this method will always return 1.
1392: *
1393: * @return The index of this node within the ordered set of its same-name sibling nodes.
1394: * @throws RepositoryException if an error occurs.
1395: */
1396: public int getIndex() throws RepositoryException;
1397:
1398: /**
1399: * This method returns all <code>REFERENCE</code> properties that refer to
1400: * this node and that are accessible through the current <code>Session</code>.
1401: * Equivalent to <code>Node.getReferences(null)</code>.
1402: *
1403: * @return A <code>PropertyIterator</code>.
1404: * @throws RepositoryException if an error occurs
1405: * @see #getReferences(String)
1406: */
1407: public PropertyIterator getReferences() throws RepositoryException;
1408:
1409: /**
1410: * This method returns all <code>REFERENCE</code> properties that refer to
1411: * this node, have the specified <code>name</code> and that are accessible
1412: * through the current <code>Session</code>.
1413: * <p/>
1414: * If the <code>name</code> parameter is <code>null</code> then all
1415: * referring <code>REFERENCES</code> are returned regardless of name.
1416: * <p/>
1417: * Some level 2 implementations may only return properties that have been
1418: * saved (in a transactional setting this includes both those properties
1419: * that have been saved but not yet committed, as well as properties that
1420: * have been committed). Other level 2 implementations may additionally
1421: * return properties that have been added within the current <code>Session</code>
1422: * but are not yet saved.
1423: * <p/>
1424: * In implementations that support versioning, this method does not return
1425: * properties that are part of the frozen state of a version in version
1426: * storage.
1427: * <p/>
1428: * If this node has no referring properties with the specified name,
1429: * an empty iterator is returned.
1430: *
1431: * @param name name of referring <code>REFERENCE</code> properties to be
1432: * returned; if <code>null</code> then all referring <code>REFERENCE</code>s
1433: * are returned
1434: * @return A <code>PropertyIterator</code>.
1435: * @throws RepositoryException if an error occurs
1436: * @since JCR 2.0
1437: */
1438: public PropertyIterator getReferences(String name)
1439: throws RepositoryException;
1440:
1441: /**
1442: * This method returns all <code>WEAKREFERENCE</code> properties that refer to
1443: * this node and that are accessible through the current <code>Session</code>.
1444: * Equivalent to <code>Node.getWeakReferences(null)</code>.
1445: *
1446: * @return A <code>PropertyIterator</code>.
1447: * @throws RepositoryException if an error occurs
1448: * @since JCR 2.0
1449: * @see #getWeakReferences(String)
1450: */
1451: public PropertyIterator getWeakReferences()
1452: throws RepositoryException;
1453:
1454: /**
1455: * This method returns all <code>WEAKREFERENCE</code> properties that refer to
1456: * this node, have the specified <code>name</code> and that are accessible
1457: * through the current <code>Session</code>.
1458: * <p/>
1459: * If the <code>name</code> parameter is <code>null</code> then all
1460: * referring <code>WEAKREFERENCE</code> are returned regardless of name.
1461: * <p/>
1462: * Some level 2 implementations may only return properties that have been
1463: * saved (in a transactional setting this includes both those properties
1464: * that have been saved but not yet committed, as well as properties that
1465: * have been committed). Other level 2 implementations may additionally
1466: * return properties that have been added within the current <code>Session</code>
1467: * but are not yet saved.
1468: * <p/>
1469: * In implementations that support versioning, this method does not return
1470: * properties that are part of the frozen state of a version in version
1471: * storage.
1472: * <p/>
1473: * If this node has no referring properties with the specified name,
1474: * an empty iterator is returned.
1475: *
1476: * @param name name of referring <code>WEAKREFERENCE</code> properties to be
1477: * returned; if <code>null</code> then all referring <code>WEAKREFERENCE</code>s
1478: * are returned
1479: * @return A <code>PropertyIterator</code>.
1480: * @throws RepositoryException if an error occurs
1481: * @since JCR 2.0
1482: */
1483: public PropertyIterator getWeakReferences(String name)
1484: throws RepositoryException;
1485:
1486: /**
1487: * Indicates whether a node exists at <code>relPath</code>
1488: * Returns <code>true</code> if a node accessible through
1489: * the current <code>Session</code> exists at <code>relPath</code> and
1490: * <code>false</code> otherwise.
1491: *
1492: * @param relPath The path of a (possible) node.
1493: * @return <code>true</code> if a node exists at <code>relPath</code>;
1494: * <code>false</code> otherwise.
1495: * @throws RepositoryException If an unspecified error occurs.
1496: */
1497: public boolean hasNode(String relPath) throws RepositoryException;
1498:
1499: /**
1500: * Indicates whether a property exists at <code>relPath</code>
1501: * Returns <code>true</code> if a property accessible through
1502: * the current <code>Session</code> exists at <code>relPath</code> and
1503: * <code>false</code> otherwise.
1504: *
1505: * @param relPath The path of a (possible) property.
1506: * @return <code>true</code> if a property exists at <code>relPath</code>;
1507: * <code>false</code> otherwise.
1508: * @throws RepositoryException If an unspecified error occurs.
1509: */
1510: public boolean hasProperty(String relPath)
1511: throws RepositoryException;
1512:
1513: /**
1514: * Indicates whether this node has child nodes.
1515: * Returns <code>true</code> if this node has one or more child nodes accessible through
1516: * the current <code>Session</code>;
1517: * <code>false</code> otherwise.
1518: *
1519: * @return <code>true</code> if this node has one or more child nodes;
1520: * <code>false</code> otherwise.
1521: * @throws RepositoryException If an unspecified error occurs.
1522: */
1523: public boolean hasNodes() throws RepositoryException;
1524:
1525: /**
1526: * Indicates whether this node has properties.
1527: * Returns <code>true</code> if this node has one or more properties accessible through
1528: * the current <code>Session</code>;
1529: * <code>false</code> otherwise.
1530: *
1531: * @return <code>true</code> if this node has one or more properties;
1532: * <code>false</code> otherwise.
1533: * @throws RepositoryException If an unspecified error occurs.
1534: */
1535: public boolean hasProperties() throws RepositoryException;
1536:
1537: /**
1538: * Returns the primary node type in effect for this node. Note that this may
1539: * differ from the node type implied by the node's <code>jcr:primaryType</code>
1540: * property if that property has recently been created or changed and has not
1541: * yet been saved. Which <code>NodeType</code> is returned when this method
1542: * is called on the root node of a workspace is up to the implementation, though
1543: * the returned type must, of course, be consistent with the child nodes and
1544: * properties of the root node.
1545: *
1546: * @return a <code>NodeType</code> object.
1547: * @throws RepositoryException if an error occurs
1548: */
1549: public NodeType getPrimaryNodeType() throws RepositoryException;
1550:
1551: /**
1552: * Returns an array of <code>NodeType</code> objects representing the mixin
1553: * node types in effect for this node. This includes only those mixin types
1554: * explicitly assigned to this node. It does not include mixin types inherited
1555: * through the addition of supertypes to the primary type hierarchy or through
1556: * the addition of supertypes to the type hierarchy of any of the declared
1557: * mixin types. Note that this may differ from the node types implied by the
1558: * node's <code>jcr:mixinTypes</code> property if that property has recently
1559: * been created or changed and has not yet been saved.
1560: *
1561: * @return an array of <code>NodeType</code> objects.
1562: * @throws RepositoryException if an error occurs
1563: */
1564: public NodeType[] getMixinNodeTypes() throws RepositoryException;
1565:
1566: /**
1567: * Returns <code>true</code> if this node is of the specified primary node type
1568: * or mixin type, or a subtype thereof. Returns <code>false</code> otherwise.
1569: * <p/>
1570: * This method respects the effective node type of the node. Note that this
1571: * may differ from the node type implied by the node's <code>jcr:primaryType</code>
1572: * property or <code>jcr:mixinTypes</code> property if that property has
1573: * recently been created or changed and has not yet been saved.
1574: *
1575: * @param nodeTypeName the name of a node type.
1576: * @return <code>true</code> If this node is of the specified primary node type
1577: * or mixin type, or a subtype thereof. Returns <code>false</code> otherwise.
1578: * @throws RepositoryException If an error occurs.
1579: */
1580: public boolean isNodeType(String nodeTypeName)
1581: throws RepositoryException;
1582:
1583: /**
1584: * Changes the primary node type of this node to <code>nodeTypeName</code>.
1585: * Also immediately changes this node's <code>jcr:primaryType</code> property
1586: * appropriately. Semantically, the new node type may take effect
1587: * immediately and <i>must</i> take effect on <code>save</code>. Whichever
1588: * behavior is adopted it must be the same as the behavior adopted for
1589: * <code>addMixin()</code> (see below) and the behavior that occurs when a
1590: * node is first created.
1591: * <p/>
1592: * If the presence of an existing property or child node would cause an
1593: * incompatibility with the new node type a <code>ConstraintViolationException</code>
1594: * is thrown either immediately or on <code>save</code>.
1595: * <p/>
1596: * If the new node type would cause this node to be incompatible with the
1597: * node type of its parent then a <code>ConstraintViolationException</code>
1598: * is thrown either immediately or on <code>save</code>.
1599: * <p/>
1600: * A <code>ConstraintViolationException</code> is also thrown either
1601: * immediately or on <code>save</code> if a conflict with an already
1602: * assigned mixin occurs.
1603: * <p/>
1604: * A <code>ConstraintViolationException</code> may also be thrown either
1605: * immediately or on <code>save</code> if the attempted change violates
1606: * implementation-specific node type transition rules. A repository that
1607: * disallows all primary node type changes would simple throw this
1608: * exception in all cases.
1609: * <p/>
1610: * If the specified node type is not recognized a
1611: * <code>NoSuchNodeTypeException</code> is thrown either immediately
1612: * or on <code>save</code>.
1613: * <p/>
1614: * A <code>VersionException</code> is thrown either immediately or on
1615: * <code>save</code> if this node is versionable and checked-in, or is
1616: * non-versionable but its nearest versionable ancestor is checked-in.
1617: * <p/>
1618: * A <code>LockException</code> is thrown either immediately or on
1619: * <code>save</code> if a lock prevents the change of node type.
1620: * <p/>
1621: * A <code>RepositoryException</code> will be thrown if another error occurs.
1622: *
1623: * @param nodeTypeName the name of the new node type.
1624: * @throws ConstraintViolationException If the specified primary node type
1625: * is prevented from being assigned.
1626: * @throws NoSuchNodeTypeException If the specified <code>nodeTypeName</code>
1627: * is not recognized and this implementation performs this validation
1628: * immediately instead of waiting until <code>save</code>.
1629: * @throws VersionException if this node is versionable and checked-in or is
1630: * non-versionable but its nearest versionable ancestor is checked-in and this
1631: * implementation performs this validation immediately instead of waiting until
1632: * <code>save</code>.
1633: * @throws LockException if a lock prevents the change of the primary node type
1634: * and this implementation performs this validation immediately instead of
1635: * waiting until <code>save</code>.
1636: * @throws RepositoryException if another error occurs.
1637: * @since JCR 2.0
1638: */
1639: public void setPrimaryType(String nodeTypeName)
1640: throws NoSuchNodeTypeException, VersionException,
1641: ConstraintViolationException, LockException,
1642: RepositoryException;
1643:
1644: /**
1645: * Adds the specified mixin node type to this node and adds <code>mixinName</code>
1646: * to this node's <code>jcr:mixinTypes</code> property. Semantically, the new
1647: * node type <i>may</i> take effect immediately and <i>must</i> take effect
1648: * on <code>save</code>. Whichever behavior is adopted it must be the same as
1649: * the behavior adopted for {@link #setPrimaryType} and the behavior that
1650: * occurs when a node is first created.
1651: * <p/>
1652: * A <code>ConstraintViolationException</code> is thrown either immediately or on <code>save</code>
1653: * if a conflict with another assigned mixin or the primary node type or for an implementation-specific
1654: * reason. Implementations may differ on when this validation is done.
1655: * <p/>
1656: * In some implementations it may only be possible to add mixin types before a
1657: * a node is first saved, and not after. I such cases any later calls to
1658: * <code>addMixin</code> will throw a <code>ConstraintViolationException</code>
1659: * either immediately or on <code>save</code>.
1660: * <p/>
1661: * A <code>NoSuchNodeTypeException</code> is thrown either immediately or on <code>save</code>
1662: * if the specified <code>mixinName</code> is not recognized.
1663: * Implementations may differ on when this validation is done.
1664: * <p/>
1665: * A <code>VersionException</code> is thrown either immediately or on <code>save</code>
1666: * if this node is versionable and checked-in or is non-versionable but its
1667: * nearest versionable ancestor is checked-in.
1668: * Implementations may differ on when this validation is done.
1669: * <p/>
1670: * A <code>LockException</code> is thrown either immediately or on <code>save</code>
1671: * if a lock prevents the addition of the mixin.
1672: * Implementations may differ on when this validation is done.
1673: *
1674: * @param mixinName the name of the mixin node type to be added
1675: * @throws NoSuchNodeTypeException If the specified <code>mixinName</code>
1676: * is not recognized and this
1677: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1678: * @throws ConstraintViolationException If the specified mixin node type
1679: * is prevented from being assigned.
1680: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
1681: * nearest versionable ancestor is checked-in and this
1682: * implementation performs this validation immediately instead of waiting until <code>save</code>..
1683: * @throws LockException if a lock prevents the addition of the mixin and this
1684: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1685: * @throws RepositoryException if another error occurs.
1686: */
1687: public void addMixin(String mixinName)
1688: throws NoSuchNodeTypeException, VersionException,
1689: ConstraintViolationException, LockException,
1690: RepositoryException;
1691:
1692: /**
1693: * Removes the specified mixin node type from this node and removes <code>mixinName</code>
1694: * from this node's <code>jcr:mixinTypes</code> property. Both the semantic
1695: * change in effective node type and the persistence of the change to the
1696: * <code>jcr:mixinTypes</code> property occur on <code>save</code>.
1697: * <p/>
1698: * If this node does not have the specified mixin, a <code>NoSuchNodeTypeException</code> is thrown
1699: * either immediately or on <code>save</code>. Implementations may differ on when this validation is done.
1700: * <p/>
1701: * A <code>ConstraintViolationException</code> will be thrown either immediately or on <code>save</code>
1702: * if the removal of a mixin is not allowed. Implementations are free to enforce any policy they
1703: * like with regard to mixin removal and may differ on when this validation is done.
1704: * <p/>
1705: * A <code>VersionException</code> is thrown either immediately or on <code>save</code>
1706: * if this node is versionable and checked-in or is
1707: * non-versionable but its nearest versionable ancestor is checked-in.
1708: * Implementations may differ on when this validation is done.
1709: * <p/>
1710: * A <code>LockException</code> is thrown either immediately or on <code>save</code>
1711: * if a lock prevents the removal of the mixin.
1712: * Implementations may differ on when this validation is done.
1713: *
1714: * @param mixinName the name of the mixin node type to be removed.
1715: * @throws NoSuchNodeTypeException if the specified <code>mixinName</code>
1716: * is not currently assigned to this node and this
1717: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1718: * @throws ConstraintViolationException if the specified mixin node type
1719: * is prevented from being removed and this
1720: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1721: * @throws VersionException if this node is versionable and checked-in or is non-versionable but its
1722: * nearest versionable ancestor is checked-in and this
1723: * implementation performs this validation immediately instead of waiting until <code>save</code>.
1724: * @throws LockException if a lock prevents the removal of the mixin and this
1725: * implementation performs this validation immediately instead of waiting until <code>save</code>..
1726: * @throws RepositoryException if another error occurs.
1727: */
1728: public void removeMixin(String mixinName)
1729: throws NoSuchNodeTypeException, VersionException,
1730: ConstraintViolationException, LockException,
1731: RepositoryException;
1732:
1733: /**
1734: * Returns <code>true</code> if the specified mixin node type, <code>mixinName</code>,
1735: * can be added to this node. Returns <code>false</code> otherwise. A result of
1736: * <code>false</code> must be returned in each of the following cases:
1737: * <ul>
1738: * <li>
1739: * The mixin's definition conflicts with an existing primary or mixin node type of this node.
1740: * </li>
1741: * <li>
1742: * This node is versionable and checked-in or is non-versionable and its nearest versionable
1743: * ancestor is checked-in.
1744: * </li>
1745: * <li>
1746: * This node is protected (as defined in this node's <code>NodeDefinition</code>,
1747: * found in the node type of this node's parent).
1748: * </li>
1749: * <li>
1750: * An access control restriction would prevent the addition of the mixin.
1751: * </li>
1752: * <li>
1753: * A lock would prevent the addition of the mixin.
1754: * </li>
1755: * <li>
1756: * An implementation-specific restriction would prevent the addition of the mixin.
1757: * </li>
1758: * </ul>
1759: * A <code>NoSuchNodeTypeException</code> is thrown if the specified mixin node type name is not recognized.
1760: *
1761: * @param mixinName The name of the mixin to be tested.
1762: * @return <code>true</code> if the specified mixin node type,
1763: * <code>mixinName</code>, can be added to this node; <code>false</code> otherwise.
1764: * @throws NoSuchNodeTypeException if the specified mixin node type name is not recognized.
1765: * @throws RepositoryException if another error occurs.
1766: */
1767: public boolean canAddMixin(String mixinName)
1768: throws NoSuchNodeTypeException, RepositoryException;
1769:
1770: /**
1771: * Returns the node definition that applies to this node. In some cases there may appear
1772: * to be more than one definition that could apply to this node. However, it is assumed that upon
1773: * creation of this node, a single particular definition was used and it is <i>that</i> definition that
1774: * this method returns. How this governing definition is selected upon node creation from among others
1775: * which may have been applicable is an implementation issue and is not covered by this specification.
1776: * The <code>NodeDefinition</code> returned when this method is called on the root node of a workspace
1777: * is also up to the implementation.
1778: *
1779: * @return a <code>NodeDefinition</code> object.
1780: * @throws RepositoryException if an error occurs.
1781: * @see NodeType#getChildNodeDefinitions
1782: */
1783: public NodeDefinition getDefinition() throws RepositoryException;
1784:
1785: /**
1786: * Creates a new version with a system generated version name and returns that version
1787: * (which will be the new base version of this node). Sets the <code>jcr:checkedOut</code>
1788: * property to false thus putting the node into the <i>checked-in</i> state. This means
1789: * that this node and its <i>connected non-versionable subtree</i> become read-only.
1790: * A node's connected non-versionable subtree is the set of non-versionable descendant nodes
1791: * reachable from that node through child links without encountering any versionable nodes.
1792: * In other words, the read-only status flows down from the checked-in node along every child
1793: * link until either a versionable node is encountered or an item with no children is encountered.
1794: * In a system that supports only simple versioning the connected non-versionable
1795: * subtree will be equivalent to the whole subtree, since simple-versionable
1796: * nodes cannot have simple-versionable descendents.
1797: * <p/>
1798: * Read-only status means that an item cannot be altered by the client using standard API methods
1799: * (<code>addNode</code>, <code>setProperty</code>, etc.). The only exceptions to this rule are the {@link Node#restore}
1800: * (all signatures), {@link Node#restoreByLabel}, {@link Workspace#restore}, {@link Node#merge} and {@link Node#update}
1801: * operations; these do not respect read-only status due to check-in. Note that <code>remove</code>
1802: * of a read-only node is possible, as long as its parent is not read-only (since removal is an
1803: * alteration of the parent node).
1804: * <p/>
1805: * If this node is already checked-in, this method has no effect but returns the current base version
1806: * of this node.
1807: * <p/>
1808: * If this node is not versionable, an <code>UnsupportedRepositoryOperationException</code> is thrown.
1809: * <p/>
1810: * A <code>VersionException</code> is thrown or if a child item of this node has an
1811: * <code>OnParentVersion</code> status of <code>ABORT</code>. This includes the case where
1812: * an unresolved merge failure exists on this node, as indicated by the presence of the
1813: * <code>jcr:mergeFailed</code> property.
1814: * <p/>
1815: * If there are unsaved changes pending on this node, an <code>InvalidItemStateException</code>
1816: * is thrown.
1817: * <p/>
1818: * Throws a <code>LockException</code> if a lock prevents the operation.
1819: * <p/>
1820: * If <code>checkin</code> succeeds, the change to the <code>jcr:isCheckedOut</code> property is
1821: * automatically persisted (there is no need to do an additional <code>save</code>).
1822: * <p/>
1823: *
1824: * @return a <code>Version</code> object
1825: * @throws VersionException if <code>jcr:predecessors</code> does not contain at least one value or if
1826: * a child item of this node has an <code>OnParentVersion</code> status of <code>ABORT</code>.
1827: * This includes the case where an unresolved merge failure exists on this node, as indicated
1828: * by the presence of a <code>jcr:mergeFailed</code> property.
1829: * @throws UnsupportedRepositoryOperationException
1830: * If this node is not versionable.
1831: * @throws InvalidItemStateException If unsaved changes exist on this node.
1832: * @throws LockException if a lock prevents the operation.
1833: * @throws RepositoryException If another error occurs.
1834: */
1835: public Version checkin() throws VersionException,
1836: UnsupportedRepositoryOperationException,
1837: InvalidItemStateException, LockException,
1838: RepositoryException;
1839:
1840: /**
1841: * Sets this versionable node to checked-out status by setting its
1842: * <code>jcr:isCheckedOut</code> property to <code>true</code>. Under full
1843: * versioning it also sets the <code>jcr:predecessors</code> property to be
1844: * a reference to the current base version (the same value as held in
1845: * <code>jcr:baseVersion</code>).
1846: * <p/>
1847: * This method puts the node into the <i>checked-out</i> state, making it
1848: * and its connected non-versionable subtree no longer read-only (see
1849: * {@link #checkin()} for an explanation of the term
1850: * "connected non-versionable subtree". Under simple versioning this will
1851: * simply be the whole subtree).
1852: * <p/>
1853: * If successful, these changes are persisted immediately,
1854: * there is no need to call <code>save</code>.
1855: * <p/>
1856: * If this node is already checked-out, this method has no effect.
1857: * </p>
1858: * If this node is not versionable, an <code>UnsupportedRepositoryOperationException</code> is thrown.
1859: * <p/>
1860: * Throws a <code>LockException</code> if a lock prevents the checkout.
1861: *
1862: * @throws UnsupportedRepositoryOperationException
1863: * If this node is not versionable.
1864: * @throws LockException if a lock prevents the checkout.
1865: * @throws RepositoryException If another error occurs.
1866: */
1867: public void checkout()
1868: throws UnsupportedRepositoryOperationException,
1869: LockException, RepositoryException;
1870:
1871: /**
1872: * Performs a <code>checkin()</code> followed by a <code>checkout()</code>.
1873: * <p/>
1874: * If this node is already checked-in, this method is equivalent to <code>checkout()</code>.
1875: * <p/>
1876: * If this node is not versionable, an
1877: * <code>UnsupportedRepositoryOperationException</code> is thrown.
1878: * <p/>
1879: * A <code>VersionException</code> is thrown if a child item of this node
1880: * has an <code>OnParentVersion</code> of <code>ABORT</code>. This
1881: * includes the case where an unresolved merge failure exists on this node,
1882: * as indicated by the presence of the <code>jcr:mergeFailed</code>
1883: * property.
1884: * <p/>
1885: * If there are unsaved changes pending on this node, an
1886: * <code>InvalidItemStateException</code> is thrown.
1887: * <p/>
1888: * A <code>LockException</code> is thrown if a lock prevents the operation.
1889: * <p/>
1890: * A <code>RepositoryException</code> is thrown if another error occurs.
1891: *
1892: * @throws VersionException if a child item of this node has an
1893: * <code>OnParentVersion</code> of <code>ABORT</code>. This includes the case
1894: * where an unresolved merge failure exists on this node, as indicated by
1895: * the presence of the <code>jcr:mergeFailed</code>.
1896: * @throws UnsupportedRepositoryOperationException if this node is not versionable.
1897: * @throws InvalidItemStateException if there are unsaved changes pending on this node.
1898: * @throws LockException if a lock prevents the operation.
1899: * @throws RepositoryException if another error occurs.
1900: * @since JCR 2.0
1901: */
1902: public void checkpoint() throws VersionException,
1903: UnsupportedRepositoryOperationException,
1904: InvalidItemStateException, LockException,
1905: RepositoryException;
1906:
1907: /**
1908: * <i>Support for this method is only required under full versioning.</i>
1909: * <p/>
1910: * Completes the merge process with respect to this node and the specified <code>version</code>.
1911: * <p/>
1912: * When the {@link #merge} method is called on a node, every versionable node in that
1913: * subtree is compared with its corresponding node in the indicated other workspace and
1914: * a "merge test result" is determined indicating one of the following:
1915: * <ol>
1916: * <li>
1917: * This node will be updated to the state of its correspondee (if the base version
1918: * of the correspondee is more recent in terms of version history)
1919: * </li>
1920: * <li>
1921: * This node will be left alone (if this node's base version is more recent in terms of
1922: * version history).
1923: * </li>
1924: * <li>
1925: * This node will be marked as having failed the merge test (if this node's base version
1926: * is on a different branch of the version history from the base version of its
1927: * corresponding node in the other workspace, thus preventing an automatic determination
1928: * of which is more recent).
1929: * </li>
1930: * </ol>
1931: * (See {@link #merge} for more details)
1932: * <p/>
1933: * In the last case the merge of the non-versionable subtree
1934: * (the "content") of this node must be done by the application (for example, by
1935: * providing a merge tool for the user).
1936: * <p/>
1937: * Additionally, once the content of the nodes has been merged, their version graph
1938: * branches must also be merged. The JCR versioning system provides for this by
1939: * keeping a record, for each versionable node that fails the merge test, of the
1940: * base verison of the corresponding node that caused the merge failure. This record
1941: * is kept in the <code>jcr:mergeFailed</code> property of this node. After a
1942: * <code>merge</code>, this property will contain one or more (if
1943: * multiple merges have been performed) <code>REFERENCE</code>s that point
1944: * to the "offending versions".
1945: * <p/>
1946: * To complete the merge process, the client calls <code>doneMerge(Version v)</code>
1947: * passing the version object referred to be the <code>jcr:mergeFailed</code> property
1948: * that the client wishes to connect to <code>this</code> node in the version graph.
1949: * This has the effect of moving the reference to the indicated version from the
1950: * <code>jcr:mergeFailed</code> property of <code>this</code> node to the
1951: * <code>jcr:predecessors</code>.
1952: * <p/>
1953: * If the client chooses not to connect this node to a particular version referenced in
1954: * the <code>jcr:mergeFailed</code> property, he calls {@link #cancelMerge(Version version)}.
1955: * This has the effect of removing the reference to the specified <code>version</code> from
1956: * <code>jcr:mergeFailed</code> <i>without</i> adding it to <code>jcr:predecessors</code>.
1957: * <p/>
1958: * Once the last reference in <code>jcr:mergeFailed</code> has been either moved to
1959: * <code>jcr:predecessors</code> (with <code>doneMerge</code>) or just removed
1960: * from <code>jcr:mergeFailed</code> (with <code>cancelMerge</code>) the <code>jcr:mergeFailed</code>
1961: * property is automatically removed, thus enabling <code>this</code>
1962: * node to be checked-in, creating a new version (note that before the <code>jcr:mergeFailed</code>
1963: * is removed, its <code>OnParentVersion</code> setting of <code>ABORT</code> prevents checkin).
1964: * This new version will have a predecessor connection to each version for which <code>doneMerge</code>
1965: * was called, thus joining those branches of the version graph.
1966: * <p/>
1967: * If successful, these changes are persisted immediately,
1968: * there is no need to call <code>save</code>.
1969: * <p/>
1970: * A <code>VersionException</code> is thrown if the <code>version</code> specified is
1971: * not among those referecned in this node's <code>jcr:mergeFailed</code> property.
1972: * <p/>
1973: * If there are unsaved changes pending on this node, an <code>InvalidItemStateException</code> is thrown.
1974: * <p/>
1975: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this node is not versionable.
1976: * <p/>
1977: * A <code>RepositoryException</code> is thrown if another error occurs.
1978: *
1979: * @param version a version referred to by this node's <code>jcr:mergeFailed</code> property.
1980: * @throws VersionException if the version specifed is not among those referenced in this node's <code>jcr:mergeFailed</code> or if this node is currently checked-in.
1981: * @throws InvalidItemStateException if there are unsaved changes pending on this node.
1982: * @throws UnsupportedRepositoryOperationException if this node is not versionable.
1983: * @throws RepositoryException if another error occurs.
1984: */
1985: public void doneMerge(Version version) throws VersionException,
1986: InvalidItemStateException,
1987: UnsupportedRepositoryOperationException,
1988: RepositoryException;
1989:
1990: /**
1991: * <i>Support for this method is only required under full versioning.</i>
1992: * <p/>
1993: * Cancels the merge process with respect to this node and specified <code>version</code>.
1994: * <p/>
1995: * See {@link #doneMerge} for a full explanation. Also see {@link #merge} for
1996: * more details.
1997: * <p/>
1998: * If successful, these changes are persisted immediately,
1999: * there is no need to call <code>save</code>.
2000: * <p/>
2001: * A <code>VersionException</code> is thrown if the <code>version</code> specified is
2002: * not among those referenced in this node's <code>jcr:mergeFailed</code> property
2003: * or if this node is currently checked-in.
2004: * <p/>
2005: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this nod is not versionable.
2006: * <p/>
2007: * If there are unsaved changes pending on this node, an <code>InvalidItemStateException</code> is thrown.
2008: * <p/>
2009: * A <code>RepositoryException</code> is thrown if another error occurs.
2010: *
2011: * @param version a version referred to by this node's <code>jcr:mergeFailed</code> property.
2012: * @throws VersionException if the version specified is not among those referenced in this node's <code>jcr:mergeFailed</code> or if this node is currently checked-in.
2013: * @throws InvalidItemStateException if there are unsaved changes pending on this node.
2014: * @throws UnsupportedRepositoryOperationException if this node is not versionable.
2015: * @throws RepositoryException if another error occurs.
2016: */
2017: public void cancelMerge(Version version) throws VersionException,
2018: InvalidItemStateException,
2019: UnsupportedRepositoryOperationException,
2020: RepositoryException;
2021:
2022: /**
2023: * If this node does have a corresponding node in the workspace <code>srcWorkspace</code>,
2024: * then this replaces this node and its subtree with a clone of the corresponding node and its
2025: * subtree.
2026: * <p/>
2027: * If this node does not have a corresponding node in the workspace
2028: * <code>srcWorkspace</code>, then the <code>update</code> method
2029: * has no effect.
2030: * <p/>
2031: * If the <code>update</code> succeeds the changes made are persisted immediately, there is
2032: * no need to call <code>save</code>.
2033: * <p/>
2034: * Note that <code>update</code> does not respect the checked-in status of nodes.
2035: * An <code>update</code> may change a node even if it is currently checked-in
2036: * (This fact is only relevant in an implementation that supports versioning).
2037: * <p/>
2038: * If the specified <code>srcWorkspace</code> does not exist, a
2039: * <code>NoSuchWorkspaceException</code> is thrown.
2040: * <p/>
2041: * If the current session does not have sufficient rights to perform the operation, then an
2042: * <code>AccessDeniedException</code> is thrown.
2043: * <p/>
2044: * An InvalidItemStateException is thrown if this <code>Session</code> (not necessarily this
2045: * <code>Node</code>) has pending unsaved changes.
2046: * <p/>
2047: * Throws a <code>LockException</code> if a lock prevents the update.
2048: * <p/>
2049: * A <code>RepositoryException</code> is thrown if another error occurs.
2050: *
2051: * @param srcWorkspace the name of the source workspace.
2052: * @throws NoSuchWorkspaceException If <code>srcWorkspace</code> does not exist.
2053: * @throws InvalidItemStateException if this <code>Session</code> (not necessarily this <code>Node</code>) has pending unsaved changes.
2054: * @throws AccessDeniedException If the current session does not have sufficient rights to perform the operation.
2055: * @throws LockException if a lock prevents the update.
2056: * @throws RepositoryException If another error occurs.
2057: */
2058: public void update(String srcWorkspace)
2059: throws NoSuchWorkspaceException, AccessDeniedException,
2060: LockException, InvalidItemStateException,
2061: RepositoryException;
2062:
2063: /**
2064: * <i>Support for this method is only required under full versioning.</i>
2065: * <p/>
2066: * This method can be thought of as a version-sensitive update.
2067: * <p/>
2068: * It recursively tests each versionable node in the subtree of this node
2069: * against its corresponding node in <code>srcWorkspace</code> with respect
2070: * to the relation between their respective base versions and either updates
2071: * the node in question or not, depending on the outcome of the test.
2072: * <p/>
2073: * A <code>MergeException</code> is thrown if <code>bestEffort</code> is <code>false</code>
2074: * and a versionable node is encountered whose corresponding node's base
2075: * version is on a divergent branch from this node's base version.
2076: * <p/>
2077: * If successful, the changes are persisted immediately, there is no need to
2078: * call <code>save</code>.
2079: * <p/>
2080: * This method returns a <code>NodeIterator</code> over all versionable nodes
2081: * in the subtree that received a merge result of <i>fail</i>. If
2082: * <code>bestEffort</code> is <code>false</code>, this iterator will be empty
2083: * (since if <code>merge</code> returns successfully, instead of throwing
2084: * an exception, it will be because no failures were encountered). If
2085: * <code>bestEffort</code> is <code>true</code>, this iterator will
2086: * contain all nodes that received a <i>fail</i> during the course of this
2087: * <code>merge</code> operation.
2088: * <p/>
2089: * If the specified <code>srcWorkspace</code> does not exist, a
2090: * <code>NoSuchWorkspaceException</code> is thrown.
2091: * <p/>
2092: * If the current session does not have
2093: * sufficient permissions to perform the operation, then an
2094: * <code>AccessDeniedException</code> is thrown.
2095: * <p/>
2096: * An <code>InvalidItemStateException</code> is thrown
2097: * if this session (not necessarily this <code>Node</code>) has pending
2098: * unsaved changes.
2099: * <p/>
2100: * A <code>LockException</code> is thrown if a lock prevents the merge.
2101: *
2102: * @param srcWorkspace the name of the source workspace.
2103: * @param bestEffort a boolean
2104: * @return iterator over all nodes that received a merge result of "fail" in the course
2105: * of this operation.
2106: * @throws MergeException if <code>bestEffort</code> is <code>false</code> and a failed merge
2107: * result is encountered.
2108: * @throws InvalidItemStateException if this session (not necessarily this
2109: * <code>node</code>) has pending unsaved changes.
2110: * @throws NoSuchWorkspaceException if the specified <code>srcWorkspace</code> does not exist.
2111: * @throws AccessDeniedException if the current session does not have sufficient
2112: * rights to perform the operation.
2113: * @throws LockException if a lock prevents the merge.
2114: * @throws RepositoryException if another error occurs.
2115: */
2116: public NodeIterator merge(String srcWorkspace, boolean bestEffort)
2117: throws NoSuchWorkspaceException, AccessDeniedException,
2118: MergeException, LockException, InvalidItemStateException,
2119: RepositoryException;
2120:
2121: /**
2122: * <i>Support for this method is only required under full versioning.</i>
2123: * <p/>
2124: * This method can be thought of as a version-sensitive update.
2125: * <p/>
2126: * If <code>isShallow</code> is <code>true</code>, it tests this versionable node against its corresponding
2127: * node in <code>srcWorkspace</code> with respect to the relation between their
2128: * respective base versions and either updates the node in question or not,
2129: * depending on the outcome of the test.
2130: * <p/>
2131: * If <code>isShallow</code> is <code>false</code>, it recursively tests each
2132: * versionable node in the subtree as mentioned above.
2133: * <p/>
2134: * If <code>isShallow</code> is <code>true</code> and this node is not
2135: * versionable, then this method returns and no changes are made.
2136: * <p/>
2137: * A <code>MergeException</code> is thrown if <code>bestEffort</code> is <code>false</code>
2138: * and a versionable node is encountered whose corresponding node's base
2139: * version is on a divergent branch from this node's base version.
2140: * <p/>
2141: * If successful, the changes are persisted immediately, there is no need to
2142: * call <code>save</code>.
2143: * <p/>
2144: * This method returns a <code>NodeIterator</code> over all versionable nodes
2145: * in the subtree that received a merge result of <i>fail</i>. If
2146: * <code>bestEffort</code> is <code>false</code>, this iterator will be empty
2147: * (since if <code>merge</code> returns successfully, instead of throwing
2148: * an exception, it will be because no failures were encountered). If
2149: * <code>bestEffort</code> is <code>true</code>, this iterator will
2150: * contain all nodes that received a <i>fail</i> during the course of this
2151: * <code>merge</code> operation.
2152: * <p/>
2153: * If the specified <code>srcWorkspace</code> does not exist, a
2154: * <code>NoSuchWorkspaceException</code> is thrown.
2155: * <p/>
2156: * If the current session does not have
2157: * sufficient permissions to perform the operation, then an
2158: * <code>AccessDeniedException</code> is thrown.
2159: * <p/>
2160: * An <code>InvalidItemStateException</code> is thrown
2161: * if this session (not necessarily this node) has pending unsaved changes.
2162: * <p/>
2163: * A <code>LockException</code> is thrown if a lock prevents the merge.
2164: *
2165: * @param srcWorkspace the name of the source workspace.
2166: * @param bestEffort a boolean
2167: * @param isShallow a boolean
2168: * @return iterator over all nodes that received a merge result of "fail" in the course
2169: * of this operation.
2170: * @throws MergeException if <code>bestEffort</code> is <code>false</code> and a failed merge
2171: * result is encountered.
2172: * @throws InvalidItemStateException if this session (not necessarily this
2173: * node) has pending unsaved changes.
2174: * @throws NoSuchWorkspaceException if <code>srcWorkspace</code> does not exist.
2175: * @throws AccessDeniedException if the current session does not have sufficient
2176: * rights to perform the operation.
2177: * @throws LockException if a lock prevents the merge.
2178: * @throws RepositoryException if another error occurs.
2179: * @since JCR 2.0
2180: */
2181: public NodeIterator merge(String srcWorkspace, boolean bestEffort,
2182: boolean isShallow) throws NoSuchWorkspaceException,
2183: AccessDeniedException, MergeException, LockException,
2184: InvalidItemStateException, RepositoryException;
2185:
2186: /**
2187: * Calling <code>createConfiguration</code> on a node <i>N</i> creates,
2188: * in the configuration storage, a new <code>nt:configuration</code> node
2189: * whose root is <i>N</i>. A reference to <i>N</i> is recorded in the
2190: * <code>jcr:root</code> property of the new configuration, and a reference
2191: * to the new configuration is recorded in the <code>jcr:configuration</code>
2192: * property of <i>N</i>.
2193: * <p/>
2194: * If the specified <code>baseline</code> is <code>null</code>, a new version
2195: * history is created to store baselines of the new configuration, and the
2196: * <code>jcr:baseVersion</code> of the new configuration references the root
2197: * of the new version history. If the specified baseline is not <code>null</code>,
2198: * the <code>jcr:baseVersion</code> of the new configuration references the
2199: * specified baseline.
2200: * <p/>
2201: * The changes are persisted immediately, a <code>save</code> is not required.
2202: * <p/>
2203: * An <code>UnsupportedRepositoryOperationException</code> is thrown if
2204: * <i>N</i> is not versionable.
2205: * <p/>
2206: * A <code>RepositoryException</code> is thrown if another error occurs.
2207: *
2208: * @param baseline a <code>Version</code>
2209: * @return a new <code>nt:configuration</code> node
2210: * @throws UnsupportedRepositoryOperationException if <i>N</i> is not versionable.
2211: * @throws RepositoryException if another error occurs.
2212: * @since JCR 2.0
2213: */
2214: public Node createConfiguration(Version baseline)
2215: throws UnsupportedRepositoryOperationException,
2216: RepositoryException;
2217:
2218: /**
2219: * Returns the absolute path of the node in the specified workspace that
2220: * corresponds to <code>this</code> node.
2221: * <p/>
2222: * If no corresponding node exists then an <code>ItemNotFoundException</code> is thrown.
2223: * <p/>
2224: * If the specified workspace does not exist then a <code>NoSuchWorkspaceException</code> is thrown.
2225: * <p/>
2226: * If the current <code>Session</code> does not have sufficent rights to perform this operation,
2227: * an <code>AccessDeniedException</code> is thrown.
2228: *
2229: * @param workspaceName the name of the workspace.
2230: * @return the absolute path to the corresponding node.
2231: * @throws ItemNotFoundException if no corresponding node is found.
2232: * @throws NoSuchWorkspaceException if the workspace is unknown.
2233: * @throws AccessDeniedException if the current <code>session</code> has insufficent rights to perform this operation.
2234: * @throws RepositoryException if another error occurs.
2235: */
2236: public String getCorrespondingNodePath(String workspaceName)
2237: throws ItemNotFoundException, NoSuchWorkspaceException,
2238: AccessDeniedException, RepositoryException;
2239:
2240: /**
2241: * Returns an iterator over all nodes that are in the shared set of this
2242: * node. If this node is not shared then the returned iterator contains
2243: * only this node.
2244: *
2245: * @return a <code>NodeIterator</code>
2246: * @throws RepositoryException if an error occurs.
2247: * @since JCR 2.0
2248: */
2249: public NodeIterator getSharedSet() throws RepositoryException;
2250:
2251: /**
2252: * A special kind of <code>remove()</code> that removes this node and every
2253: * other node in the shared set of this node.
2254: * <p/>
2255: * This removal must be done atomically, i.e., if one of the nodes cannot be
2256: * removed, the function throws the exception <code>remove()</code> would
2257: * have thrown in that case, and none of the nodes are removed.
2258: * <p/>
2259: * If this node is not shared this method removes only this node.
2260: *
2261: * @throws VersionException
2262: * @throws LockException
2263: * @throws ConstraintViolationException
2264: * @throws RepositoryException
2265: * @see #removeShare()
2266: * @see Item#remove()
2267: * @since JCR 2.0
2268: */
2269: public void removeSharedSet() throws VersionException,
2270: LockException, ConstraintViolationException,
2271: RepositoryException;
2272:
2273: /**
2274: * A special kind of <code>remove()</code> that removes this node, but does
2275: * not remove any other node in the shared set of this node.
2276: * <p/>
2277: * All of the exceptions defined for <code>remove()</code> apply to this
2278: * function. In addition, a <code>RepositoryException</code> is thrown if
2279: * this node cannot be removed without removing another node in the shared
2280: * set of this node.
2281: * <p/>
2282: * If this node is not shared this method removes only this node.
2283: *
2284: * @throws VersionException
2285: * @throws LockException
2286: * @throws ConstraintViolationException
2287: * @throws RepositoryException
2288: * @see #removeSharedSet()
2289: * @see Item#remove()
2290: * @since JCR 2.0
2291: */
2292: public void removeShare() throws VersionException, LockException,
2293: ConstraintViolationException, RepositoryException;
2294:
2295: /**
2296: * Places a hold on this node and its properties (if <code>isDeep</code> is
2297: * <code>false</code>) or this node and its subtree (if <code>isDeep</code>
2298: * is <code>true</code>).
2299: * <p/>
2300: * The supplied <code>holdID</code> is added to the <code>jcr:hold</code>
2301: * multi-value property and the corresponding <code>jcr:isDeep</code> value
2302: * is set accordingly. The corresponding <code>jcr:isDeep</code> value is
2303: * the one with the same index as the <code>holdID</code> value.
2304: * <p/>
2305: * The format and interpretation of the <code>holdID</code> is not specified.
2306: * It is expected to be an identifier associated with the application placing
2307: * the hold.
2308: * <p/>
2309: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this
2310: * node is not of type <code>mix:managedRetention</code>.
2311: * <p/>
2312: * A <code>RepositoryException</code> is thrown if another error occurs.
2313: *
2314: * @param holdID a string
2315: * @param isDeep a boolean
2316: * @throws UnsupportedRepositoryOperationException if this node is not of
2317: * type <code>mix:managedRetention</code>.
2318: * @throws RepositoryException if another error occurs.
2319: * @since JCR 2.0
2320: */
2321: public void setHold(String holdID, boolean isDeep)
2322: throws UnsupportedRepositoryOperationException,
2323: RepositoryException;
2324:
2325: /**
2326: * Removes the specified <code>holdID</code> and the corresponding boolean
2327: * flag from the <code>jcr:hold</code> and <code>jcr:isDeep</code> properties
2328: * of this node, respectively.
2329: * <p/>
2330: * If this is the last <code>holdID</code> in the property then the hold on
2331: * this node is lifted.
2332: * <p/>
2333: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this
2334: * node is not of type <code>mix:managedRetention</code>.
2335: * <p/>
2336: * A <code>RepositoryException</code> is thrown if another error occurs.
2337: *
2338: * @param holdID a string
2339: * @throws UnsupportedRepositoryOperationException if this node is not of
2340: * type <code>mix:managedRetention</code>.
2341: * @throws RepositoryException if another error occurs.
2342: * @since JCR 2.0
2343: */
2344: public void removeHold(String holdID)
2345: throws UnsupportedRepositoryOperationException,
2346: RepositoryException;
2347:
2348: /**
2349: * Sets the retention policy of this node to that defined in the specified
2350: * policy node. Interpretation and enforcement of this policy is an
2351: * implementation issue.
2352: * <p/>
2353: * The <code>jcr:retentionPolicy</code> property of this node is set to
2354: * refer to the policy node.
2355: * <p/>
2356: * A <code>ConstraintViolationException</code> is thrown if the specified
2357: * node is not a valid retention policy node.
2358: * <p/>
2359: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this
2360: * node is not of type <code>mix:managedRetention</code>.
2361: * <p/>
2362: * A <code>RepositoryException</code> is thrown if another error occurs.
2363: *
2364: * @param policy a policy node
2365: * @throws ConstraintViolationException if the specified node is not a valid
2366: * retention policy node.
2367: * @throws UnsupportedRepositoryOperationException if this node is not of
2368: * type <code>mix:managedRetention</code>.
2369: * @throws RepositoryException if another error occurs.
2370: * @since JCR 2.0
2371: */
2372: public void setRetentionPolicy(Node policy)
2373: throws ConstraintViolationException,
2374: UnsupportedRepositoryOperationException,
2375: RepositoryException;
2376:
2377: /**
2378: * Causes the current retention policy on this node to no longer apply.
2379: * <p/>
2380: * Removes the <code>jcr:retentionPolicy</code> property from this node.
2381: * <p/>
2382: * A <code>ConstraintViolationException</code> is thrown if this node does
2383: * not have a retention policy currently assigned.
2384: * <p/>
2385: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this
2386: * node is not of type <code>mix:managedRetention</code>.
2387: * <p/>
2388: * A <code>RepositoryException</code> is thrown if another error occurs.
2389: *
2390: * @throws ConstraintViolationException if this node does not have a
2391: * retention policy currently assigned.
2392: * @throws UnsupportedRepositoryOperationException if this node is not of
2393: * type <code>mix:managedRetention</code>.
2394: * @throws RepositoryException if another error occurs.
2395: * @since JCR 2.0
2396: */
2397: public void removeRetentionPolicy()
2398: throws ConstraintViolationException,
2399: UnsupportedRepositoryOperationException,
2400: RepositoryException;
2401:
2402: /**
2403: * Returns <code>true</code> if this node is either
2404: * <ul>
2405: * <li/>versionable (full or simple) and currently checked-out,
2406: * <li/>non-versionable and its nearest versionable ancestor is checked-out or
2407: * <li/>non-versionable and it has no versionable ancestor.
2408: * </ul>
2409: * Returns <code>false</code> if this node is either
2410: * <ul>
2411: * <li/>versionable (full or simple) and currently checked-in or
2412: * <li/>non-versionable and its nearest versionable ancestor is checked-in.
2413: * </ul>
2414: *
2415: * @return a boolean
2416: * @throws RepositoryException If another error occurs.
2417: */
2418: public boolean isCheckedOut() throws RepositoryException;
2419:
2420: /**
2421: * Restores <code>this</code> node to the state defined by the
2422: * version with the specified <code>versionName</code>.
2423: * <p/>
2424: * If this node is not versionable, an
2425: * <code>UnsupportedRepositoryOperationException</code> is thrown.
2426: * <p/>
2427: * If successful, the change is persisted immediately and there is no
2428: * need to call <code>save</code>.
2429: * <p/>
2430: * A <code>VersionException</code> is thrown if no version with the specified <code>versionName</code>
2431: * exists in this node's version history or if an attempt is made to restore the root version
2432: * (<code>jcr:rootVersion</code>).
2433: * <p/>
2434: * An InvalidItemStateException is thrown if this <code>Session</code> (not necessarily this
2435: * <code>Node</code>) has pending unsaved changes.
2436: * <p/>
2437: * A LockException is thrown if a lock prevents the addition of the mixin.
2438: * <p/>
2439: * This method will work regardless of whether this node is checked-in or not.
2440: * <p/>
2441: * An identifier collision occurs when a node exists <i>outside the subtree rooted at this node</i>
2442: * with the same identifier as a node that would be introduced by the <code>restore</code>
2443: * operation <i>into the subtree at this node</i>. The result in such a case is governed by
2444: * the <code>removeExisting</code> flag. If <code>removeExisting</code> is <code>true</code>,
2445: * then the incoming node takes precedence, and the existing node (and its subtree) is removed
2446: * (if possible; otherwise a <code>RepositoryException</code> is thrown).
2447: * If <code>removeExisting</code> is <code>false</code>, then a <code>ItemExistsException</code>
2448: * is thrown and no changes are made. Note that this applies not only to cases where the restored
2449: * node itself conflicts with an existing node but also to cases where a conflict occurs with any
2450: * node that would be introduced into the workspace by the restore operation. In particular, conflicts
2451: * involving subnodes of the restored node that have <code>OnParentVersion</code> settings of
2452: * <code>COPY</code> or <code>VERSION</code> are also governed by the <code>removeExisting</code> flag.
2453: *
2454: * @param versionName a <code>Version</code> object
2455: * @param removeExisting a boolean flag that governs what happens in case of an identifier collision.
2456: * @throws UnsupportedRepositoryOperationException if this node is not versionable.
2457: * @throws VersionException if the specified <code>version</code> is not part of this node's version history
2458: * or if an attempt is made to restore the root version (<code>jcr:rootVersion</code>).
2459: * @throws ItemExistsException if <code>removeExisting</code> is <code>false</code> and an identifier collision occurs.
2460: * @throws LockException if a lock prevents the restore.
2461: * @throws InvalidItemStateException if this <code>Session</code> (not necessarily this <code>Node</code>) has pending unsaved changes.
2462: * @throws RepositoryException If another error occurs.
2463: */
2464: public void restore(String versionName, boolean removeExisting)
2465: throws VersionException, ItemExistsException,
2466: UnsupportedRepositoryOperationException, LockException,
2467: InvalidItemStateException, RepositoryException;
2468:
2469: /**
2470: * Restores <code>this</code> node to the state defined by the specified
2471: * <code>version</code>.
2472: * <p/>
2473: * If this node is not versionable, an
2474: * <code>UnsupportedRepositoryOperationException</code> is thrown.
2475: * <p/>
2476: * If successful, the change is persisted immediately and there is no
2477: * need to call <code>save</code>.
2478: * <p/>
2479: * A <code>VersionException</code> is thrown if the specified <code>version</code>
2480: * is not part of this node's version history or if an attempt is made to restore the root version (<code>jcr:rootVersion</code>).
2481: * <p/>
2482: * An InvalidItemStateException is thrown if this <code>Session</code> (not necessarily this
2483: * <code>Node</code>) has pending unsaved changes.
2484: * <p/>
2485: * A <code>LockException</code> is thrown if a lock prevents the restore.
2486: * <p/>
2487: * This method will work regardless of whether this node is checked-in or not.
2488: * <p/>
2489: * An identifier collision occurs when a node exists <i>outside the subtree rooted at this node</i>
2490: * with the same identifier as a node that would be introduced by the <code>restore</code>
2491: * operation <i>into the subtree at this node</i>. The result in such a case is governed by
2492: * the <code>removeExisting</code> flag. If <code>removeExisting</code> is <code>true</code>,
2493: * then the incoming node takes precedence, and the existing node (and its subtree) is removed
2494: * (if possible; otherwise a <code>RepositoryException</code> is thrown).
2495: * If <code>removeExisting</code> is <code>false</code>, then a <code>ItemExistsException</code>
2496: * is thrown and no changes are made. Note that this applies not only to cases where the restored
2497: * node itself conflicts with an existing node but also to cases where a conflict occurs with any
2498: * node that would be introduced into the workspace by the restore operation. In particular, conflicts
2499: * involving subnodes of the restored node that have <code>OnParentVersion</code> settings of
2500: * <code>COPY</code> or <code>VERSION</code> are also governed by the <code>removeExisting</code> flag.
2501: *
2502: * @param version a <code>Version</code> object
2503: * @param removeExisting a boolean flag that governs what happens in case of an identifier collision.
2504: * @throws UnsupportedRepositoryOperationException if this node is not versionable.
2505: * @throws VersionException if the specified <code>version</code> is not part of this node's version history
2506: * or if an attempt is made to restore the root version (<code>jcr:rootVersion</code>).
2507: * @throws ItemExistsException if <code>removeExisting</code> is <code>false</code> and an identifier collision occurs.
2508: * @throws InvalidItemStateException if this <code>Session</code> (not necessarily this <code>Node</code>)
2509: * has pending unsaved changes.
2510: * @throws LockException if a lock prevents the restore.
2511: * @throws RepositoryException if another error occurs.
2512: */
2513: public void restore(Version version, boolean removeExisting)
2514: throws VersionException, ItemExistsException,
2515: UnsupportedRepositoryOperationException, LockException,
2516: RepositoryException;
2517:
2518: /**
2519: * Restores the specified version to <code>relPath</code>, relative to this node.
2520: * <p/>
2521: * A node need not exist at relPath, though the parent of <code>relPath</code>
2522: * must exist, otherwise a <code>PathNotFoundException</code> is thrown.
2523: * <p/>
2524: * If a node <i>does</i> exist at relPath then it must correspond to the version being restored
2525: * (the version must be a version <i>of that node</i>) and must not be a root version
2526: * (<code>jcr:rootVersion</code>), otherwise a <code>VersionException</code>
2527: * is thrown.
2528: * <p/>
2529: * If no node exists at <code>relPath</code> then a <code>VersionException</code> is thrown if
2530: * the parent node of <code>relPath</code> is versionable and checked-in or is non-versionable but
2531: * its nearest versionable ancestor is checked-in.
2532: * <p/>
2533: * If there <i>is</i> a node at <code>relPath</code> then the checked-in status of that node
2534: * itself and the checked-in status of its parent are irrelevant. The restore will work even if
2535: * one or both are checked-in.
2536: * <p/>
2537: * An identifier collision occurs when a node exists <i>outside the subtree rooted at <code>relPath</code></i>
2538: * with the same identifier as a node that would be introduced by the <code>restore</code> operation
2539: * <i>into the subtree at <code>relPath</code></i> (Note that in cases where there is no node at
2540: * <code>relPath</code>, this amounts to saying that an identifier collsion occurs if there exists
2541: * a node <i>anywhere</i> in this workspace with the same identifier as a node that would be introduced by
2542: * the <code>restore</code>). The result in such a case is governed by the <code>removeExisting</code>
2543: * flag. If <code>removeExisting</code> is <code>true</code>, then the incoming node takes precedence,
2544: * and the existing node (and its subtree) is removed (if possible; otherwise
2545: * a <code>RepositoryException</code> is thrown). If <code>removeExisting</code> is
2546: * <code>false</code>, then a <code>ItemExistsException</code> is thrown and no changes are made.
2547: * Note that this applies not only to cases where the restored
2548: * node itself conflicts with an existing node but also to cases where a conflict occurs with any
2549: * node that would be introduced into the workspace by the restore operation. In particular, conflicts
2550: * involving subnodes of the restored node that have <code>OnParentVersion</code> settings of
2551: * <code>COPY</code> or <code>VERSION</code> are also governed by the <code>removeExisting</code> flag.
2552: * <p/>
2553: * If the would-be parent of the location <code>relPath</code> is actually a property, or if a node type
2554: * restriction would be violated, then a <code>ConstraintViolationException</code> is thrown.
2555: * <p/>
2556: * If the <code>restore</code> succeeds, the changes made to this node are persisted
2557: * immediately, there is no need to call <code>save</code>.
2558: * <p/>
2559: * An InvalidItemStateException is thrown if this <code>Session</code> (not necessarily this
2560: * <code>Node</code>) has pending unsaved changes.
2561: * <p/>
2562: * An <code>UnsupportedRepositoryOperationException</code> is thrown if versioning is not supported.
2563: * <p/>
2564: * A <code>LockException</code> is thrown if a lock prevents the restore.
2565: *
2566: * @param version a version object
2567: * @param relPath the path to which the version is to be restored
2568: * @param removeExisting overns what happens on identifier collision.
2569: * @throws PathNotFoundException if the parent of <code>relPath</code> does not exist.
2570: * @throws ItemExistsException if removeExisting is false and an identifier collision occurs
2571: * @throws ConstraintViolationException If the would-be parent of the location <code>relPath</code> is
2572: * actually a property, or if a node type restriction would be violated
2573: * @throws VersionException if the parent node of <code>relPath</code> is versionable and checked-in or is
2574: * non-versionable but its nearest versionable ancestor is checked-in or if a node exists at relPath that is not
2575: * the node corresponding to the specified <code>version</code> or if an attempt is made to restore the root version
2576: * (<code>jcr:rootVersion</code>).
2577: * @throws UnsupportedRepositoryOperationException if versioning is not supported.
2578: * @throws LockException if a lock prevents the restore.
2579: * @throws InvalidItemStateException if this <code>Session</code> (not necessarily this <code>Node</code>) has pending unsaved changes.
2580: * @throws RepositoryException if another error occurs
2581: */
2582: public void restore(Version version, String relPath,
2583: boolean removeExisting) throws PathNotFoundException,
2584: ItemExistsException, VersionException,
2585: ConstraintViolationException,
2586: UnsupportedRepositoryOperationException, LockException,
2587: InvalidItemStateException, RepositoryException;
2588:
2589: /**
2590: * Restores the version of this node with the specified version label.
2591: * If this node is not versionable, an
2592: * <code>UnsupportedRepositoryOperationException</code> is thrown.
2593: * If successful, the change is persisted immediately and there is no
2594: * need to call <code>save</code>.
2595: * <p/>
2596: * A <code>VersionException</code> is thrown if the specified <code>versionLabel</code>
2597: * does not exist in this node's version history.
2598: * <p/>
2599: * An InvalidItemStateException is thrown if this <code>Session</code> (not necessarily this
2600: * <code>Node</code>) has pending unsaved changes.
2601: * <p/>
2602: * A <code>LockException</code> is thrown if a lock prevents the restore.
2603: * <p/>
2604: * This method will work regardless of whether this node is checked-in or not.
2605: * <p/>
2606: * An identifier collision occurs when a node exists <i>outside the subtree rooted at this node</i>
2607: * with the same identifier as a node that would be introduced by the <code>restoreByLabel</code>
2608: * operation <i>into the subtree at this node</i>. The result in such a case is governed by
2609: * the <code>removeExisting</code> flag. If <code>removeExisting</code> is <code>true</code>,
2610: * then the incoming node takes precedence, and the existing node (and its subtree) is
2611: * removed (if possible; otherwise a <code>RepositoryException</code> is thrown). If
2612: * <code>removeExisting</code> is <code>false</code>, then a <code>ItemExistsException</code>
2613: * is thrown and no changes are made. Note that this applies not only to cases where the restored
2614: * node itself conflicts with an existing node but also to cases where a conflict occurs with any
2615: * node that would be introduced into the workspace by the restore operation. In particular, conflicts
2616: * involving subnodes of the restored node that have <code>OnParentVersion</code> settings of
2617: * <code>COPY</code> or <code>VERSION</code> are also governed by the <code>removeExisting</code> flag.
2618: *
2619: * @param versionLabel a String
2620: * @param removeExisting a boolean flag that governs what happens in case of an identifier collision.
2621: * @throws UnsupportedRepositoryOperationException if this node is not verisonable.
2622: * @throws VersionException if the specified <code>versionLabel</code>
2623: * does not exist in this node's version history.
2624: * @throws ItemExistsException if <code>removeExisting</code> is <code>false</code> and an identifier collision occurs.
2625: * @throws LockException if a lock prevents the restore.
2626: * @throws InvalidItemStateException if this <code>Session</code> (not necessarily this <code>Node</code>) has pending unsaved changes.
2627: * @throws RepositoryException If another error occurs.
2628: */
2629: public void restoreByLabel(String versionLabel,
2630: boolean removeExisting) throws VersionException,
2631: ItemExistsException,
2632: UnsupportedRepositoryOperationException, LockException,
2633: InvalidItemStateException, RepositoryException;
2634:
2635: /**
2636: * Returns the <code>VersionHistory</code> object of this node.
2637: * This object provides access to the <code>nt:versionHistory</code>
2638: * node holding this node's versions.
2639: * <p/>
2640: * If this node is not versionable, an <code>UnsupportedRepositoryOperationException</code> is thrown.
2641: *
2642: * @return a <code>VersionHistory</code> object
2643: * @throws UnsupportedRepositoryOperationException if this node is not versionable.
2644: * @throws RepositoryException If another error occurs.
2645: */
2646: public VersionHistory getVersionHistory()
2647: throws UnsupportedRepositoryOperationException,
2648: RepositoryException;
2649:
2650: /**
2651: * Returns the current base version of this versionable node.
2652: * <p/>
2653: * If this node is not versionable, an <code>UnsupportedRepositoryOperationException</code> is thrown.
2654: *
2655: * @return a <code>Version</code> object.
2656: * @throws UnsupportedRepositoryOperationException
2657: * if this node is not versionable.
2658: * @throws RepositoryException If another error occurs.
2659: */
2660: public Version getBaseVersion()
2661: throws UnsupportedRepositoryOperationException,
2662: RepositoryException;
2663:
2664: /**
2665: * Places a lock on this node. If successful, this node is said to <i>hold</i> the lock.
2666: * <p/>
2667: * If <code>isDeep</code> is <code>true</code> then the lock applies to this node and all its descendant nodes;
2668: * if <code>false</code>, the lock applies only to this, the holding node.
2669: * <p/>
2670: * If <code>isSessionScoped</code> is <code>true</code> then this lock will expire upon the expiration of the current
2671: * session (either through an automatic or explicit <code>Session.logout</code>); if <code>false</code>, this lock
2672: * does not expire until explicitly unlocked or automatically unlocked due to a implementation-specific limitation,
2673: * such as a timeout.
2674: * <p/>
2675: * Returns a <code>Lock</code> object reflecting the state of the new lock.
2676: * <p/>
2677: * If the lock is open-scoped the returned lock will include a lock token.
2678: * <p/>
2679: * The lock token is also automatically added to the set of lock tokens held by the current <code>Session</code>.
2680: * <p/>
2681: * If successful, then the property <code>jcr:lockOwner</code> is created and set to the value of
2682: * <code>Session.getUserID</code> for the current session and the property <code>jcr:lockIsDeep</code> is set to the
2683: * value passed in as <code>isDeep</code>. These changes are persisted automatically; there is no need to call
2684: * <code>save</code>.
2685: * <p/>
2686: * Note that it is possible to lock a node even if it is checked-in (the lock-related properties will be changed
2687: * despite the checked-in status).
2688: * <p/>
2689: * If this node is not of mixin node type <code>mix:lockable</code> then an
2690: * <code>LockException</code> is thrown.
2691: * <p/>
2692: * If this node is already locked (either because it holds a lock or a lock above it applies to it),
2693: * a <code>LockException</code> is thrown.
2694: * <p/>
2695: * If <code>isDeep</code> is <code>true</code> and a descendant node of this node already holds a lock, then a
2696: * <code>LockException</code> is thrown.
2697: * <p/>
2698: * If this node does not have a persistent state (has never been saved
2699: * or otherwise persisted), a <code>LockException</code> is thrown.
2700: * <p/>
2701: * If the current session does not have sufficient privileges to place the lock, an
2702: * <code>AccessDeniedException</code> is thrown.
2703: * <p/>
2704: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this implementation does not support locking.
2705: * <p/>
2706: * An InvalidItemStateException is thrown if this node has pending unsaved changes.
2707: * <p/>
2708: * A <code>RepositoryException</code> is thrown if another error occurs.
2709: *
2710: * @param isDeep if <code>true</code> this lock will apply to this node and all its descendants; if
2711: * <code>false</code>, it applies only to this node.
2712: * @param isSessionScoped if <code>true</code>, this lock expires with the current session; if <code>false</code> it
2713: * expires when explicitly or automatically unlocked for some other reason.
2714: * @return A <code>Lock</code> object containing a lock token.
2715: * @throws UnsupportedRepositoryOperationException if this implementation does not support locking.
2716: * @throws LockException if this node is not <code>mix:lockable</code> or this node is already locked or
2717: * <code>isDeep</code> is <code>true</code> and a descendant node of this node already holds a lock.
2718: * @throws AccessDeniedException if this session does not have permission to lock this node.
2719: * @throws InvalidItemStateException if this node has pending unsaved changes.
2720: * @throws RepositoryException if another error occurs.
2721: */
2722: public Lock lock(boolean isDeep, boolean isSessionScoped)
2723: throws UnsupportedRepositoryOperationException,
2724: LockException, AccessDeniedException,
2725: InvalidItemStateException, RepositoryException;
2726:
2727: /**
2728: * Returns the <code>Lock</code> object that applies to this node. This may be either a lock on this node itself
2729: * or a deep lock on a node above this node.
2730: * <p/>
2731: * If the current session holds the lock token for this lock, then the returned <code>Lock</code> object contains
2732: * that lock token (accessible through <code>Lock.getLockToken</code>). If this <code>Session</code>
2733: * does not hold the applicable lock token, then the returned <code>Lock</code> object will not
2734: * contain the lock token (its <code>Lock.getLockToken</code> method will return <code>null</code>).
2735: * <p/>
2736: * If this node is not locked (no lock applies to this node), a <code>LockException</code> is thrown.
2737: * <p/>
2738: * If the current session does not have sufficient privileges to get the lock, an <code>AccessDeniedException</code>
2739: * is thrown.
2740: * <p/>
2741: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this implementation does not support locking.
2742: * <p/>
2743: * A <code>RepositoryException</code> is thrown if another error occurs.
2744: *
2745: * @return The applicable <code>Lock</code> object, without a contained lock token.
2746: * @throws UnsupportedRepositoryOperationException if this implementation does not support locking.
2747: * @throws LockException if no lock applies to this node.
2748: * @throws AccessDeniedException if the curent session does not have pernmission to get the lock.
2749: * @throws RepositoryException if another error occurs.
2750: */
2751: public Lock getLock()
2752: throws UnsupportedRepositoryOperationException,
2753: LockException, AccessDeniedException, RepositoryException;
2754:
2755: /**
2756: * Removes the lock on this node. Also removes the properties <code>jcr:lockOwner</code> and
2757: * <code>jcr:lockIsDeep</code> from this node. These changes are persisted automatically; there is no need to call
2758: * <code>save</code>. As well, the corresponding lock token is removed from the set of lock tokens held by the current
2759: * <code>Session</code>.
2760: * <p/>
2761: * If this node does not currently hold a lock or
2762: * holds a lock for which this <code>Session</code> is not the owner,
2763: * then a <code>LockException</code> is thrown. Note however that the system
2764: * may give permission to a non-owning session to unlock a lock. Typically
2765: * such "lock-superuser" capability is intended to facilitate administrational
2766: * clean-up of orphaned open-scoped locks.
2767: * <p/>
2768: * Note that it is possible to unlock a node even if it is checked-in (the lock-related properties will be changed
2769: * despite the checked-in status).
2770: * <p/>
2771: * If the current session does not
2772: * have sufficient privileges to remove the lock, an <code>AccessDeniedException</code> is thrown.
2773: * <p/>
2774: * An <code>InvalidItemStateException</code> is thrown if this node has pending unsaved changes.
2775: * <p/>
2776: * An <code>UnsupportedRepositoryOperationException</code> is thrown if this implementation does not support locking.
2777: * <p/>
2778: * A <code>RepositoryException</code> is thrown if another error occurs.
2779: *
2780: * @throws UnsupportedRepositoryOperationException if this implementation does not support locking.
2781: * @throws LockException if this node does not currently hold a lock or holds a lock for which this Session does not have the correct lock token
2782: * @throws AccessDeniedException if the current session does not have permission to unlock this node.
2783: * @throws InvalidItemStateException if this node has pending unsaved changes.
2784: * @throws RepositoryException if another error occurs.
2785: */
2786: public void unlock()
2787: throws UnsupportedRepositoryOperationException,
2788: LockException, AccessDeniedException,
2789: InvalidItemStateException, RepositoryException;
2790:
2791: /**
2792: * Returns <code>true</code> if this node holds a lock; otherwise returns <code>false</code>. To <i>hold</i> a
2793: * lock means that this node has actually had a lock placed on it specifically, as opposed to just having a lock
2794: * <i>apply</i> to it due to a deep lock held by a node above.
2795: *
2796: * @return a <code>boolean</code>.
2797: * @throws RepositoryException if an error occurs.
2798: */
2799: public boolean holdsLock() throws RepositoryException;
2800:
2801: /**
2802: * Returns <code>true</code> if this node is locked either as a result of a lock held by this node or by a deep
2803: * lock on a node above this node; otherwise returns <code>false</code>.
2804: *
2805: * @return a <code>boolean</code>.
2806: * @throws RepositoryException if an error occurs.
2807: */
2808: public boolean isLocked() throws RepositoryException;
2809:
2810: /**
2811: * Causes the lifecycle state of this node to undergo the specified
2812: * <code>transition</code>.
2813: * <p/>
2814: * This method may change the value of the <code>jcr:currentLifecycleState</code>
2815: * property, in most cases it is expected that the implementation will change
2816: * the value to that of the passed <code>transition</code> parameter, though
2817: * this is an implementation-specific issue. If the <code>jcr:currentLifecycleState</code>
2818: * property is changed the change is persisted immediately, there is no need
2819: * to call <code>save</code>.
2820: * <p/>
2821: * Throws an <code>UnsupportedRepositoryOperationException</code> if this
2822: * implementation does not support lifecycle actions or if this node does
2823: * not have the <code>mix:lifecycle</code> mixin.
2824: * <p/>
2825: * Throws <code>InvalidLifecycleTransitionException</code> if the lifecycle
2826: * transition is not successful.
2827: *
2828: * @param transition a state transition
2829: * @throws UnsupportedRepositoryOperationException if this implementation does
2830: * not support lifecycle actions or if this node does not have the
2831: * <code>mix:lifecycle</code> mixin.
2832: * @throws InvalidLifecycleTransitionException if the lifecycle transition is not successful.
2833: * @throws RepositoryException if another error occurs.
2834: * @since JCR 2.0
2835: */
2836: public void followLifecycleTransition(String transition)
2837: throws UnsupportedRepositoryOperationException,
2838: InvalidLifecycleTransitionException, RepositoryException;
2839:
2840: /**
2841: * Returns the list of valid state transitions for this node.
2842: *
2843: * @return a <code>String</code> array.
2844: * @throws UnsupportedRepositoryOperationException if this implementation does
2845: * not support lifecycle actions or if this node does not have the
2846: * <code>mix:lifecycle</code> mixin.
2847: * @throws RepositoryException if another error occurs.
2848: * @since JCR 2.0
2849: */
2850: public String[] getAllowedLifecycleTransistions()
2851: throws UnsupportedRepositoryOperationException,
2852: RepositoryException;
2853: }
|