org.codehaus.plexus.summit.util
Class UriBuilder

java.lang.Object
  extended byorg.codehaus.plexus.summit.util.UriBuilder
Direct Known Subclasses:
ContentUriBuilder, RelativeTemplateLink, TemplateLink

public class UriBuilder
extends java.lang.Object

This creates a Dynamic URI for use within the Turbine system

If you use this class to generate all of your href tags as well as all of your URI's, then you will not need to worry about having session data setup for you or using HttpServletRequest.encodeUrl() since this class does everything for you.

 UriBuilder dui = new UriBuilder (data, "UserScreen" );
 dui.setName("Click Here").addPathInfo("user","jon");
 dui.getA();
 

The above call to getA() would return the String:

<A HREF="http://www.server.com:80/servlets/Turbine/screen=UserScreen&amp;user=jon">Click Here</A>

Version:
$Id: UriBuilder.java 2083 2005-06-05 03:01:09Z jvanzyl $
Author:
Jon S. Stevens, Jason van Zyl, John McNally, James Taylor

Field Summary
static int ANCHOR_STATIC_PART_LENGTH
          Length of static part of an A tag
protected  RunData data
          The RunData object.
private  boolean encodeUrl
          true=url will be rewritten with session_id if needed; false=url will not be encoded
private static char[] hexadecimal
          Array mapping hexadecimal values to the corresponding ASCII characters.
static java.lang.String HTTP
          HTTP protocol.
static java.lang.String HTTPS
          HTTPS protocol.
private  boolean isRelative
          true=relative url's; false=absolute url's
protected static int PATH_INFO
          P = 0 for path info.
protected  java.util.ArrayList pathInfo
          A Vector that contains all the path info if any.
protected static int QUERY_DATA
          Q = 1 for query data.
protected  java.util.ArrayList queryData
          A Vectory that contains all the query data if any.
protected  boolean redirect
          Whether we want to redirect or not.
 javax.servlet.http.HttpServletResponse res
          Servlet response interface.
static java.lang.String ROLE
           
private static boolean[] safe
          Characters that need not be encoded.
 
Constructor Summary
UriBuilder()
          Default constructor - the init() method must be called befroe use.
UriBuilder(RunData data)
          Constructor that takes the RunData as an argument.
 
Method Summary
protected  void add(java.util.ArrayList list, RequestParameters pp)
          Method for a quick way to add all the parameters in a RequestParameters to a given List
protected  void add(int type, RequestParameters pp)
          Method for a quick way to add all the parameters in a RequestParameters.
protected  void add(int type, java.lang.String name, java.lang.String value)
          If the type is P (0), then add name/value to the pathInfo hashtable.
protected  void addPair(java.util.ArrayList list, java.lang.String name, java.lang.String value)
          Add a key value pair (in the form of a 2 object array) to the provided list
 UriBuilder addPathInfo(RequestParameters pp)
          Adds a name=value pair for every entry in a RequestParameters object to the path_info string.
 UriBuilder addPathInfo(java.lang.String name, boolean value)
          Adds a name=value pair to the path_info string.
 UriBuilder addPathInfo(java.lang.String name, double value)
          Adds a name=value pair to the path_info string.
 UriBuilder addPathInfo(java.lang.String name, int value)
          Adds a name=value pair to the path_info string.
 UriBuilder addPathInfo(java.lang.String name, long value)
          Adds a name=value pair to the path_info string.
 UriBuilder addPathInfo(java.lang.String name, java.lang.Object value)
          Adds a name=value pair to the path_info string.
 UriBuilder addPathInfo(java.lang.String name, java.lang.String value)
          Adds a name=value pair to the path_info string.
 UriBuilder addQueryData(RequestParameters pp)
          Adds a name=value pair for every entry in a RequestParameters object to the query string.
 UriBuilder addQueryData(java.lang.String name, double value)
          Adds a name=value pair to the query string.
 UriBuilder addQueryData(java.lang.String name, int value)
          Adds a name=value pair to the query string.
 UriBuilder addQueryData(java.lang.String name, long value)
          Adds a name=value pair to the query string.
 UriBuilder addQueryData(java.lang.String name, java.lang.Object value)
          Adds a name=value pair to the query string.
 UriBuilder addQueryData(java.lang.String name, java.lang.String value)
          Adds a name=value pair to the query string.
 java.lang.String getA(java.lang.String name)
          Create an anchor object.
 java.lang.String getScriptName()
          Gets the script name (/servlets/Turbine).
 java.lang.String getServerName()
          Gets the server name.
 int getServerPort()
          Gets the server port.
 java.lang.String getServerScheme()
          Gets the server scheme (HTTP or HTTPS).
 boolean hasPathInfo()
          Does this URI have path info.
 boolean hasQueryData()
          Does this URI have query data.
 void init()
          Initializes the builder for use by clearing any previous state.
 void init(RunData data)
          Initialize with a RunData object
 boolean isEncodeUrl()
          Will a call to toString() add session info if needed to maintain a session.
 boolean isRelative()
          Will a call to toString() generate a relative url? where relative means no scheme, domain, and port info
