In some cases, a property may have more than one value. A property that may have more than one value is referred to as a multi-valued property (regardless of whether it currently has one or more than one value).
Whether a particular property is a multi-valued property is governed by the property definition applicable to it, which is determined by the node type of the property's parent node.
The values within a multi-valued property are ordered.
Accessing the values of such a property is done with the method Property.getValues, which returns an array of Value objects that contains the values in their prescribed order.
Accessing a multi-valued property with Property.getValue, or a single-value property with Property.getValues will throw a ValueFormatException.
The values stored within a multi-valued property are all of the same type.
As with single-value properties, there is no such thing as a null value. If a value within a multi-value property is set to null, this is equivalent to removing that value from the value array. In such a case the array is automatically compacted: shifting the indexes of those values with indexes greater than that of the removed value by -1.
Note that this does mean that a multi-value property can have no values (i.e., be an empty array), whereas a single-value property either has a (non-null) value or does not exist.
See 7.1.5 Adding and Writing Properties for more details.