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.
• Randomly character ranges consist of an opening square bracket, the word "random", a colon, the number of random characters to generate, another colon, the set of characters to include, and a closing square bracket. For example, "[random:4:0123456789abcdef]" will generate a string of four randomly selected characters from the set of hexadecimal digits. The final colon and character set may be omitted to use the set of lowercase alphabetic characters.
• 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. Alternately, a local file may be read in sequential order by using "sequentialfile:" or "streamfile:" instead of "file:"; the former will load the entire file into memory while the latter will only hold a small amount of data in memory at any time.
• Timestamps in a specified format. A pattern of just "[timestamp]" will be replaced with the current time, with millisecond precision, in the generalized time format (for example, "20180102030405.678Z"). A value A value of "[timestamp:format=XXX]" will be replaced with the current time in the specified format, where the format value can be one of "milliseconds" for the number of milliseconds since the epoch (January 1, 1970 at midnight UTC), "seconds" for the number of seconds since the epoch, or any value supported by Java's SimpleDateFormat class. A pattern of "[timestamp:min=XXX:max=XXX]" will be replaced with a randomly selected timestamp in generalized time format between the given minimum and maximum timestamps (inclusive), which must be in generalized time format. A pattern of "[timestamp:min=XXX:max=XXX:format=XXX]" will be replaced with a randomly selected timestamp in the specified format between the given minimum and maximum timestamps (where the minimum and maximum timestamp values must be in the generalized time format).
• Randomly generated UUIDs (universally unique identifiers) as described in RFC 4122. These UUIDs may be generated using a pattern string of "[uuid]".
• 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.
• [random:5] -- Will generate a string of five randomly selected lowercase letters to be used in place of the bracketed range.
• [random:4:0123456789abcdef] -- Will generate a string of four randomly selected hexadecimal digits to be used in place of the bracketed range.
• [random:5:abcdefghijklmnopqrstuvwxyz] -- Will generate a string of five randomly selected lowercase letters to be used in place of the bracketed range.
• [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. The entire file will be read into memory, so this may not be a suitable option for very large files.
• [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. The entire file will be read into memory, so this may not be a suitable option for very large files.
• [streamfile:///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. A background thread will be used to read data from the file and place it into a queue so that it is available quickly, but only a small amount of data will be held in memory at any time, so this is a suitable option for very large files.
• [timestamp] -- The current time in generalized time format, with millisecond precision.
• [timestamp:format=milliseconds] -- The current time expressed as the number of milliseconds since January 1, 1970 at midnight UTC (that is, the output of System.currentTimeMillis().
• [timestamp:format=seconds] -- The current time expressed as the number of seconds since January 1, 1970 at midnight UTC.
• [timestamp:format=yyyy-MM-dd'T'HH:mm:ss.SSSZ] -- The current time expressed in the specified format string.
• [timestamp:min=20180101000000.000Z:max=20181231235959.999Z: format=yyyyMMddHHmmss] -- A randomly selected timestamp sometime in the year 2018 in the specified format.
• [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.
• [uuid] -- Will cause a randomly generated UUID 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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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

@NotNull
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(@NotNull
                    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(@NotNull
                    java.lang.String s,
                    @Nullable
                    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

@NotNull
public java.lang.String nextValue()

Retrieves the next value generated from the value pattern.

Returns:

The next value generated from the value pattern.

toString

@NotNull
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.