protected  void remove(int type, java.lang.String name)
          If the type is P (0), then remove name/value from the pathInfo hashtable.
protected  void removePairByName(java.util.ArrayList pairs, java.lang.String name)
          Helper method to remove one or more pairs by its name (ie key).
 void removePathInfo()
          Removes all the path info elements.
 void removePathInfo(java.lang.String name)
          Removes a name=value pair from the path info.
 void removeQueryData()
          Removes all the query string elements.
 void removeQueryData(java.lang.String name)
          Removes a name=value pair from the query string.
protected  void renderPairs(java.util.ArrayList pairs, java.lang.StringBuffer out, char pairSep, char keyValSep)
          This method takes a List of key/value arrays and converts it into a URL encoded key/value pair format with the appropriate separator.
protected  void renderPathInfo(java.util.ArrayList pairs, java.lang.StringBuffer out)
          This method takes a Vector of key/value arrays and writes it to the supplied StringBuffer as encoded path info.
protected  java.lang.String renderPathInfo(java.util.Vector data)
          Deprecated. Prefer the ArrayList / StringBuffer form.
protected  void renderQueryString(java.util.ArrayList data, java.lang.StringBuffer out)
          This method takes a List of key/value arrays and writes it to the provided StringBuffer in encoded query string format.
protected  java.lang.String renderQueryString(java.util.Vector data)
          Deprecated. Prefer the ArrayList / StringBuffer form.
 UriBuilder setAction(java.lang.String action)
          Sets the action= value for this URL.
 UriBuilder setEncodeUrl(boolean b)
          Can be used to disable url rewriting.
 UriBuilder setRedirect(boolean doRedirect)
          Sets whether we want to redirect or not.
 UriBuilder setRelative(boolean b)
          if true, the scheme, domain, and port will not be included in the String representation of this uri..
 UriBuilder setTarget(java.lang.String template)
          Sets the target = value for this URL.
 java.lang.String toString()
          Builds the URL with all of the data URL-encoded as well as encoded using HttpServletResponse.encodeUrl().
static java.lang.String toString(RunData data)
          Given a RunData object, get a URI for the request.
static java.lang.String toString(RunData data, boolean isAbsolute)
          Given a RunData object, get a URI for the request.
protected static void writeEncoded(java.lang.String in, java.lang.StringBuffer out)
          URL encodes in and writes it to out.
protected static void writeFastEncoded(java.lang.String in, java.lang.StringBuffer out)
          URL encodes in and writes it to out.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ROLE

public static final java.lang.String ROLE

HTTP

public static final java.lang.String HTTP
HTTP protocol.

See Also:
Constant Field Values

HTTPS

public static final java.lang.String HTTPS
HTTPS protocol.

See Also:
Constant Field Values

ANCHOR_STATIC_PART_LENGTH

public static final int ANCHOR_STATIC_PART_LENGTH
Length of static part of an A tag


data

protected RunData data
The RunData object.


res

public javax.servlet.http.HttpServletResponse res
Servlet response interface.


pathInfo

protected java.util.ArrayList pathInfo
A Vector that contains all the path info if any.


queryData

