wt.httpgw
Class URLFactory

java.lang.Object
  wt.httpgw.URLFactory

public final class URLFactory
extends Object

A URL and HREF factory for Windchill application resources.

Instances are capable of generating URL objects or HREF strings to resources in a particular Windchill system. Each instance corresponds to one Windchill system from which URL mappings are obtained. Each factory instance has an optional request URI from which relative HREF strings are generated. If no request URI is set, only absolute HREFs are returned. Each system has a base URL corresponding to the application's virtual directory root. Resources are requested using paths relative to this base URL (e.g. wt/clients/images/myimage.jpg).

Instances are constructed given a codebase URL for a Windchill system. This URL is any URL that can be used to download configuration files corresponding to the desired system. Configuration files (e.g. wt.properties, urlmap.properties) from the server codebase are used to determine the system's base URL and any URL mappings that may apply to certain resources. The base URL for a system may be different than the server codebase URL used to construct the factory.

URL mappings allow Windchill administrators to override the location of specific resources such as files, directories, or servlets which are otherwise located relative to the system's base URL. Mappings may override the entire URL or just specific components such as protocol, host, port, or path.

Typiccal usage in a JSP is to instantiate using the no-arg constructor, set the requestURI property from the servlet request, generate a HTML tag in the response to the application root using the getBaseHREF() method, then reset the factory's request URI to the application root using the setRequestUri method with the same value.

Resource-specific helper methods can be created which encapsulate the URL and HREF generating methods within methods that are more meaningful to the target resource. For example, a servlet that uses path info elements and/or query string parameters in a well defined way can be exposed factory methods that have more meaningful arguments. These helper methods should accept an instance of a URL factory as input along with the resource-specific arguments.

NOTE: Instances of a URL factory are not thread safe. Each instance contains buffers that may be reused when encoding URLs.

Mapping File

(UL)The mapping file will consist of a series of key/value pairs separated by the '=' character. Further '=' characters will be left as part of the value part of the pair. Comments may be inserted into the file by using the '#' character and blank lines will be ignored. The default Windchill file for URL Mappings is the file urlmap.properties located in the Windchill codebase directory.

Mapping Rules

By default, any parameter left out from the description below will be taken from the curent URLFactory properties. For example, if a protocol is left out, the protocol for the current RequestURI (if set) or the server base URL will be utilized. The following are the mapping formats that may be used in the mappings file. Any other mappings will not be mapped properly.



Protocol://hostname:port/windchill-codebase/package-path/resource	Will map the resource to a specific resource, located in a Windchill codebase and package path on the hostname's server, through a specified protocol and port.
Protocol://hostname:port/windchill-codebase/package-path/	will map the package to a specific package path and Windchill codebase, located on hostname's server, through a specified protocol and port.
Protocol://hostname/windchill-codebase/package-path/resource	will map the resource to a specific windchill codeebase and package path, located on a hostname's server, through a specified protocol. The port will be retrieved from URLFactory.
Protocol://hostname/windchill-codebase/package-path/	will map the package path to a specific windchill codebase and package path, located on hostname's server, through a specified protocol. The port will be retrieved from the URLFactory.
://hostname	Will map the resource to a new hostname maintaining the same protocol, port windchill codebase and package path.
://hostname:port	Will map the resource to a new hostname and port maintaining the same protocol codebase and package path.
://hostname/windchill-codebase/package-path/	Will map the resource to a new hostname, Windchill codebase and package path using the same port and protocol
://hostname:port/windchill-codebase/package-path/	Will map the resource to a new hostname port and windchill codebase/package path using the same protocol
://:port/windchill-codebase/package-path/	Will map the resource to a new port on the same host with a new path to the Windchill codebase and package path.
://:port/windchill-codebase/package-path/resource	Will map the resource to a new port and resource path (including Windchill codebase)
/package-path/	Will remap a given package path to new package path including the Windchill codebase, while maintaining the same protocol, port and hostname of the current Windchill server. (se examples below)
package-path/	Will remap a given package path to a new package path using the current Windchill codebase, while maintaining the same protocol, port and hostname of the current Windchill server. (see examples below)
/package-path/resource	Will remap a given resource to a new Windchill codebase and package path as defined while maintaining the same protocol, port and hostname of the current Windchill server.
package-path/resource	Will remap a given resource to a new package path utilizing the same Windchill codebase while maintaining the same protocol, port and hostname of the current Windchill server.

Supported API: true
Extendable: false

Constructor Summary

URLFactory()
Construct a URL factory for the default (local) server system.

URLFactory(URL server_codebase)
Construct a URL factory for a specified server system.

Method Summary

