senselogic.sitevision.api.metadata

Interface MetadataUtil

@Requireable(value="MetadataUtil")
public interface MetadataUtil

Utility used to handle metadata. Due to the nature of the Sitevision metadata it is not suited to alter the values using JCR (i.e. due to inheritance). This utility adds the functionality needed to access and alter metadata.

Note that any metadata value is available as property on a JCR-node.

An instance of the Sitevision class implementing this interface can be obtained via Utils.getMetadataUtil(). See Utils for how to obtain an instance of the Utils interface.

Since:

Sitevision 2.6.1

Author:

Mikael Wikblom

Method Summary

Modifier and Type	Method and Description
Node	getLinkMetadataPropertyValue(Node aNode, String aPropertyName) Returns a Node for a link metadata on a specified Node.
LinkValueBuilder	getLinkValueBuilder() Returns a link value builder that can be used to build LinkValue instances.
List	getRelatedMetadataPropertyValues(Node aNode, String aPropertyName) Returns a List containing all related metadata values for a specified Node.
RelatedValueBuilder	getRelatedValueBuilder() Returns a related value builder that can be used to build RelatedValue instances.
boolean	isMetadataValueInherited(Node aNode, Property aProperty) Returns a boolean indicating that the metadata value on the Node is inherited from a parent node.
boolean	isMetadataValueInherited(Node aNode, Property aProperty, int aVersion) Returns a boolean indicating that the metadata value in a specified version on the Node is inherited from a parent node.
boolean	isMetadataValueInherited(Node aNode, String aPropertyName) Returns a boolean indicating that the metadata value on the Node is inherited from a parent node.
boolean	isMetadataValueInherited(Node aNode, String aPropertyName, int aVersion) Returns a boolean indicating that the metadata value in a specified version on the Node is inherited from a parent node.
void	removeMetadataPropertyValue(Node aNode, Property aProperty) Removes a metadata Property value on a Node.
void	removeMetadataPropertyValue(Node aNode, String aPropertyName) Removes a metadata Property value on a Node.
void	setMetadataPropertyValue(Node aNode, Property aProperty, Object aValue) Set a new value to a metadata Property on a Node.
void	setMetadataPropertyValue(Node aNode, String aPropertyName, Object aValue) Set a new value to a metadata Property on a Node.

Method Detail

setMetadataPropertyValue

void setMetadataPropertyValue(Node aNode,
                              Property aProperty,
                              Object aValue)
                       throws LockException,
                              RepositoryException

Set a new value to a metadata Property on a Node. The node must be of such a type where it is possible to define a metadata value (e.g. page, article, template, file, image) or an IllegalArgumentException will be thrown.

For comprehensive information about supported metadata see alternate method setMetadataPropertyValue(javax.jcr.Node, String, Object).

Important note! This method operates in the VersionUtil.OFFLINE_VERSION. Hence, if you set a metadata value, aNode must be published (see PublishingUtil) to have any effect in the VersionUtil.ONLINE_VERSION

Parameters:

aNode - the Node where the metadata value should be altered. May not be null

aProperty - the Property that should be altered. May not be null

aValue - the new value. May not be null

Throws:

LockException - is thrown if the specified is locked for editing (i.e. someone else is currently editing the same node)

RepositoryException - if anything goes wrong

See Also:

setMetadataPropertyValue(javax.jcr.Node, String, Object)

setMetadataPropertyValue

void setMetadataPropertyValue(Node aNode,
                              String aPropertyName,
                              Object aValue)
                       throws LockException,
                              RepositoryException

Set a new value to a metadata Property on a Node. The node must be of such a type where it is possible to define a metadata value (e.g. page, article, template, file, image) or an IllegalArgumentException will be thrown.

This method currently supports alternation of the following metadata types:

• text
  The value will be handled as string (i.e. toString).
• single alternative
  The value must be a valid alternative, or the metadata definition must support 'other' values. If not, an UnsupportedOperationException is thrown. The value is handled as a string (i.e. toString).
• multiple alternative
  The value must be a valid alternative, or the metadata definition must support 'other' values. Any invalid value will be ignored. If no valid alternatives are provided an UnsupportedOperationException is thrown. The value is a comma separated string of the alternatives. It is also possible to provide a collection or an array of strings corresponding to the alternatives.
• date
  The value must be a Date, Calendar, Long, Integer or Double. If no valid value is provided an UnsupportedOperationException is thrown.
• user
  The value must be a Node (of type sv:user or sv:simpleUser) or an id String to a JCR-node corresponding to the designated user. If no valid value is provided an UnsupportedOperationException is thrown.
• directory object
  The value must be a Node (of type sv:user, sv:userGroup or sv:userContainer) or an id String to a JCR-node corresponding to the designated directory object. It is also possible to provide a collection, an array of such objects or a comma separated list of ids. If no valid value is provided an UnsupportedOperationException is thrown.
