org.jboss.dna.graph.property
Interface Property

All Superinterfaces:

Comparable<Property>, Iterable<Object>

All Known Implementing Classes:

BasicEmptyProperty, BasicMultiValueProperty, BasicProperty, BasicSingleValueProperty

@Immutable
public interface Property
extends Iterable<Object>, Comparable<Property>

Representation of a property consisting of a name and value(s). Note that this property is immutable, meaning that the property values may not be changed through this interface.

This class is designed to be used with the ValueFactories interface and the particular ValueFactory that corresponds to the type of value you'd like to use. The ValueFactory will then return the values (if no type conversion is required) or will convert the values using the appropriate conversion algorithm.

The following example shows how to obtain the String representations of the property values:

   ValueFactories valueFactories = ...
   Property property = ...
   Iterator<String> iter = valueFactories.getStringFactory().create(property.getValues());
   while ( iter.hasNext() ) {
       System.out.println(iter.next());
   }
 

Meanwhile, the long value factory converts the values to long, the date value factory converts the values to DateTime instances, and so on.

This technique is much better and far safer than casting the values. It is possible that some Property instances contain heterogeneous values, so casting may not always work. Also, this technique guarantees that the values are properly converted if the type is not what you expected.

Author:

Randall Hauch

Method Summary

Object	getFirstValue() Obtain the property's first value in its natural form.
Name	getName() Get the name of the property.
String	getString() Get the string form of the property, using the default encoder.
String	getString(NamespaceRegistry namespaceRegistry) Get the string form of the property, using the supplied namespace registry to convert the property's name and values.
String	getString(NamespaceRegistry namespaceRegistry, TextEncoder encoder) Get the encoded string form of the property, using the supplied namespace registry to convert the property's namespace URIs to prefixes and the supplied encoder to encode characters in the property's name and values.
String	getString(NamespaceRegistry namespaceRegistry, TextEncoder encoder, TextEncoder delimiterEncoder) Get the encoded string form of the property, using the supplied namespace registry to convert the property's namespace URIs to prefixes and the supplied encoder to encode characters in the property's name and values.
String	getString(TextEncoder encoder) Get the encoded string form of the property, using the supplied encoder to encode characters in the property's name and values.
Iterator<?>	getValues() Obtain the property's values in their natural form.
Object[]	getValuesAsArray() Obtain the property's values as an array of objects in their natural form.
boolean	isEmpty() Determine whether this property has no actual values.
boolean	isMultiple() Determine whether the property currently has multiple values.
boolean	isSingle() Determine whether the property currently has a single value.
int	size() Get the number of actual values in this property.

Methods inherited from interface java.lang.Iterable

iterator

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getName

Name getName()

Get the name of the property.

Returns:

the property name; never null

size

int size()

Get the number of actual values in this property. If the property allows multiple values, then this method may return a value greater than 1. If the property only allows a single value, then this method will return either 0 or 1. This method may return 0 regardless of whether the property allows a single value, or multiple values.

Returns:

the number of actual values in this property; always non-negative

isMultiple

boolean isMultiple()

Determine whether the property currently has multiple values.

Returns:

true if the property has multiple values, or false otherwise.

See Also:

isSingle(), isEmpty()

isSingle

boolean isSingle()

Determine whether the property currently has a single value.

Returns:

true if the property has a single value, or false otherwise.

See Also:

isMultiple(), isEmpty()

isEmpty

boolean isEmpty()

Determine whether this property has no actual values. This method may return true regardless of whether the property allows a single value, or multiple values.

This method is a convenience method that is equivalent to size() == 0.

Returns:

true if this property has no values, or false otherwise

See Also:

isMultiple(), isSingle()

getFirstValue

Object getFirstValue()

Obtain the property's first value in its natural form. This is equivalent to calling isEmpty() ? null : iterator().next()

Returns:

the first value, or null if the property is empty

See Also:

Iterable.iterator(), getValues(), getValuesAsArray(), isEmpty()

getValues

Iterator<?> getValues()

Obtain the property's values in their natural form. This is equivalent to calling iterator().

A valid iterator is returned if the property has single valued or multi-valued.

The resulting iterator is immutable, and all property values are immutable.

Returns:

an iterator over the values; never null

See Also:

getFirstValue(), Iterable.iterator(), getValuesAsArray(), ValueFactory.create(Iterator)

getValuesAsArray

Object[] getValuesAsArray()

Obtain the property's values as an array of objects in their natural form.

A valid array is return if the property has single valued or multi-valued, or a null value is returned if the property is empty.

The resulting array is a copy, guaranteeing immutability for the property.

Returns:

the array of values

See Also:

getFirstValue(), Iterable.iterator(), getValues(), ValueFactory.create(Object[])

getString

String getString()

Get the string form of the property, using the default encoder.

Returns:

the encoded string

See Also:

getString(TextEncoder)

getString

String getString(TextEncoder encoder)

Get the encoded string form of the property, using the supplied encoder to encode characters in the property's name and values.

Parameters:

encoder - the encoder to use, or null if the default encoder should be used

Returns:

the encoded string

See Also:

getString()

getString

String getString(NamespaceRegistry namespaceRegistry)

Get the string form of the property, using the supplied namespace registry to convert the property's name and values.

Parameters:

namespaceRegistry - the namespace registry that should be used to obtain the prefix for the namespace URIs in the property name

Returns:

the string

Throws:

IllegalArgumentException - if the namespace registry is null

See Also:

getString(NamespaceRegistry,TextEncoder), getString(NamespaceRegistry, TextEncoder, TextEncoder)

getString

String getString(NamespaceRegistry namespaceRegistry,
                 TextEncoder encoder)

Get the encoded string form of the property, using the supplied namespace registry to convert the property's namespace URIs to prefixes and the supplied encoder to encode characters in the property's name and values.

Parameters:

namespaceRegistry - the namespace registry that should be used to obtain the prefix for the namespace URIs in the property name, or null if the namespace registry should not be used

encoder - the encoder to use for encoding the name and values, or null if the default encoder should be used

Returns:

the encoded string

See Also:

getString(NamespaceRegistry), getString(NamespaceRegistry, TextEncoder, TextEncoder)

getString

String getString(NamespaceRegistry namespaceRegistry,
                 TextEncoder encoder,
                 TextEncoder delimiterEncoder)

Get the encoded string form of the property, using the supplied namespace registry to convert the property's namespace URIs to prefixes and the supplied encoder to encode characters in the property's name and values.

Parameters:

namespaceRegistry - the namespace registry that should be used to obtain the prefix for the namespace URIs in the property name, or null if the namespace registry should not be used

encoder - the encoder to use for encoding the name and values, or null if the default encoder should be used

delimiterEncoder - the encoder to use for encoding delimiters used in paths and names, or null if the standard delimiters should be used

Returns:

the encoded string

See Also:

getString(NamespaceRegistry), getString(NamespaceRegistry, TextEncoder)