de.marcelsauer.tokenreplacer
Class Toky

java.lang.Object
  de.marcelsauer.tokenreplacer.Toky

All Implemented Interfaces:

TokenReplacer

public class Toky
extends java.lang.Object
implements TokenReplacer

Toky is a token replacer for Strings. It will replace the found token with a provided static value or a dynamically generated value created by a Generator. Toky itself IS NOT THREAD SAFE. so handling Toky in a multi threaded environment should be synchronized by the client.

simplest use case, only static values

 TokenReplacer toky = new Toky().register("number", "123");
 toky.substitute("i can count to {number}");
 

is same as registering an explicit Token

 toky = new Toky().register(new Token("number").replacedBy("123"));
 toky.substitute("i can count to {number}");
 

we can also use a Generator to dynamically get the value (which here does not really make sense ;-)

 toky = new Toky().register(new Token("number").replacedBy(new Generator() {
 
        @Override
        public void inject(String[] args) {
                // not relevant here
        }
 
        @Override
        public String generate() {
                return "123";
        }
 }));
 

here we use a generator and pass the arguments "a,b,c" to it, they will be injected via Generator.inject(String[] args) before the call to Generator.generate() is done. it is up to the generator to decide what to do with them. this feature makes handling tokens pretty powerful because you can write very dynamic generators.

 toky.substitute("i can count to {number(a,b,c)}");
 

if you prefer to use index based tokens, you can also use this:

 toky.register(new String[] { "one", "two", "three" });
 toky.substitute("abc {0} {1} {2} def")); // will produce "abc one two three def"
 

of course you can replace all default delimiters with your preferred ones, just make sure start and end are different.

 toky.withTokenStart("*"); // default is '{'
 toky.withTokenEnd("#"); // default is '}'
 toky.withArgumentDelimiter(";"); // default is ','
 toky.withArgumentStart("["); // default is '('
 toky.withArgumentEnd("]"); // default is ')'
 

by default Toky will throw IllegalStateExceptions if there was no matching value or generator found for a token. you can enable/disable generating exceptions.

 toky.doNotIgnoreMissingValues(); // which is the DEFAULT
 

will turn error reporting for missing values OFF

 toky.ignoreMissingValues();
 

you can enable/disable generator caching. if you enable caching once a generator for a token returned a value this value will be used for all subsequent tokens with the same name otherwise the generator will be called once for every token.

e.g. {counter}{counter}{counter}

with a registered generator will result in 3 calls to the generator (resulting in poorer performance). so, if you know your generator will always return the same value enable caching.

 toky.enableGeneratorCaching();
 toky.disableGeneratorCaching();
 

Author:

msauer

Constructor Summary

Toky()
constructs a new TokenReplacer.

Toky(TokenReplacer impl)
allows clients of Toky to provided their own implementation of the TokenReplacer that will be called.

Method Summary

TokenReplacer	disableGeneratorCaching() turns generator caching OFF.
TokenReplacer	doNotIgnoreMissingValues() tells the TokenReplacer to report any tokens that can not be replaced.
TokenReplacer	enableGeneratorCaching() turns generator caching ON.
TokenReplacer	ignoreMissingValues() tells the TokenReplacer to IGNORE any tokens that can not be replaced.
TokenReplacer	register(java.lang.String[] replacements) registers an array of replacements for a string based in indexed tokens.
TokenReplacer	register(java.lang.String token, Generator Generator) registers a Token that will be replaced by the given Generator.
TokenReplacer	register(java.lang.String token, java.lang.String value) registers a static value for a given token.
TokenReplacer	register(Token token) registers a Token that needs to be replaced.
java.lang.String	substitute(java.lang.String toSubstitute) replaces all Token with one of the following: the provided static values set via TokenReplacer.register(String, String) the token registered via TokenReplacer.register(Token) the generator registered via TokenReplacer.register(String, Generator)
TokenReplacer	withArgumentDelimiter(java.lang.String argsSep)
TokenReplacer	withArgumentEnd(java.lang.String argsEnd)
TokenReplacer	withArgumentStart(java.lang.String argsStart)
TokenReplacer	withTokenEnd(java.lang.String tokenEnd)
TokenReplacer	withTokenStart(java.lang.String tokenStart)

Methods inherited from class java.lang.Object

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

Constructor Detail

Toky

public Toky(TokenReplacer impl)

allows clients of Toky to provided their own implementation of the TokenReplacer that will be called. use this if you know what you are doing :-) otherwise always use the normal Toky() constructor that will use the correct implementation!

Parameters:

impl -

Toky

public Toky()

constructs a new TokenReplacer.

Method Detail

register

public TokenReplacer register(java.lang.String token,
                              java.lang.String value)

Description copied from interface: TokenReplacer

registers a static value for a given token. if you need dynamic behaviour then use #register(Generator). same as registering a token via TokenReplacer.register(Token) and supplying a replacement value via Token.replacedBy(String).

Specified by:

register in interface TokenReplacer

Parameters:

token - the name of the token to be replaced e.g. for ${date} -> "date" would be the token, must not be null or empty

value - the static value that will be used when replacing the token, must not be null or empty

Returns:

the TokenReplacer to allow method chaining

register

public TokenReplacer register(Token token)

Description copied from interface: TokenReplacer

registers a Token that needs to be replaced.