protected java.util.ArrayList queryData
A Vectory that contains all the query data if any.


redirect

protected boolean redirect
Whether we want to redirect or not.


PATH_INFO

protected static final int PATH_INFO
P = 0 for path info.

See Also:
Constant Field Values

QUERY_DATA

protected static final int QUERY_DATA
Q = 1 for query data.

See Also:
Constant Field Values

isRelative

private boolean isRelative
true=relative url's; false=absolute url's


encodeUrl

private boolean encodeUrl
true=url will be rewritten with session_id if needed; false=url will not be encoded


hexadecimal

private static final char[] hexadecimal
Array mapping hexadecimal values to the corresponding ASCII characters.


safe

private static boolean[] safe
Characters that need not be encoded. This is much faster than using a BitSet, and for such a small array the space cost seems justified.

Constructor Detail

UriBuilder

public UriBuilder()
Default constructor - the init() method must be called befroe use.


UriBuilder

public UriBuilder(RunData data)
Constructor that takes the RunData as an argument.

Parameters:
data - The RunData associated with this builder.
Method Detail

init

public void init()
Initializes the builder for use by clearing any previous state.


init

public void init(RunData data)
Initialize with a RunData object

Parameters:
data -

add

protected void add(int type,
                   java.lang.String name,
                   java.lang.String value)

If the type is P (0), then add name/value to the pathInfo hashtable.

If the type is Q (1), then add name/value to the queryData hashtable.

Parameters:
type - Type (P or Q) of insertion.
name - A String with the name to add.
value - A String with the value to add.

addPair

protected void addPair(java.util.ArrayList list,
                       java.lang.String name,
                       java.lang.String value)
Add a key value pair (in the form of a 2 object array) to the provided list

Parameters:
list - List to add to.
name - A String with the name to add.
value - A String with the value to add.

add

protected void add(java.util.ArrayList list,
                   RequestParameters pp)
Method for a quick way to add all the parameters in a RequestParameters to a given List

Parameters:
list - The list of pairs to add to
pp - A RequestParameters.

add

protected void add(int type,
                   RequestParameters pp)
Method for a quick way to add all the parameters in a RequestParameters.

If the type is P (0), then add name/value to the pathInfo hashtable.

If the type is Q (1), then add name/value to the queryData hashtable.

Parameters:
type - Type (P or Q) of insertion.
pp - A RequestParameters.

addPathInfo

public UriBuilder addPathInfo(java.lang.String name,
                              java.lang.Object value)
Adds a name=value pair to the path_info string.

Parameters:
name - A String with the name to add.
value - An Object with the value to add.

addPathInfo

public UriBuilder addPathInfo(java.lang.String name,
                              java.lang.String value)
Adds a name=value pair to the path_info string.

Parameters:
name - A String with the name to add.
value - A String with the value to add.

addPathInfo

public UriBuilder addPathInfo(java.lang.String name,
                              double value)
Adds a name=value pair to the path_info string.

Parameters:
name - A String with the name to add.
value - A double with the value to add.

addPathInfo

public UriBuilder addPathInfo(java.lang.String name,
                              int value)
Adds a name=value pair to the path_info string.

Parameters:
name - A String with the name to add.
value - An int with the value to add.

addPathInfo

public UriBuilder addPathInfo(java.lang.String name,
                              long value)
Adds a name=value pair to the path_info string.

Parameters:
name - A String with the name to add.
value - A long with the value to add.

addPathInfo

public UriBuilder addPathInfo(java.lang.String name,
                              boolean value)
Adds a name=value pair to the path_info string.

Parameters:
name - A String with the name to add.
value - A double with the value to add.

addPathInfo

public UriBuilder addPathInfo(RequestParameters pp)
Adds a name=value pair for every entry in a RequestParameters object to the path_info string.

Parameters:
pp - A RequestParameters.

addQueryData

public UriBuilder addQueryData(java.lang.String name,
                               java.lang.Object value)
Adds a name=value pair to the query string.

Parameters:
name - A String with the name to add.
value - An Object with the value to add.

addQueryData

public UriBuilder addQueryData(java.lang.String name,
                               java.lang.String value)
