com.unboundid.util
Class ValuePattern

java.lang.Object
  com.unboundid.util.ValuePattern

All Implemented Interfaces:

java.io.Serializable

@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class ValuePattern
extends java.lang.Object
implements java.io.Serializable

This class provides a method for generating a string value comprised of zero or more components. The components may be any combination of zero or more strings, sequential numeric ranges, and random numeric ranges. These components should be formatted as follows:

• Strings are simply any kind of static text that will be used as-is without any modification, except that double opening or closing square brackets (i.e., "[[" or "]]") will be replaced with single opening or closing square brackets to distinguish them from the square brackets used in numeric ranges or URL references.
• Sequential numeric ranges consist of an opening square bracket, a numeric value to be used as the lower bound for the range, a colon, a second numeric value to be used as the upper bound for the range, an optional 'x' character followed by a numeric value to be used as the increment, an optional '%' character followed by a format string as allowed by the DecimalFormat class to define how the resulting value should be formatted, and a closing square bracket to indicate the end of the range.
• Random numeric ranges consist of an opening square bracket, a numeric value to be used as the lower bound for the range, a dash, a second numeric value to be used as the upper bound for the range, an optional '%' character followed by a format string as allowed by the DecimalFormat class to define how the resulting value should be formatted, and a closing square bracket to indicate the end of the range.
• Strings read from a file specified by a given URL. That file may be contained on the local filesystem (using a URL like "file:///tmp/mydata.txt") or read from a remote server via HTTP (using a URL like "http://server.example.com/mydata.txt"). In either case, the provided URL must not contain a closing square bracket character. If this option is used, then that file must contain one value per line, and its contents will be read into memory and values from the file will be selected in a random order and used in place of the bracketed URL.
• Back-references that will be replaced with the same value as the bracketed token in the specified position in the string. For example, a component of "[ref:1]" will be replaced with the same value as used in the first bracketed component of the value pattern. Back-references must only reference components that have been previously defined in the value pattern, and not those which appear after the reference.

It must be possible to represent all of the numeric values used in sequential or random numeric ranges as long values. In a sequential numeric range, if the first value is larger than the second value, then values will be chosen in descending rather than ascending order (and if an increment is given, then it should be positive). In addition, once the end of a sequential range has been reached, then the value will wrap around to the beginning of that range.
Examples of value pattern components include:

• Hello -- The static text "Hello".
• [[Hello]] -- The static text "[Hello]" (note that the double square brackets were replaced with single square brackets).
• [0:1000] -- A sequential numeric range that will iterate in ascending sequential order from 0 to 1000. The 1002nd value that is requested will cause the value to be wrapped around to 0 again.
• [1000:0] -- A sequential numeric range that will iterate in descending sequential order from 1000 to 0. The 1002nd value that is requested will cause the value to be wrapped around to 1000 again.
• [0:1000x5%0000] -- A sequential numeric range that will iterate in ascending sequential order from 0 to 1000 in increments of five with all values represented as four-digit numbers padded with leading zeroes. For example, the first four values generated by this component will be "0000", "0005", "0010", and "0015".
• [0-1000] -- A random numeric range that will choose values at random between 0 and 1000, inclusive.
• [0-1000%0000] -- A random numeric range that will choose values at random between 0 and 1000, inclusive, and values will be padded with leading zeroes as necessary so that they are represented using four digits.
• [file:///tmp/mydata.txt] -- A URL reference that will cause randomly-selected lines from the specified local file to be used in place of the bracketed range. To make it clear that the file contents are randomly accessed, you may use randomfile in place of file.
• [sequentialfile:///tmp/mydata.txt] -- A URL reference that will cause lines from the specified local file, selected in sequential order, to be used in place of the bracketed range.
• [http://server.example.com/tmp/mydata.txt] -- A URL reference that will cause randomly-selected lines from the specified remote HTTP-accessible file to be used in place of the bracketed range.

Examples of full value pattern strings include:

• dc=example,dc=com -- A value pattern containing only static text and no numeric components.
• [1000:9999] -- A value pattern containing only a numeric component that will choose numbers in sequential order from 1000 to 9999.
• (uid=user.[1-1000000]) -- A value pattern that combines the static text "(uid=user." with a value chosen randomly between one and one million, and another static text string of ")".
• uid=user.[1-1000000],ou=org[1-10],dc=example,dc=com -- A value pattern containing two numeric components interspersed between three static text components.
• uid=user.[1-1000000],ou=org[ref:1],dc=example,dc=com -- A value pattern in which the organization number will be the same as the randomly-selected user number.

See Also:

Serialized Form

Field Summary

static java.lang.String

PUBLIC_JAVADOC_URL The URL to the publicly-accessible javadoc for this class, which provides a detailed overview of the supported value pattern syntax.

Constructor Summary

ValuePattern(java.lang.String s)
Creates a new value pattern from the provided string.

ValuePattern(java.lang.String s, java.lang.Long r)
Creates a new value pattern from the provided string.

Method Summary

java.lang.String	nextValue() Retrieves the next value generated from the value pattern.
java.lang.String	toString() Retrieves a string representation of this value pattern, which will be the original pattern string used to create it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PUBLIC_JAVADOC_URL

public static final java.lang.String PUBLIC_JAVADOC_URL

The URL to the publicly-accessible javadoc for this class, which provides a detailed overview of the supported value pattern syntax.

See Also:

Constant Field Values

Constructor Detail

ValuePattern

public ValuePattern(java.lang.String s)
             throws java.text.ParseException

Creates a new value pattern from the provided string.

Parameters:

s - The string representation of the value pattern to create. It must not be null.

Throws:

java.text.ParseException - If the provided string cannot be parsed as a valid value pattern string.

ValuePattern

public ValuePattern(java.lang.String s,
                    java.lang.Long r)
             throws java.text.ParseException

Creates a new value pattern from the provided string.

Parameters:

s - The string representation of the value pattern to create. It must not be null.

r - The seed to use for the random number generator. It may be null if no seed is required.

Throws:

java.text.ParseException - If the provided string cannot be parsed as a valid value pattern string.

Method Detail

nextValue

public java.lang.String nextValue()

Retrieves the next value generated from the value pattern.

Returns:

The next value generated from the value pattern.

toString

public java.lang.String toString()

Retrieves a string representation of this value pattern, which will be the original pattern string used to create it.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this value pattern.