Each string in the array returned by PropertyDefinition.getValueConstraints() specifies a constraint on the value(s) of the property. The constraints are OR-ed together, meaning that in order to be valid, the value (each of the values, in the case of multi-value properties) must meet at least one of the constraints. For example, a constraint array of ["constraint1", "constraint2", "constraint3"] has the interpretation: "the value of this property must meet either constraint1, constraint2 or constraint3".
Reporting constraint information is optional. Therefore, the return of an empty array indicates that there are no discoverable constraints, meaning that either there are constraints but they are inexpressible in the constraint-string syntax, or constraint discovery is simply not supported.
In the case of multi-value properties, the constraint array returned applies independently to each of the values of the property. For example, if one value meets one constraint in the constraint array while the other meets another, the constraint set is considered met for the property as a whole.
If a property does not exist or (in the case of multi-value properties) contains an empty array, the constraint set is considered to have been met by default since, by definition, no values have failed to meet the constraints.
The constraint strings themselves have different formats and interpretations depending on the type of the property in question. The following describes the value constraint syntax for each property type:
STRING: The constraint string is a regular expression pattern. For example the regular expression “.*” means “any string, including the empty string”. Whereas a simple literal string (without any regular expression-specific meta-characters) like “banana” matches only the string “banana” (see 6.7.16.1 Choice Lists, below).
PATH: The constraint string is a path terminating with either no final “/”, a single “/” or the substring “/*”. For example, possible constraint strings for a property of type PATH include:
“/myapp:products/myapp:televisions”
“/myapp:products/myapp:televisions/”
“/myapp:products/*”
“myapp:products/myapp:televisions”
“../myapp:televisions”
“../myapp:televisions/*”
The following principles apply:
The constraint must match the normalized path. For example, the “*” means “matches descendants” not “matches any subsequent path”, so that /a/* does not match /a/../c. Similarly, a trailing “/” has no effect (hence, 1 and 2, above, are equivalent).
Relative path constraints only match relative path values and absolute path constraints only match absolute path values.
The trailing “*” character means that the value of the PATH property is restricted to the indicated subtree (in other words any additional relative path can replace the “*”). For example, 3, above would allow /myapp:products/myapp:radios, /myapp:products/myapp:microwaves/X900, and so forth.
A constraint without a “*” means that the PATH property is restricted to that precise path. For example, 1, above would allow only the value /myapp:products/myapp:televisions.
The constraint can indicate either a relative path or an absolute path depending on whether it includes a leading “/” character. 1 and 4 above, for example, are distinct.
The constraint string returned must reflect the namespace mapping in the current Session (i.e., the current state of the namespace registry overlaid with any session-specific mappings). Constraint strings for PATH properties should be stored in fully-qualified form (using the actual URI instead of the prefix) and then be converted to prefix form according to the current mapping. Note however that these constraint strings are not themselves valid PATH values, since they may contain a “*” character, which is not allowed in the value of an actual PATH property.
NAME: The constraint string is a name in prefix form. For example, “myapp:products”. No wildcards or other pattern matching are supported. As with PATH properties, the string returned must reflect the namespace mapping in the current Session. Constraint strings for NAME properties should be stored in fully-qualified form (using the actual URI instead of the prefix) and then be converted to prefix form according to the current mapping.
REFERENCE: The constraint string is a name in prefix form. This name is interpreted as a node type name and the REFERENCE property is restricted to referring only to nodes that have at least the indicated node type8. For example, a constraint of “mytype:document” would indicate that the REFERENCE property in question can only refer to nodes that have at least the node type mytype:document (assuming this was the only constraint returned in the array, recall that the array of constraints are to be "OR-ed" together). No wildcards or other pattern matching are supported. As with PATH properties, the string returned must reflect the namespace mapping in the current Session. Constraint strings for REFERENCE properties should be stored in fully-qualified form (using the actual URI instead of the prefix) and then be converted to prefix form according to the current mapping.
The remaining types all have value constraints in the form of inclusive or exclusive ranges: i.e., "[min, max]", "(min, max)", "(min, max]" or "[min, max)". Where "[" and "]" indicate "inclusive", while "(" and ")" indicate "exclusive". A missing min or max value indicates no bound in that direction. For example [,5] means no minimum but a maximum of 5 (inclusive) while [,] means simply that any value will suffice. The meaning of the min and max values themselves differ between types as follows:
BINARY: min and max specify the allowed size range of the binary value in bytes.
DATE: min and max are dates specifying the allowed date range. The date strings must be in the ISO 8601:2000-compliant format: sYYYY-MM-DDThh:mm:ss.sssTZD. See 6.2.5.1 Date.
LONG, DOUBLE: min and max are numbers.