com.navigamez.greex
Class GreexGenerator

java.lang.Object
  com.navigamez.greex.GreexGenerator

public class GreexGenerator
extends Object

Generates matches for a given regular expression. Support for regular expressions is provided by RegExp.

To use this class, create a new generator instance with your regular expression, then use the generate methods to generate your matches. This example will use this regular expression:

(white|black)|((light|dark) )?(red|green|blue|gray)

To generate a random match, create an instance of GreexGenerator and use generateRandom():

GreexGenerator generator = new GreexGenerator("(white|black)|((light|dark) )?(red|green|blue|gray)");
String match = generator.generateRandom();
System.out.println(match); // e.g. "dark red"

To generate all matches, create an instance of GreexGenerator and use generateAll():

GreexGenerator generator = new GreexGenerator("(white|black)|((light|dark) )?(red|green|blue|gray)");
List<String> matches = generator.generateAll();
System.out.println(matches.size()); // "14"

When generating all matches for a non-finite regular expression, you must provide a max length or you will get a StackOverflowError or OutOfMemoryError. The max length defaults to Integer.MAX_VALUE when not provided, which is fine for finite regular expressions.

Thread Safety

This class is not 100% thread safe. Here is the thread safety profile of each method.

Method	Thread Safety
generateAll()	Always thread safe
generateAll(int)	Always thread safe
generateRandom()	Not thread safe*
generateRandom(long)	Always thread safe
generateRandom(Random)	Sometimes thread safe**

* This method uses an internal Random with no synchronization, and so it is not thread safe.
** This method is only thread safe if the calling class is managing the Random in a thread-safe way.

Since:

1.0

Constructor Summary

GreexGenerator(String regex)
Create a new generator using the given regular expression.

Method Summary

Set<String>	generateAll() Generate all the matches for this generator's regular expression.
Set<String>	generateAll(int maxLength) Generate all the matches for this generator's regular expression where the length of the generated string is less than the given maximum length.
String	generateRandom() Generates a random match for this generator's regular expression.
String	generateRandom(long seed) Generates a random match for this generator's regular expression.
String	generateRandom(Random random) Generates a random match for this generator's regular expression.

Methods inherited from class java.lang.Object

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

Constructor Detail

GreexGenerator

public GreexGenerator(String regex)

Create a new generator using the given regular expression.

Parameters:

regex - the regular expression that will be used for match generation

Method Detail

generateAll

public Set<String> generateAll()
                        throws StackOverflowError,
                               OutOfMemoryError

Generate all the matches for this generator's regular expression. This method is the same as invoking generateAll(Integer.MAX_VALUE).

This method is always thread safe.

Returns:

an unordered set of all matches

Throws:

OutOfMemoryError - might be thrown if the regular expression is non-finite

StackOverflowError - might be thrown if the regular expression is non-finite

generateAll

public Set<String> generateAll(int maxLength)
                        throws StackOverflowError,
                               OutOfMemoryError

Generate all the matches for this generator's regular expression where the length of the generated string is less than the given maximum length.

This method is always thread safe.

Parameters:

maxLength - the maximum string length for generated matches

Returns:

an unordered set of all matches with lengths less than the given maximum length

Throws:

OutOfMemoryError - might be thrown if the regular expression is non-finite

StackOverflowError - might be thrown if the regular expression is non-finite

generateRandom

public String generateRandom()
                      throws StackOverflowError

Generates a random match for this generator's regular expression. This uses an internal Random that was created when the instance was constructed. Subsequent calls continue to use the same Random instance.

This method is never thread safe.

Returns:

a random string that matches the given regular expression

Throws:

StackOverflowError - might be thrown if the regular expression is non-finite

generateRandom

public String generateRandom(long seed)
                      throws StackOverflowError

Generates a random match for this generator's regular expression. This creates a new Random instance using the given seed. Subsequent calls with the same seed will create a new Random each time, and so this will always return the same result for the same regular expression and seed.

This method is always thread safe.

Parameters:

seed - the seed to use for the Random instance.

Returns:

a random string that matches the given regular expression

Throws:

StackOverflowError - might be thrown if the regular expression is non-finite

generateRandom

public String generateRandom(Random random)
                      throws StackOverflowError

Generates a random match for this generator's regular expression. This uses the given Random instance.

This method is only thread safe if the given Random is managed in a thread-safe way.

Parameters:

random - the Random to use for generation.

Returns:

a random string that matches the given regular expression

Throws:

StackOverflowError - might be thrown if the regular expression is non-finite