• link
  The value must be a LinkValue (since Sitevision 3.6), a Node or an id String to a JCR-node that can be used as link (e.g. page, article, image, file). If no valid value is provided an UnsupportedOperationException is thrown.
• link to portlet (since Sitevision 2.6.2)
  The value will be handled as string (i.e. toString).
• number (since Sitevision 2.6.2)
  The value must be a Number (e.g. Integer, Long, Double etc.) or the toString() method of the value must be parseable as an int (i.e. Integer.parseInt(aValue.toString()) must not throw a NumberFormatException). If no valid value is provided an UnsupportedOperationException is thrown.
• related (since Sitevision 3.6)
  The value must be a RelatedValue. If no valid value is provided an UnsupportedOperationException is thrown.
• single tag (since Sitevision 7.2)
  The value must be a valid tag, or the metadata definition must allow custom tags. If not, an UnsupportedOperationException is thrown. The value must be of type sv:tag or a tag name as a String.
• multiple tags (since Sitevision 7.2)
  The value must be a valid tag, or the metadata definition must allow custom tags. Any invalid tags will be ignored. If no valid tags are provided an UnsupportedOperationException is thrown. The value is a comma separated string of the tag names. Note that tag names provided as a comma separated string must be prefixed with #. It is also possible to provide a collection or an array of sv:tag or strings of tag names.

Important note! This method operates in the VersionUtil.OFFLINE_VERSION. Hence, if you set a metadata value, aNode must be published (see PublishingUtil) to have any effect in the VersionUtil.ONLINE_VERSION

Throws NullPointerException or IllegalArgumentException if an illegal argument is provided. Throws UnsupportedOperationException if an invalid value or metadata property type is specified. Throws ConstraintViolationException (i.e. a RepositoryException) if current user doesn't have permission to write metadata on the node.

Parameters:

aNode - the Node where the metadata value should be altered. May not be null

aPropertyName - the name of the metadata property that should be altered. May not be null

aValue - the new value. May not be null

Throws:

LockException - is thrown if the specified node is locked for editing (i.e. someone else is currently editing the same node)

RepositoryException - if anything goes wrong

See Also:

setMetadataPropertyValue(javax.jcr.Node, javax.jcr.Property, Object)

removeMetadataPropertyValue

void removeMetadataPropertyValue(Node aNode,
                                 Property aProperty)
                          throws RepositoryException

Removes a metadata Property value on a Node. The node must be of such a type where it is possible to define a metadata value (e.g. page, article, template, file, image) or an IllegalArgumentException will be thrown.

For comprehensive information, see alternate method removeMetadataPropertyValue(Node, String)

.

Important note! This method operates in the VersionUtil.OFFLINE_VERSION. Hence, if you remove a metadata value, aNode must be published (see PublishingUtil) to have any effect in the VersionUtil.ONLINE_VERSION

Parameters:

aNode - the Node where the metadata value should be removed. May not be null

aProperty - the Property that should be removed. May not be null

Throws:

RepositoryException - if anything goes wrong

See Also:

removeMetadataPropertyValue(javax.jcr.Node, String)

removeMetadataPropertyValue

void removeMetadataPropertyValue(Node aNode,
                                 String aPropertyName)
                          throws RepositoryException

Removes a metadata Property value on a Node. The node must be of such a type where it is possible to define a metadata value (e.g. page, article, template, file, image) or an IllegalArgumentException will be thrown.

Due to the hierarchical nature of the metadata and the inheritance mechanism, a removal of a value does not necessarily mean that the value is removed (it may then be inherited from a parent node)

Note that the result of removal of a text metadata on the node where the metadata definition is defined is not the null value but an empty String. This means that the JCR property will be available after the removal and contain "" as value.

Important note! This method operates in the VersionUtil.OFFLINE_VERSION. Hence, if you remove a metadata value, aNode must be published (see PublishingUtil) to have any effect in the VersionUtil.ONLINE_VERSION

Throws NullPointerException or IllegalArgumentException if illegal arguments are used. Throws ConstraintViolationException (i.e. a RepositoryException) if current user doesn't have permission to write metadata on the node.

Parameters:

aNode - the Node where the metadata value should be removed. May not be null

aPropertyName - the name of the metadata property that should be removed. May not be null

Throws:

RepositoryException - if anything goes wrong

See Also:

removeMetadataPropertyValue(javax.jcr.Node, javax.jcr.Property)

isMetadataValueInherited

boolean isMetadataValueInherited(Node aNode,
                                 Property aProperty)
                          throws RepositoryException

Returns a boolean indicating that the metadata value on the Node is inherited from a parent node.

Note that this method returns true when the metadata definition is defined on the Node and the value is null

Important note! This method operates in the VersionUtil.OFFLINE_VERSION

Parameters:

aNode - the Node that contains the metadata value. May not be null

aProperty - the metadata Property that should be queried. May not be null

Returns:

a boolean indicating the inheritance

Throws:

RepositoryException - if anything goes wrong

See Also:

isMetadataValueInherited(javax.jcr.Node, javax.jcr.Property, int)

isMetadataValueInherited

boolean isMetadataValueInherited(Node aNode,
                                 Property aProperty,
                                 int aVersion)
                          throws RepositoryException

Returns a boolean indicating that the metadata value in a specified version on the Node is inherited from a parent node.

Note that this method returns true when the metadata definition is defined on the Node and the value is null

Parameters:

aNode - the Node that contains the metadata value. May not be null

aProperty - the metadata Property that should be queried. May not be null

aVersion - VersionUtil.OFFLINE_VERSION or VersionUtil.ONLINE_VERSION

Returns:

a boolean indicating the inheritance

Throws:

RepositoryException - if anything goes wrong

Since:

Sitevision 2.6.1_04

isMetadataValueInherited

boolean isMetadataValueInherited(Node aNode,
                                 String aPropertyName)
                          throws RepositoryException

Returns a boolean indicating that the metadata value on the Node is inherited from a parent node.

Note that this method returns true when the metadata definition is defined on the Node and the value is null

Important note! This method operates in the VersionUtil.OFFLINE_VERSION

Parameters:

aNode - the Node that contains the metadata value. May not be null

aPropertyName - the name of the metadata property that should be queried. May not be null

Returns:

a boolean indicating the inheritance

Throws:

RepositoryException - if anything goes wrong

See Also:

isMetadataValueInherited(javax.jcr.Node, String, int)

isMetadataValueInherited

boolean isMetadataValueInherited(Node aNode,
                                 String aPropertyName,
                                 int aVersion)
                          throws RepositoryException

Returns a boolean indicating that the metadata value in a specified version on the Node is inherited from a parent node.

Note that this method returns true when the metadata definition is defined on the Node and the value is null

Parameters:

aNode - the Node that contains the metadata value. May not be null

aPropertyName - the name of the metadata property that should be queried. May not be null

aVersion - VersionUtil.OFFLINE_VERSION or VersionUtil.ONLINE_VERSION

Returns:

a boolean indicating the inheritance

Throws:

RepositoryException - if anything goes wrong

Since:

Sitevision 2.6.1_04

getRelatedMetadataPropertyValues

List getRelatedMetadataPropertyValues(Node aNode,
                                      String aPropertyName)
                               throws RepositoryException

Returns a List containing all related metadata values for a specified Node.

Important note! The returned List is not type safe and my contain either a Node and/or a String depending on its findings.

Parameters:

aNode - the Node that contains the metadata value. May not be null

aPropertyName - the name of the metadata property that should be queried. May not be null

Returns:

a List containing all related metadata values, or an empty List if no could be found.

Throws:

NullPointerException - if aNode or aPropertyName is null.

IllegalArgumentException - if aNode is of wrong type (a node that doesn't have metadata).

RepositoryException - if anything goes wrong while accessing aNode or extracting the result

Since:

Sitevision 2.6.2_03

getLinkMetadataPropertyValue

Node getLinkMetadataPropertyValue(Node aNode,
                                  String aPropertyName)
                           throws RepositoryException

Returns a Node for a link metadata on a specified Node.

Important note! The nodes returned by this method are temporary objects and are not part of the Sitevision model. This means that methods like Item.getPath(), Item.getParent() and Item.getName() etc. will not return any information.

Parameters:

aNode - the Node that contains the link metadata value. May not be null

aPropertyName - the name of the link metadata property that should be queried. May not be null

Returns:

a temporary Node representing the link metadata value, or null if no link could be found.

Throws:

NullPointerException - if aNode or aPropertyName is null.

IllegalArgumentException - if aNode is of wrong type (a node that doesn't have metadata).

RepositoryException - if anything goes wrong while accessing aNode or extracting the result

Since:

Sitevision 3.1

getLinkValueBuilder

LinkValueBuilder getLinkValueBuilder()

Returns a link value builder that can be used to build LinkValue instances.

Tip! A LinkValue can be used to set a link metadata via setMetadataPropertyValue(javax.jcr.Node, String, Object) or setMetadataPropertyValue(javax.jcr.Node, javax.jcr.Property, Object).

Returns:

a link value builder.

Since:

Sitevision 3.6

getRelatedValueBuilder

RelatedValueBuilder getRelatedValueBuilder()

Returns a related value builder that can be used to build RelatedValue instances.

Tip! A RelatedValue can be used to set a related metadata via setMetadataPropertyValue(javax.jcr.Node, String, Object) or setMetadataPropertyValue(javax.jcr.Node, javax.jcr.Property, Object).

Returns:

a related value builder.

Since:

Sitevision 3.6