Specified by:

register in interface TokenReplacer

Parameters:

token - the Token, must not be null, the token must have a valid value or generator associated with it which was set via Token.replacedBy(String) or Token.replacedBy(String)

Returns:

the #TokenReplacer to allow method chaining

substitute

public java.lang.String substitute(java.lang.String toSubstitute)

Description copied from interface: TokenReplacer

replaces all Token with one of the following:

• the provided static values set via TokenReplacer.register(String, String)
• the token registered via TokenReplacer.register(Token)
• the generator registered via TokenReplacer.register(String, Generator)

  Specified by:

  substitute in interface TokenReplacer

  Parameters:

  toSubstitute - the string that contains the tokens, will be returned as-is in case of null or empty string

  Returns:

  the result after replacing all tokens with the proper values

withArgumentDelimiter

public TokenReplacer withArgumentDelimiter(java.lang.String argsSep)

Specified by:

withArgumentDelimiter in interface TokenReplacer

Parameters:

argsSep - changes the delimiter of the arguments to the given value e.g. {dynamic(1;2;3)} -> ';' would be the delimiter, must not be null or empty

Returns:

the #TokenReplacer to allow method chaining

withArgumentEnd

public TokenReplacer withArgumentEnd(java.lang.String argsEnd)

Specified by:

withArgumentEnd in interface TokenReplacer

Parameters:

argsEnd - sets the argument end identifier to the given value e.g. {dynamic[1;2;3]} -> ']' would be the delimiter e.g. ']', must not be null or empty

Returns:

the #TokenReplacer to allow method chaining

withArgumentStart

public TokenReplacer withArgumentStart(java.lang.String argsStart)

Specified by:

withArgumentStart in interface TokenReplacer

Parameters:

argsStart - sets the argument start identifier to the given value e.g. {dynamic[1;2;3]} -> '[' would be the delimiter e.g. '[', must not be null or empty

Returns:

the #TokenReplacer to allow method chaining

withTokenEnd

public TokenReplacer withTokenEnd(java.lang.String tokenEnd)

Specified by:

withTokenEnd in interface TokenReplacer

Parameters:

tokenEnd - sets the token end identifier to the given value e.g. [dynamic] -> ']' would be the end identifier, e.g. '[', must not be null or empty

Returns:

the #TokenReplacer to allow method chaining

withTokenStart

public TokenReplacer withTokenStart(java.lang.String tokenStart)

Specified by:

withTokenStart in interface TokenReplacer

Parameters:

tokenStart - sets the token start identifier to the given value e.g. [dynamic] -> '[' would be the start identifier, e.g. '[', must not be null or empty

Returns:

the #TokenReplacer to allow method chaining

register

public TokenReplacer register(java.lang.String token,
                              Generator Generator)

Description copied from interface: TokenReplacer

registers a Token that will be replaced by the given Generator. same as registering a token via TokenReplacer.register(Token) and supplying a generator via Token.replacedBy(Generator)

Specified by:

register in interface TokenReplacer

Parameters:

token - the name of the token to be replaced e.g. for ${date} -> "date" would be the token, must not be null or empty

Returns:

the #TokenReplacer to allow method chaining

doNotIgnoreMissingValues

public TokenReplacer doNotIgnoreMissingValues()

Description copied from interface: TokenReplacer

tells the TokenReplacer to report any tokens that can not be replaced. if turned on an IllegalStateException will be thrown during token replacement. reporting errors is turned ON by DEFAULT.

Specified by:

doNotIgnoreMissingValues in interface TokenReplacer

Returns:

the #TokenReplacer to allow method chaining

ignoreMissingValues

public TokenReplacer ignoreMissingValues()

Description copied from interface: TokenReplacer

tells the TokenReplacer to IGNORE any tokens that can not be replaced. if turned OFF no Exceptions will be thrown during token replacement. reporting errors is turned ON by DEFAULT.

Specified by:

ignoreMissingValues in interface TokenReplacer

Returns:

the #TokenReplacer to allow method chaining

enableGeneratorCaching

public TokenReplacer enableGeneratorCaching()

Description copied from interface: TokenReplacer

turns generator caching ON. once a value is determined through a Generator all remaining values with the same token name will be replaced by the cached version. use TokenReplacer.disableGeneratorCaching() to turn caching off.

Specified by:

enableGeneratorCaching in interface TokenReplacer

Returns:

the #TokenReplacer to allow method chaining

disableGeneratorCaching

public TokenReplacer disableGeneratorCaching()

Description copied from interface: TokenReplacer

turns generator caching OFF. use TokenReplacer.enableGeneratorCaching() to turn caching on.

Specified by:

disableGeneratorCaching in interface TokenReplacer

Returns:

the #TokenReplacer to allow method chaining

register

public TokenReplacer register(java.lang.String[] replacements)

Description copied from interface: TokenReplacer

registers an array of replacements for a string based in indexed tokens. the tokens will be replaced in the order they were added to the array. e.g.

 toky.register(new String[] { "one", "two", "three" });
 toky.substitute("{0} {1} {2}")); // will result in "one two three"
 

Specified by:

register in interface TokenReplacer

Parameters:

replacements - the array of replacements that will be used when replacing an indexed strings, must not be null but can be empty

Returns:

the #TokenReplacer to allow method chaining