Adds a name=value pair to the query string.

Parameters:
name - A String with the name to add.
value - A String with the value to add.

addQueryData

public UriBuilder addQueryData(java.lang.String name,
                               double value)
Adds a name=value pair to the query string.

Parameters:
name - A String with the name to add.
value - A double with the value to add.

addQueryData

public UriBuilder addQueryData(java.lang.String name,
                               int value)
Adds a name=value pair to the query string.

Parameters:
name - A String with the name to add.
value - An int with the value to add.

addQueryData

public UriBuilder addQueryData(java.lang.String name,
                               long value)
Adds a name=value pair to the query string.

Parameters:
name - A String with the name to add.
value - A long with the value to add.

addQueryData

public UriBuilder addQueryData(RequestParameters pp)
Adds a name=value pair for every entry in a RequestParameters object to the query string.

Parameters:
pp - A RequestParameters.

getA

public java.lang.String getA(java.lang.String name)
Create an anchor object. This call to getA():

 UriBuilder dui = new UriBuilder (data, "UserScreen" );
 dui.setName("Click Here").addPathInfo("user","jon");
 dui.getA();
 

would return the String:

<A HREF="http://www.server.com:80/servlets/Turbine/screen=UserScreen&amp;user=jon">Click Here</A>

Parameters:
name - A String with the name for the anchor.
Returns:
The anchor as a <A HREF="">name</A>.

getScriptName

public java.lang.String getScriptName()
Gets the script name (/servlets/Turbine).

Returns:
A String with the script name.

getServerName

public java.lang.String getServerName()
Gets the server name.

Returns:
A String with the server name.

getServerPort

public int getServerPort()
Gets the server port.

Returns:
A String with the server port.

getServerScheme

public java.lang.String getServerScheme()
Gets the server scheme (HTTP or HTTPS).

Returns:
A String with the server scheme.

remove

protected void remove(int type,
                      java.lang.String name)

If the type is P (0), then remove name/value from the pathInfo hashtable.

If the type is Q (1), then remove name/value from the queryData hashtable.

Parameters:
type - Type (P or Q) of removal.
name - A String with the name to be removed.

removePairByName

protected void removePairByName(java.util.ArrayList pairs,
                                java.lang.String name)
Helper method to remove one or more pairs by its name (ie key). It is intended to be used with queryData and pathInfo.

Parameters:
pairs - the list of pairs to look over for removal.
name - the name of the pair(s) to remove.

removePathInfo

public void removePathInfo()
Removes all the path info elements.


removePathInfo

public void removePathInfo(java.lang.String name)
Removes a name=value pair from the path info.

Parameters:
name - A String with the name to be removed.

removeQueryData

public void removeQueryData()
Removes all the query string elements.


removeQueryData

public void removeQueryData(java.lang.String name)
Removes a name=value pair from the query string.

Parameters:
name - A String with the name to be removed.

renderPathInfo

protected java.lang.String renderPathInfo(java.util.Vector data)
Deprecated. Prefer the ArrayList / StringBuffer form.

This method takes a Vector of key/value arrays and converts it into a URL encoded querystring format.

Parameters:
data - A Vector of key/value arrays.
Returns:
A String with the URL encoded data.

renderPathInfo

protected void renderPathInfo(java.util.ArrayList pairs,
                              java.lang.StringBuffer out)
This method takes a Vector of key/value arrays and writes it to the supplied StringBuffer as encoded path info.

Parameters:
pairs - A Vector of key/value arrays.
out - Buffer to which encoded path info is written

renderQueryString

protected java.lang.String renderQueryString(java.util.Vector data)
Deprecated. Prefer the ArrayList / StringBuffer form.

This method takes a Vector of key/value arrays and converts it into a URL encoded querystring format.

Parameters:
data - A Vector of key/value arrays.
Returns:
A String with the URL encoded data.

renderQueryString

protected void renderQueryString(java.util.ArrayList data,
                                 java.lang.StringBuffer out)
This method takes a List of key/value arrays and writes it to the provided StringBuffer in encoded query string format.

Parameters:
data - A Vector of key/value arrays.
out - Buffer to which encoded query string is written.