String	determineResource(String aRequestPath) This method will take a request resource path which may start with a '/' and determine from this the Windchill resource path based on the Windchill codebase being common between the URLFactory, and the requested resource path.
String	getBaseHREF() This method will return the fully qualified path to the Windchill Codebase.
String	getBaseHREFFromRequestURI() Get the HREF which represents the path from the current Request URI to the Windchill codebase.
URL	getBaseURL() Get base URL for the referenced Windchill system as a URL object.
String	getEncoding() Get the character encoding used to encode character to octets before the are hex escaped into generated URLs or HREFs.
String	getFullyQualifiedRequestURI() This method will get the Fully Qualified Request URI returning the Protocol://Hostname[:Port]/[PackagePath/][Resource][?QueryString] .
String	getHREF(String resource) Generate a HREF string to the identified resource.
String	getHREF(String resource, boolean fullyQualified) Generate a HREF string to the identified resource.
String	getHREF(String resource, HashMap params) Generate a HREF string to the identified resource.
String	getHREF(String resource, HashMap params, boolean fullyQualified) Generate a HREF string to the identified resource.
String	getHREF(String resource, String query_string) Generate a HREF string to the identified resource.
String	getHREF(String resource, String params, boolean fullyQualified) Generate a HREF string to the identified resource.
String	getRequestURI() Get the request URI of this factory.
URL	getURL(String resource) Generate a URL to the identified resource.
URL	getURL(String resource, HashMap params) Generate a URL object to the identified resource.
URL	getURL(String resource, String query_string) Generate a URL to the identified resource.
HashMap	parseQueryString(String query_string) Parses a query string passed from the client to the server and builds a HashMap object with key-value pairs.
void	setEncoding(String encoding) Set the character encoding used to encode characters to octets before they are hex escaped into generated URLs or HREFs.
void	setRequestURI(String request_uri) Set the request URI of this factory.
void	setRequestURIFromURL(URL request_uri) Set the request URI of this factory.
String	setRequestURItoBase() Set the request URI for this factory to the Windchill Codebase of the URLFactory's Windchill system.
void	setRequestURL(String aScheme, String aHostname, String aRequest_URI) Set the request URL for this factory.

Methods inherited from class java.lang.Object

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

Constructor Detail

URLFactory

public URLFactory()
           throws WTException

Construct a URL factory for the default (local) server system. The Windchill codebase will be the codebase of the local server.

Supported API: true

Throws:

WTException

URLFactory

public URLFactory(URL server_codebase)
           throws WTException

Construct a URL factory for a specified server system. The URL should point the URLFactory to the codebase of the desired Windchill system.

For example:

http://host.domain:8080/Windchill/

Supported API: true

Parameters:

server_codebase - codebase URL corresponding to the desired system.

Throws:

WTException

Method Detail

setRequestURIFromURL

public void setRequestURIFromURL(URL request_uri)

Set the request URI of this factory. Generated HREF strings for resources will be relative to this base URI.

Setting to a request URI will cause all generated HREFs to be relative to the given request URI. Setting to null will force all generated HREFs to be fully qualified.

Supported API: true

Parameters:

request_uri - request URI

setRequestURL

public void setRequestURL(String aScheme,
                          String aHostname,
                          String aRequest_URI)

Set the request URL for this factory. If the request URI includes a host and and protocol (scheme), the specified scheme and hostname passed in will overwrite the requested URI. This method therefore supports absolute URIs and relative URIs.

Supported API: true

Parameters:

aScheme - The scheme for the URL ( for example https )

aHostname - The hostname of the request. Some browsers may include the port in this string. This method will accept this form and parse the port successfully.

aRequest_URI - The request uri for the request. This may be relative or absolute.

setRequestURItoBase

public String setRequestURItoBase()

Set the request URI for this factory to the Windchill Codebase of the URLFactory's Windchill system. The base HREF will be returned to the Windchill codebase.

Supported API: true

Returns:

String The HREF to the windchill codebase.

setRequestURI

public void setRequestURI(String request_uri)
                   throws NullPointerException

Set the request URI of this factory. Generated HREF strings for resources will be relative to this base URI.

Setting to a request URI will cause all generated HREFs to be relative to the given request URI. Setting to null will force all generated HREFs to be fully qualified. The specified request URI may be fully qualified or relative to the current request URI. The rules follow those which are defined in the HTTP Specification for valid HREF formats. If there is no current request URI, relative URIs will be interpreted relative to the Windhcill codebase URL.

Notes: If a relative request_uri is passed in as an argument to this method with the form ../[../]newpath/[resource][?query_string] the ../ much be a valid pathing relative to the current Request URI. For example, if the current Request URI is equal to /Windchill/wt/httpgw and this method is called with ../../../../directory this would be invalid and the Request URI will not be changed. A NullPointerException will be thrown by the method which can be used in the client to trap this exception.

