org.mule.module.apikit.uri
Class Variable

java.lang.Object
  org.mule.module.apikit.uri.Variable

public class Variable
extends Object

A variable in a URL pattern or template.

The variables can be typed by prefixing the variable name. Types are not required, if no type is specified, the variable is considered untyped.

Note: there is no predefined list of types as the handling of types is out of scope. The syntax simply allows variables to be associated with a type.

Examples of variables:

   foo         - An untyped variable named 'foo'
   bar         - An untyped variable named 'bar'
   ping:foo    - A variable named 'foo' typed 'ping'
   ping:foo=1  - A variable named 'foo' typed 'ping' which default value is '1'
   foo=pong    - An untyped variable named 'foo' which default value is 'pong'
 

Variables only appear in the context of the a template expansion.

Expansion rule (4.4.1):

 "In a variable ('var') expansion, if the variable is defined then substitute the value of
 the variable, otherwise substitute the default value.
 If no default value is given then substitute with the empty string."
 

Syntax for variables:

 var         = [ vartype ":" ]  varname [ "=" vardefault ]
 vars        = var [ *("," var) ]
 vartype     = (ALPHA / DIGIT)* (ALPHA / DIGIT / "." / "_" / "-" )
 varname     = (ALPHA / DIGIT)* (ALPHA / DIGIT / "." / "_" / "-" )
 vardefault  = *(unreserved / pct-encoded)
 

Version:

11 June 2009

Author:

Christophe Lauret

See Also:

URI Template (Internet Draft 3), RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax

Nested Class Summary

static class	Variable.Form Indicate that the variable's value should be processed as a list ("@") or an associative array ("%").
static class	Variable.Modifier Indicate that the variable's value should be processed as a list ("@") or an associative array ("%").
static class	Variable.Reserved Used for reserved variable names.

Field Summary

protected static Pattern

VALID_VALUE The pattern for a valid normalised variable value: any unreserved character or an escape sequence.

Constructor Summary

Variable(String name)
Creates a new untyped variable.

Variable(String name, String def)
Creates a new untyped variable.

Variable(String name, String def, VariableType type)
Creates a new variable.

Variable(String name, String def, VariableType type, Variable.Form form)
Creates a new variable.

Variable(Variable.Reserved reserved)
Creates a new untyped reserved variable.

Method Summary

String	defaultValue() Returns the default value for this variable.
boolean	equals(Object o)
Variable.Form	form() Returns the form of this variable.
int	hashCode()
static boolean	isValidName(String name) Indicates whether the variable has a valid name according to the specifications.
static boolean	isValidValue(String value) Indicates whether the variable has a valid value according to the specifications.
String	name() Returns the name of this variable.
protected String	namePatternString() Returns the name of this variable as a regular expression pattern string for use in a regular expression.
static Variable	parse(String exp) Parses the given expression and returns the corresponding instance.
String	toString()
VariableType	type() Returns the implementation type of this variable.
String	value(Parameters parameters) Returns the expanded value of this variable.
String[]	values(Parameters parameters) Returns the expanded value of this variable.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

VALID_VALUE

protected static final Pattern VALID_VALUE

The pattern for a valid normalised variable value: any unreserved character or an escape sequence. This pattern contains non-capturing parentheses to make it easier to get variable values as a group.

Constructor Detail

Variable

public Variable(Variable.Reserved reserved)
         throws NullPointerException,
                IllegalArgumentException

Creates a new untyped reserved variable.

Parameters:

reserved - The name of the variable.

Throws:

NullPointerException - If the specified name is null.

IllegalArgumentException - If the specified name is an empty string.

Variable

public Variable(String name)
         throws NullPointerException,
                IllegalArgumentException

Creates a new untyped variable.

Parameters:

name - The name of the variable.

Throws:

NullPointerException - If the specified name is null.

IllegalArgumentException - If the specified name is an empty string.

Variable

public Variable(String name,
                String def)
         throws NullPointerException,
                IllegalArgumentException

Creates a new untyped variable.

Parameters:

name - The name of the variable.

def - The default value for the variable.

Throws:

NullPointerException - If the specified name is null.

IllegalArgumentException - If the specified name is an empty string.

Variable

public Variable(String name,
                String def,
                VariableType type)
         throws NullPointerException,
                IllegalArgumentException

Creates a new variable.

Parameters:

name - The name of the variable.

def - The default value for the variable.

type - The type of the variable.

Throws:

NullPointerException - If the specified name is null.

IllegalArgumentException - If the specified name is an empty string.

Variable

public Variable(String name,
                String def,
                VariableType type,
                Variable.Form form)
         throws NullPointerException,
                IllegalArgumentException

Creates a new variable.

Parameters:

name - The name of the variable.

def - The default value for the variable.

type - The type of the variable.

Throws:

NullPointerException - If the specified name is null.

IllegalArgumentException - If the specified name is an empty string.

Method Detail

form

public Variable.Form form()

Returns the form of this variable.

This method will never return null.

Returns:

The form of this variable.

name

public String name()

Returns the name of this variable.

This method never return null.

Returns:

The name of this variable.

defaultValue

public String defaultValue()

Returns the default value for this variable.

This method never return null.

Returns:

The default value for this variable.

type

public VariableType type()

Returns the implementation type of this variable.

This method will return null if the variable is untyped.

Returns:

The type of this variable.

value

public String value(Parameters parameters)

Returns the expanded value of this variable.

If no value is specified for this variable, the default value is returned instead.

Parameters:

parameters - The parameters.

Returns:

The value.

values

public String[] values(Parameters parameters)

Returns the expanded value of this variable.

If no values are specified for this variable, the default value is returned instead.

Parameters:

parameters - The parameters.

Returns:

The values.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

parse

public static Variable parse(String exp)
                      throws URITemplateSyntaxException

Parses the given expression and returns the corresponding instance.

Parameters:

exp - The expression to parse.

Returns:

the corresponding variable.

Throws:

URITemplateSyntaxException - If the expression cannot be parsed

isValidName

public static boolean isValidName(String name)

Indicates whether the variable has a valid name according to the specifications.

Parameters:

name - The name of the variable.

Returns:

true if the name is valid; false otherwise.

isValidValue

public static boolean isValidValue(String value)

Indicates whether the variable has a valid value according to the specifications.

Parameters:

value - The value of the variable.

Returns:

true if the name is not valid; false otherwise.

namePatternString

protected String namePatternString()

Returns the name of this variable as a regular expression pattern string for use in a regular expression.

Implementation note: this method replaces any character that could be interpreted as a regex meta-character, it is more efficient than using quotation (\Q...\E) for the whole string.

Returns:

The regex pattern corresponding to this name.