renderPairs

protected void renderPairs(java.util.ArrayList pairs,
                           java.lang.StringBuffer out,
                           char pairSep,
                           char keyValSep)
This method takes a List of key/value arrays and converts it into a URL encoded key/value pair format with the appropriate separator.

Parameters:
out - the buffer to write the pairs to.
pairs - A List of key/value arrays.
pairSep - the character to use as a separator between pairs. For example for a query-like rendering it would be '&'.
keyValSep - the character to use as a separator between key and value. For example for a query-like rendering, it would be '='.

setAction

public UriBuilder setAction(java.lang.String action)
Sets the action= value for this URL.

By default it adds the information to the path_info instead of the query data.

Parameters:
action - A String with the action value.
Returns:
A UriBuilder (self).

setTarget

public UriBuilder setTarget(java.lang.String template)
Sets the target = value for this URL.

By default it adds the information to the path_info instead of the query data.

Parameters:
template - A String with the template value.
Returns:
A UriBuilder (self).

setRedirect

public UriBuilder setRedirect(boolean doRedirect)
Sets whether we want to redirect or not.

Parameters:
doRedirect - True if it should redirect.
Returns:
A UriBuilder (self).

setRelative

public UriBuilder setRelative(boolean b)
if true, the scheme, domain, and port will not be included in the String representation of this uri..

Parameters:
b - a boolean
Returns:
a UriBuilder (self)

isRelative

public boolean isRelative()
Will a call to toString() generate a relative url? where relative means no scheme, domain, and port info

Returns:
a boolean

setEncodeUrl

public UriBuilder setEncodeUrl(boolean b)
Can be used to disable url rewriting.

Parameters:
b - a boolean
Returns:
a UriBuilder (self)

isEncodeUrl

public boolean isEncodeUrl()
Will a call to toString() add session info if needed to maintain a session. Does not determine whether the url will be rewritten, only that it might be.

Returns:
a boolean

toString

public java.lang.String toString()
Builds the URL with all of the data URL-encoded as well as encoded using HttpServletResponse.encodeUrl().

 UriBuilder dui = new UriBuilder (data, "UserScreen" );
 dui.addPathInfo("user","jon");
 dui.toString();
 

The above call to toString() would return the String:

http://www.server.com/servlets/Turbine/screen/UserScreen/user/jon

Returns:
A String with the built URL.

toString

public static java.lang.String toString(RunData data)
Given a RunData object, get a URI for the request. This is necessary sometimes when you want the exact URL and don't want UriBuilder to be too smart and remove actions, screens, etc. This also returns the Query Data where UriBuilder normally would not. This method always returns absolute url's.

Parameters:
data - A Turbine RunData object.
Returns:
A String with the URL representing the RunData.

toString

public static java.lang.String toString(RunData data,
                                        boolean isAbsolute)
Given a RunData object, get a URI for the request. This is necessary sometimes when you want the exact URL and don't want UriBuilder to be too smart and remove actions, screens, etc. This also returns the Query Data where UriBuilder normally would not.

Parameters:
data - A Turbine RunData object.
isAbsolute - to determine absolute vs. relative links.
Returns:
A String with the URL representing the RunData.

writeFastEncoded

protected static final void writeFastEncoded(java.lang.String in,
                                             java.lang.StringBuffer out)
URL encodes in and writes it to out. If the string is null, 'null' will be written. This method is faster if the string does not contain any characters needing encoding. It adds some penalty for strings which actually need to be encoded. for short strings ~20 characters the upside is a 75% decrease. while the penalty is a 10% increase. As many query parameters do not need encoding even in i18n applications it should be much better to delay the byte conversion.

Parameters:
in - String to write.
out - Buffer to write to.

writeEncoded

protected static final void writeEncoded(java.lang.String in,
                                         java.lang.StringBuffer out)
URL encodes in and writes it to out. If the string is null, 'null' will be written.

Parameters:
in - String to write.
out - Buffer to write to.

hasPathInfo

public boolean hasPathInfo()
Does this URI have path info.


hasQueryData

public boolean hasQueryData()
Does this URI have query data.