com.fatwire.cs.core.uri
Class AbstractAssembler

java.lang.Object
  com.fatwire.cs.core.uri.AbstractAssembler

All Implemented Interfaces:

Assembler

Direct Known Subclasses:

QueryAssembler

public abstract class AbstractAssembler
extends java.lang.Object
implements Assembler

Base implementation of an Assembler. This class implements all the methods of the Assembler interface, but calls out to abstract methods in order to get relevant components for URI assembly and disassembly. This class also provides a number of utility methods that can be helpful in assembly and disassembly. The QueryAssembler class is the primary implementation and is most likely the first place to start in developing a custom assembler.

Since:

18-Oct-2004 12:40:50 PM

See Also:

Assembler, QueryAssembler

Nested Class Summary

protected static class	AbstractAssembler.AssemblyContext This class is a wrapper over the Definition object.
protected static class	AbstractAssembler.DisassemblyContext This class is a wrapper over the incoming URI that contains an accessor to arbitrary context parameters that extending classes can specify.

Field Summary

protected static java.lang.String

PAGENAME This string corresponds to the required variable for the Content Server app type, pagename.

Fields inherited from interface com.fatwire.cs.core.uri.Assembler

LOG_NAME, PROP_PATH_PREFIX, PROP_URIBASE_BLOB_SERVER, PROP_URIBASE_CACHE_SERVER, PROP_URIBASE_CATALOG_MANAGER, PROP_URIBASE_CONTENT_SERVER, PROP_URIBASE_COOKIE_SERVER, PROP_URIBASE_DISPATCH_MANAGER, PROP_URIBASE_PAGE_DISPATCH_SERVER, PROP_URIBASE_SATELLITE_SERVER, PROP_URIBASE_SEED_DISPATCH_SERVER, PROP_URIBASE_SYNC_SEED_DISPATCH_SERVER, PROP_URIBASE_TREE_MANAGER

Constructor Summary

protected

AbstractAssembler() Constructor.

Method Summary

java.net.URI	assemble(Definition def) Constructs a URI from the Definition provided.
protected java.lang.String	decode(java.lang.String string) URLDecodes a string using the encoding specified by this class.
Definition	disassemble(java.net.URI uri, Definition.ContainerType ct) Constructs a Definition from the URI provided, using the container type specified.
protected java.lang.String	encode(java.lang.String string) URLEncodes a string using the encoding specified by this class.
protected abstract Definition.AppType	getAppType(AbstractAssembler.DisassemblyContext ctx) Return the AppType for the URI specified.
protected AbstractAssembler.AssemblyContext	getAssemblyContext(Definition def) Returns an assembly context object given the input definition.
protected abstract java.lang.String	getAuthority(AbstractAssembler.AssemblyContext ctx) Returns the authority (host and port) for the assembly context specified.
protected abstract java.lang.String	getAuthority(AbstractAssembler.DisassemblyContext ctx) Returns the authority (host:port etc) for the URI specified
protected AbstractAssembler.DisassemblyContext	getDisassemblyContext(java.net.URI uri)
protected abstract java.lang.String	getFragment(AbstractAssembler.AssemblyContext ctx) Get the fragment corresponding to this assembly context.
protected abstract java.lang.String	getFragment(AbstractAssembler.DisassemblyContext ctx) Returns the fragment for the uri specified
protected org.apache.commons.logging.Log	getLog() Return a Log object that is appropriate for use with this component.
protected abstract java.lang.String	getPath(AbstractAssembler.AssemblyContext ctx) Returns the path for the assembly context specified.
protected java.lang.String	getProperty(java.lang.String name, java.lang.String dephault) Get the property value of a specified property.
protected abstract java.lang.String	getQuery(AbstractAssembler.AssemblyContext ctx) This method returns the query string for the URI given the assembly context specified.
protected abstract java.util.Map	getQuery(AbstractAssembler.DisassemblyContext ctx) Returns a map of query name/value pairs for the URI specified.
protected abstract Definition.SatelliteContext	getSatelliteContext(AbstractAssembler.DisassemblyContext ctx) Return the Satellite Context for this Definition
protected abstract java.lang.String	getScheme(AbstractAssembler.AssemblyContext ctx) Returns the scheme (protocol) for the assembly context specified.
protected abstract java.lang.String	getScheme(AbstractAssembler.DisassemblyContext ctx) Return the scheme (http, https, etc.) for the URI specified
protected abstract boolean	getSessionEncode(AbstractAssembler.DisassemblyContext ctx) Get the session encode flag for this Definition.
protected java.util.Map	parseQueryString(java.lang.String qry) Parse a query string and put the parameters into a map.
void	setProperties(java.util.Properties props) Sets the properties into the assembler.

Methods inherited from class java.lang.Object

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

Field Detail

PAGENAME

protected static final java.lang.String PAGENAME

This string corresponds to the required variable for the Content Server app type, pagename.

See Also:

Constant Field Values

Constructor Detail

AbstractAssembler

