7.1.5 Adding and Writing Properties

To add new properties or change the values of existing properties of a node we use the setProperty methods of Node:

javax.jcr.
Node

Property

setProperty(String name,
Value value)

Sets the specified (single value) property of this node to the specified value. If the property does not yet exist, it is created. The property type of the property will be that specified by the node type of this node.

If the property type of the supplied Value object is different from that required, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not indicate a specific property type, then the property type of the supplied Value object is used and if the property already exists (has previously been set) it assumes both the new value and new property type.

If the property is multi-valued, a ValueFormatException is thrown.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value)null) would remove property called "P" of the node in N.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope: that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately (by this method), or on save, if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately (by this method), or on save, if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately (by this method), or on save, if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

A RepositoryException is thrown if another error occurs.

Property

setProperty(String name, Value[] values)

Sets the specified (multi-value) property to the specified array of values. If the property does not yet exist, it is created. Same as

setProperty(String name, Value value)

except that an array of Value objects is assigned instead of a single Value.

The property type of the property will be that specified by the node type of this node. If the property type of the supplied Value objects is different from that required, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. All Value objects in the array must be of the same type, otherwise a ValueFormatException is thrown. If the property is not multi-valued then a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not indicate a specific property type, then the property type of the supplied Value objects is used and if the property already exists it assumes both the new values and the new property type.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value[])null) would remove property called "P" of the node in N.

Note that this is different from passing an array that contains null elements. In such a case, the array is compacted by removing the nulls. The resulting set of values of the property never contains nulls. However, the set may be empty: N.setProperty("P", new Value[]{null}) would set the property to the empty set of values.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope: that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately (by this method), or on save, if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately (by this method), or on save, if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately (by this method), or on save, if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

A RepositoryException is thrown if another error occurs.

Property

setProperty(String name,
Value[] values,
int type)

Sets the specified (multi-value) property to the specified array of values. If the property does not yet exist, it is created. The type of the property is determined by the type parameter specified.

If the property type of the supplied Value objects is different from that specified, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown.

If the property already exists it assumes both the new values and the new property type.

All Value objects in the array must be of the same type, otherwise a ValueFormatException is thrown. If the property is not multi-valued then a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value[])null, type) would remove property called "P" of the node in N.

Note that this is different from passing an array that contains null elements. In such a case, the array is compacted by removing the nulls. The resulting set of values of the property never contains nulls. However, the set may be empty: N.setProperty("P", new Value[]{null}, type) would set the property to the empty set of values.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope: that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately (by this method), or on save, if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately (by this method), or on save, if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately (by this method), or on save, if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

A RepositoryException is thrown if another error occurs.

Property

setProperty(String name, String[] values)

Sets the specified property to the specified array of values. Same as

setProperty(String name, Value[] values)

except that the values are specified as String objects instead of Value objects.

Property

setProperty(String name,
String[] values,
int type)

Sets the specified property to the specified array of values and to the specified type. Same as

setProperty(String name,
Value[] values,
int type)

except that the values are specified as String objects instead of Value objects.

Property

setProperty(String name,
Value value,
int type)

Sets the specified (single-value) property to the specified value. If the property does not yet exist, it is created. The type of the property is determined by the type parameter specified.

If the property type of the supplied Value object is different from that required, then a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown.

If the property is not single-valued then a ValueFormatException is also thrown.

If the property already exists it assumes both the new value and the new property type.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Value)null, type) would remove property called "P" of the node in N.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope: that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

A ConstraintViolationException will be thrown either immediately (by this method), or on save, if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately (by this method), or on save, if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately (by this method), or on save, if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

If another error occurs, a RepositoryException is thrown.

Property

setProperty(String name,
String value,
int type)

Sets the specified property to the specified value. Same as

setProperty(String name,
Value value,
int type)

except that the value is specified as a String object instead of a Value object.

Property

setProperty(String name, String value)

setProperty(String name, InputStream value)

setProperty(String name, boolean value)

setProperty(String name, Calendar value)

setProperty(String name, double value)

setProperty(String name, long value)

setProperty(String name, Node value)

Sets the specified property to the specified value. In the context of these methods, each Java type implies a particular property type. The correspondence is:

String: PropertyType.STRING

InputStream: PropertyType.BINARY

boolean: PropertyType.BOOLEAN

Calendar: PropertyType.DATE

double: PropertyType.DOUBLE

long: PropertyType.LONG

Node: PropertyType.REFERENCE

In the case of the signature that takes a Node, the REFERENCE property in question is set to refer to the supplied node (see 6.2.5.4 Reference).

The property type of the property being set is determined by the node type of this node. If this property type is something other than that implied by the (Java) type of the passed value, a best-effort conversion is attempted. If the conversion fails, a ValueFormatException is thrown. If the property is multi-valued, a ValueFormatException is also thrown. If another error occurs, a RepositoryException is thrown.

If the node type of this node does not specify a particular property type for the property being set then the property type implied by the (Java) type of the passed value is used and if the property already exists (has previously been set) it assumes both the new value and new type.

Passing a null as the second parameter removes the property. It is equivalent to calling remove on the Property object itself. For example, N.setProperty("P", (Calendar)null) would remove property called "P" of the node in N. Obviously, a null cannot be passed to the signatures that take the primitive types boolean, long or double.

To save the addition or removal of a property, a save call must be performed that includes the parent of the property in its scope: that is, a save on either the session, this node, or an ancestor of this node. To save a change to an existing property, a save call that includes that property in its scope is required. This means that in addition to the above-mentioned save options, a save on the changed property itself will also work.

To create a property of PropertyType.NAME or PropertyType.PATH an explicit type must be specified using a three-argument signature.

A ConstraintViolationException will be thrown either immediately (by this method), or on save, if the change would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately (by this method), or on save, if this node is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately (by this method), or on save, if a lock prevents the setting of the property. Implementations may differ on when this validation is performed.

A RepositoryException is thrown if another error occurs.


To change the value of a property that has already been retrieved you can also use the setValue methods in the Property Interface itself:

javax.jcr.
Property

void

setValue(Value value)

setValue(Value[] values)

setValue(String value)

setValue(String[] values)

setValue(InputStream value)

setValue(double value)

setValue(long value)

setValue(Calendar value)

setValue(boolean value)

setValue(Node node)

Sets the value of this Property to the specified value. The behavior of these methods is identical with their corresponding Node.setProperty signature.