Supported API: true

Parameters:

request_uri - request URI in string form to allow relative URI syntax

Throws:

NullPointerException - Optional exception used to catch invalid relative Request URI paths, or if a relative Request URI is desired and the current Request URI is null.

getRequestURI

public String getRequestURI()

Get the request URI of this factory. This method will not return any resource or query strings associated with the request URI. For a fully qualified requestURI, use getFullyQualifiedRequestURI( )

Supported API: true

Returns:

request URI string (null if not set)

See Also:

getFullyQualifiedRequestURI()

getFullyQualifiedRequestURI

public String getFullyQualifiedRequestURI()

This method will get the Fully Qualified Request URI returning the Protocol://Hostname[:Port]/[PackagePath/][Resource][?QueryString] . If the Request URI is null, null will be returned.

Supported API: true

Returns:

The fully qualified Request URI (null if not set)

See Also:

getRequestURI()

setEncoding

public void setEncoding(String encoding)

Set the character encoding used to encode characters to octets before they are hex escaped into generated URLs or HREFs. The default encoding is UTF8 as recommended in RFC 2718. Setting to null restores the default encoding.

Supported API: true

Parameters:

encoding - character encoding name

getEncoding

public String getEncoding()

Get the character encoding used to encode character to octets before the are hex escaped into generated URLs or HREFs.

Supported API: true

Returns:

character encoding name

getBaseURL

public final URL getBaseURL()

Get base URL for the referenced Windchill system as a URL object. This normally corresponds to the Windchill application virtual directory root, but the value returned should only be assumed to refer to the application's static document root. URL mappings may apply to any dynamic resources, including JSPs, so the factory should be used to contruct references to all resources.

Supported API: true

Returns:

base URL

getBaseHREF

public final String getBaseHREF()

This method will return the fully qualified path to the Windchill Codebase. If this is the String that is desired for the <BASE> tag, it may be used, however getFullyQualifiedRequestURI() should be used where possible to set the base tag relative to the current Request URI and not the Windchill codebase.

Supported API: true

@return The fully qualified base to the Windchill codebase.

getBaseHREFFromRequestURI

public final String getBaseHREFFromRequestURI()

Get the HREF which represents the path from the current Request URI to the Windchill codebase. If the current RequestURI is null, the fully qualified HREF to the Windchill codebase will be returned.

Note: This value should NOT be used to set HTML <BASE> tags. Use getFullyQualifiedRequestURI() to get a fully qualified base tag for the current Request URI.

Supported API: true

Returns:

base HREF to the Windchill Codebase

@see getFullyQualifiedRequestURI()

getURL

public final URL getURL(String resource)

Generate a URL to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will not be ignored, and will return the URL using the current URLFactory hostname, protocol and port. Generate a URL to the identified resource.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.

Thread Safe: true (Do not share factory instances between threads)

Supported API: true

Parameters:

resource - The resource path

Returns:

resource URL

determineResource

public String determineResource(String aRequestPath)

This method will take a request resource path which may start with a '/' and determine from this the Windchill resource path based on the Windchill codebase being common between the URLFactory, and the requested resource path. This is useful, if there is a need to use request.getRequestURI( ) which will return an absolute resource path, but there is a need to utilize the mapping file on the system.

Supported API: true

Parameters:

aRequestPath - The request URI to resolve. If it does not start with a '/' the the String will be returned.

Returns:

The transformed String containing either the original string (if a fully qualified string was passed in, or the path to the resource within the current codebase. If the path can not be resolved to the current Windchill system, the string passed in is returned.

getHREF

public String getHREF(String resource,
                      boolean fullyQualified)

Generate a HREF string to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will be ignored, and will return the string if HREFs are not fully qualified, or the fully qualified HREF using the current URLFactory hostname, protocol and port.

Path elements containing non-ASCII characters are encoded into bytes and then URL encoded. If request URI is set, this may return a relative HREF.

This method will return a fully qualified HREF. This should only is cases where a fully qualified HREF is required. For example, opening a new window using javascript.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.

Thread Safe: true (Do not share factory instances between threads)

Supported API: true

@param path resource path

Parameters:

fullyQualified - whether the HREF is to be fully qualified (independent of URLFactory configuration)

Returns:

resource HREF string

getHREF

public String getHREF(String resource)

Generate a HREF string to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will be ignored, and will return the string if HREFs are not fully qualified, or the fully qualified HREF using the current URLFactory hostname, protocol and port.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.
Path elements containing non-ASCII characters are encoded into bytes and then URL encoded. If request URI is set, this may return a relative HREF.

NOTE: This method is not thread safe. Do not share factory instances between threads.

Supported API: true

@param path resource path

Returns:

resource HREF string

getURL

public URL getURL(String resource,
                  String query_string)

Generate a URL to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will be ignored, and will return the URL using the current URLFactory hostname, protocol and port. Path elements and query strings containing non-ASCII characters are encoded into bytes and then URL encoded.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.

Thread Safe: true (Do not share factory instances between threads)

Supported API: true

@param resource The resource path

Parameters:

query_string - The query string to add to the URL

Returns:

resource URL

getHREF

public String getHREF(String resource,
                      String params,
                      boolean fullyQualified)

Generate a HREF string to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will be ignored, and will return the string if HREFs are not fully qualified, or the fully qualified HREF using the current URLFactory hostname, protocol and port.

Path elements and request parameters containing non-ASCII characters that are already encoded. If request URI is set, this may return a relative HREF.

This method will return a fully qualified HREF if the flag is true. This should only is cases where a fully qualified HREF is required. For example, opening a new window using javascript.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.

Thread Safe: true (Do not share factory instances between threads)

Supported API: true

@param path resource path

Parameters:

params - The list of Parameters already encoded

fullyQualified - whether the HREF is to be fully qualified (independent of URLFactory configuration)

Returns:

resource HREF string

getHREF

public String getHREF(String resource,
                      String query_string)

Generate a HREF string to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will be ignored, and will return the string if HREFs are not fully qualified, or the fully qualified HREF using the current URLFactory hostname, protocol and port.

Path elements and request parameters containing non-ASCII characters that are already encoded. If request URI is set, this may return a relative HREF.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.

Thread Safe: true (Do not share factory instances between threads)

Supported API: true

@param path resource path

Parameters:

query_string - The list of Parameters already encoded

Returns:

resource HREF string

getURL

public URL getURL(String resource,
                  HashMap params)

Generate a URL object to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will be ignored, and will return the URL using the current URLFactory hostname, protocol and port.

Path elements and request parameters containing non-ASCII characters that are encoded within this method before returning.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.

Thread Safe: true (Do not share factory instances between threads)

Supported API: true

@param resource resource path

Parameters:

params - The hashmap on un-encoded parameters.

Returns:

URL to the resource

getHREF

public String getHREF(String resource,
                      HashMap params,
                      boolean fullyQualified)

Generate a HREF string to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will be ignored, and will return the string if HREFs are not fully qualified, or the fully qualified HREF using the current URLFactory hostname, protocol and port.

Path elements and request parameters containing non-ASCII characters are encoded into bytes and then URL encoded. Parameter values should be strings or arrays of strings for multi-valued parameters. If request URI is set, this may return a relative HREF.

This method will return a fully qualified HREF if the flag is true. This should only is cases where a fully qualified HREF is required. For example, opening a new window using javascript.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.

Thread Safe: true (Do not share factory instances between threads)

Supported API: true

@param path resource path

Parameters:

params - The Hashmap of Parameters

fullyQualified - whether the HREF is to be fully qualified (independent of URLFactory configuration)

Returns:

resource HREF string

getHREF

public String getHREF(String resource,
                      HashMap params)

Generate a HREF string to the identified resource. The resource path is a full path starting at the application root directory. The path is relative to the Windchill application root. A leading '/' will be ignored, and will return the string if HREFs are not fully qualified, or the fully qualified HREF using the current URLFactory hostname, protocol and port.

Path elements and request parameters containing non-ASCII characters are encoded into bytes and then URL encoded. Parameter values should be strings or arrays of strings for multi-valued parameters. If request URI is set, this may return a relative HREF.

NOTE: If usage of request.getRequestURI( ) is required, make sure to pass the request through determineResource(request.getRequestURI()); first, so that the resource path relative to the Windchill System can be determined. Failure to do so will not allow proper usage of the mapping file.

Thread Safe: true (Do not share factory instances between threads)

Supported API: true

@param path resource path

Parameters:

params - The hashmap of parameters.

parseQueryString

public HashMap parseQueryString(String query_string)

Parses a query string passed from the client to the server and builds a HashMap object with key-value pairs. The query string should be in the form of a string packaged by the GET or POST method, that is, it should have key-value pairs in the form key=value, with each pair separated from the next by a & character. This is the format produced by the getURL and getHREF methods.

A key can appear more than once in the query string with different values. However, the key appears only once in the hashtable, with its value being an array of strings containing the multiple values sent by the query string.

The keys and values in the hashtable are stored in their decoded form, so an + characters are converted to spaces and any hex escaped octets are converted to bytes before the octet sequence is decoded into characters using the factory's current character encoding.

NOTE: This method is not thread safe. Do not share factory instances between threads.

Supported API: true

Parameters:

query_string - string containing encoded query string

Returns:

a HashTable object built from the parsed key-value pairs. If query_string is null, an empty HashMap will be returned.