protected AbstractAssembler()

Constructor. Upon object construction, support for UTF-8 encoding is tested, and the result is cached for future use in the encode() and decode() methods.

UTF-8 is the recommended URLEncoding:

• http://www.w3.org/TR/html40/appendix/notes.html#non-ascii-chars
• http://java.sun.com/j2ee/1.4/docs/tutorial/doc/WebI18N5.html
• http://www.ietf.org/rfc/rfc2396.txt

Method Detail

getLog

protected final org.apache.commons.logging.Log getLog()

Return a Log object that is appropriate for use with this component. The log object is not stored as a member variable because this object may be cached, and this would make it impossible to re-set the log.

Returns:

Log

setProperties

public final void setProperties(java.util.Properties props)

Sets the properties into the assembler. The properties passed in correspond to the properties named in Assembler, and they contain information about the url path for each app type. Some containers may not permit the use of a url base, in which case the property value supplied will be null.

Property values do not need to be unique.

This method must be called by all Assemblers before any other Assembler methods are called.

Specified by:

setProperties in interface Assembler

Parameters:

props - The properties

getProperty

protected final java.lang.String getProperty(java.lang.String name,
                                             java.lang.String dephault)

Get the property value of a specified property.

Parameters:

name - property name

dephault - default property value or null

Returns:

value of the property or the default value if the property does not have a value.

assemble

public java.net.URI assemble(Definition def)
                      throws java.net.URISyntaxException

Constructs a URI from the Definition provided. Individual arguments are determined by invoking the corresponding getter methods in this class. Overriding classes may either override this method or one or more of the corresponding getter methods.

The components do not need to be encoded as this method will encode all values that require encoding.

The corresponding methods are called in the following order:

1. AbstractAssembler.getAssemblyContext(Definition)
2. AbstractAssembler.getScheme(AssemblyContext)
3. AbstractAssembler.getAuthority(AssemblyContext)
4. AbstractAssembler.getPath(AssemblyContext)
5. AbstractAssembler.getQuery(AssemblyContext)
6. AbstractAssembler.getFragment(AssemblyContext)

and the AssemblyContext object is not modified by this method. It is the same object in all of these methods. Most subclasses will not need to override this method, and should instead override the getter methods specified above instead.

Specified by:

assemble in interface Assembler

Parameters:

def -

Returns:

assembled URI

Throws:

java.net.URISyntaxException

See Also:

http://www.ietf.org/rfc/rfc2396.txt, AbstractAssembler.encode(String), AbstractAssembler.decode(String)

getScheme

protected abstract java.lang.String getScheme(AbstractAssembler.AssemblyContext ctx)

Returns the scheme (protocol) for the assembly context specified.

Parameters:

ctx - Assembly context object

Returns:

scheme

getAuthority

protected abstract java.lang.String getAuthority(AbstractAssembler.AssemblyContext ctx)

Returns the authority (host and port) for the assembly context specified.

Parameters:

ctx - Assembly context object

Returns:

authority

getPath

protected abstract java.lang.String getPath(AbstractAssembler.AssemblyContext ctx)

Returns the path for the assembly context specified. Do not quote contents in this string - this will be handled by AbstractAssembler.assemble(com.fatwire.cs.core.uri.Definition).

Parameters:

ctx - Assembly context object

Returns:

path

getQuery

protected abstract java.lang.String getQuery(AbstractAssembler.AssemblyContext ctx)

This method returns the query string for the URI given the assembly context specified. The query string is expected to be properly quoted. A typical implementation might construct part of the query string like this: result.append('&').append(encode(key)).append('=').append(encode(value));

Parameters:

ctx - Assembly context object

Returns:

query string fit to be inserted into a URI.

See Also:

Encode provides a helpful method for quoting illegal characters in the query string.

getFragment

protected abstract java.lang.String getFragment(AbstractAssembler.AssemblyContext ctx)

Get the fragment corresponding to this assembly context. This string will be quoted by AbstractAssembler.assemble(com.fatwire.cs.core.uri.Definition).

Parameters:

ctx - Assembly context object

Returns:

fragment

getAssemblyContext

protected AbstractAssembler.AssemblyContext getAssemblyContext(Definition def)

Returns an assembly context object given the input definition.

Parameters:

def - input definition

Returns:

AssemblyContext

See Also:

AbstractAssembler.AssemblyContext

disassemble

public Definition disassemble(java.net.URI uri,
                              Definition.ContainerType ct)
                       throws java.net.URISyntaxException

Constructs a Definition from the URI provided, using the container type specified. The primary Definition components are retrieved from the uri using the six getter methods taking a AbstractAssembler.DisassemblyContext object as the argument. If through the decoding process, a method determines that the URI provided does not correspond to the current assembler, the assembler should set the ownership to foreign. This will prevent any further processing (and it is more efficient than throwing an exception).

Methods are called in the following order:

1. AbstractAssembler.getDisassemblyContext(URI)
2. AbstractAssembler.getQuery(DisassemblyContext)
3. AbstractAssembler.getAppType(DisassemblyContext)
4. AbstractAssembler.getSatelliteContext(DisassemblyContext)
5. AbstractAssembler.getSessionEncode(DisassemblyContext)
6. AbstractAssembler.getScheme(DisassemblyContext)
7. AbstractAssembler.getAuthority(DisassemblyContext)
8. AbstractAssembler.getFragment(DisassemblyContext)

Failing quickly is beneficial to performance, since Content Server will send every URI to each assembler until a match is found.

Overriding classes may either override this method or one or more of the corresponding getter methods (overriding the getter methods is recommended for most situations).

Users overriding this method should note that the assemble() method created a uri such that the five components were encoded using UTF-8 if required. Therefore, to disassemble a URI, components should not be retrieved using the getRaw* methods, because that will return a component that has not been decoded.

Specified by:

disassemble in interface Assembler

Parameters:

uri -

ct - the container type to be set in the returned Definition

Returns:

re-assembled Definition

Throws:

java.net.URISyntaxException

See Also:

Definition, Definition.ContainerType

getSessionEncode

protected abstract boolean getSessionEncode(AbstractAssembler.DisassemblyContext ctx)

Get the session encode flag for this Definition.

Parameters:

ctx - DisassemblyContext object containing the URI, context parameters, and a flag inidicating whether or not this assembler is capable of disassembling this URI.

Returns:

true or false, return value ignored if ownership is foreign.

getSatelliteContext

protected abstract Definition.SatelliteContext getSatelliteContext(AbstractAssembler.DisassemblyContext ctx)

Return the Satellite Context for this Definition

Parameters:

ctx - DisassemblyContext object containing the URI, context parameters, and a flag inidicating whether or not this assembler is capable of disassembling this URI.

Returns:

satellite context, or null if ownership is foreign.

getScheme

protected abstract java.lang.String getScheme(AbstractAssembler.DisassemblyContext ctx)

Return the scheme (http, https, etc.) for the URI specified

Parameters:

ctx - DisassemblyContext object containing the URI, context parameters, and a flag inidicating whether or not this assembler is capable of disassembling this URI.

Returns:

scheme, or null if ownership is foreign.

getAuthority

protected abstract java.lang.String getAuthority(AbstractAssembler.DisassemblyContext ctx)

Returns the authority (host:port etc) for the URI specified

Parameters:

ctx - DisassemblyContext object containing the URI, context parameters, and a flag inidicating whether or not this assembler is capable of disassembling this URI.

Returns:

authority or null if ownership is foreign.

getFragment

protected abstract java.lang.String getFragment(AbstractAssembler.DisassemblyContext ctx)

Returns the fragment for the uri specified

Parameters:

ctx - DisassemblyContext object containing the URI, context parameters, and a flag inidicating whether or not this assembler is capable of disassembling this URI.

Returns:

fragment or null if ownership is foreign.

getAppType

protected abstract Definition.AppType getAppType(AbstractAssembler.DisassemblyContext ctx)

Return the AppType for the URI specified.

Parameters:

ctx - DisassemblyContext object containing the URI, context parameters, and a flag inidicating whether or not this assembler is capable of disassembling this URI.

Returns:

AppType or null if ownership is foreign.

getDisassemblyContext

protected AbstractAssembler.DisassemblyContext getDisassemblyContext(java.net.URI uri)

getQuery

protected abstract java.util.Map getQuery(AbstractAssembler.DisassemblyContext ctx)

Returns a map of query name/value pairs for the URI specified. The returned map contains String/String[] pairs, not String/String pairs.

Parameters:

ctx - DisassemblyContext object containing the URI, context parameters, and a flag inidicating whether or not this assembler is capable of disassembling this URI.

Returns:

Map containing String/String[] name/value pairs for the URi being specified, or null if the ownership is foreign.

encode

protected final java.lang.String encode(java.lang.String string)

URLEncodes a string using the encoding specified by this class.

Parameters:

string -

Returns:

encoded string

Throws:

java.lang.IllegalStateException - if UTF-8 encoding is not supported and the platform's default encoding is not supported.

decode

protected final java.lang.String decode(java.lang.String string)

URLDecodes a string using the encoding specified by this class.

Parameters:

string - encoded string

Returns:

decoded string

Throws:

java.lang.IllegalStateException - if UTF-8 encoding is not supported and the platform's default encoding is not supported.

java.lang.IllegalArgumentException - if the string is not well-formed for decoding.

parseQueryString

protected final java.util.Map parseQueryString(java.lang.String qry)

Parse a query string and put the parameters into a map. Input parameters will be URLDecoded prior to their addition into the resultant map.

Note that the map returned contains a String[] as the value, not a single String value This provides support for query strings with multiple values for a given parameter name.

Parameters:

qry -

Returns:

map containing String/String[] pairs.

Throws:

java.lang.IllegalArgumentException - if there are mistakes in the string that make it impossible to parse.