Source Code Cross Referenced for Node.java in  » 6.0-JDK-Modules » jsr-283 » javax » jcr » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules » jsr 283 » javax.jcr 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


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:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.