com.ibm.portal.state
Interface URLFactory

All Superinterfaces:

Disposable, ServerContextProvider

public interface URLFactory
extends ServerContextProvider, Disposable

Factory that provides methods to obtain engine URLs as well as resource URLs. Engine URLs are URLs that can carry navigational state. Resource URLs point to generic resources (e.g. icons, files, voice grammars, URIs etc.).

Since:

6.0

Method Summary

ServerContext	getServerContext() Returns information about the URL configuration in the scope of the current request.
DisposableURL	newResourceURL(java.lang.String name, PortalResources.Type type) Creates a DisposableURL object that points to a generic resource.
DisposableURL	newResourceURL(java.lang.String name, PortalResources.Type type, PortalResources.State state) Creates a DisposableURL object that points to a generic resource.
DisposableURL	newResourceURL(java.lang.String name, Theme theme, PortalResources.Type type) Creates a DisposableURL object that points to a generic resource.
DisposableURL	newResourceURL(java.lang.String name, Theme theme, PortalResources.Type type, PortalResources.State state) Creates a DisposableURL object that points to a generic resource.
EngineURL	newURL(Constants.Clone type) Creates a new EngineURL object.
EngineURL	newURL(StateHolder state, Constants.Clone type) Creates a new EngineURL object.
EngineURL	newURL(StateHolder state, URLContext allowedContext, Constants.Clone type) Creates a new EngineURL object.
EngineURL	newURL(URLContext allowedContext, Constants.Clone type) Creates a new EngineURL object.

Methods inherited from interface com.ibm.portal.Disposable

dispose

Method Detail

newResourceURL

DisposableURL newResourceURL(java.lang.String name,
                             PortalResources.Type type)
                             throws ResourceNotFoundException,
                                    InvalidResourceTypeException,
                                    ResourceUrlException

Creates a DisposableURL object that points to a generic resource. The resource is identified by its filename and resource type.
The resouce lookup takes additional information of the request into account (if available). This is the current locale, the client device, markup chosen for the client, and the theme name.
This method is a convenience method for newResourceURL called with state PortalResources.NO_STATE.

Parameters:

name - File name (without path) of the resource. Must not be null.

type - Portal resource type. Must not be null.

Returns:

A DisposableURL object that can be serialized to a stream. Not null.

Throws:

ResourceNotFoundException - If the resource cannot be located.

InvalidResourceTypeException - If the resource type is unknown.

ResourceUrlException - If the resource URL cannot be created.

newResourceURL

DisposableURL newResourceURL(java.lang.String name,
                             PortalResources.Type type,
                             PortalResources.State state)
                             throws ResourceNotFoundException,
                                    InvalidResourceTypeException,
                                    ResourceUrlException

Creates a DisposableURL object that points to a generic resource. The resource is identified by its filename and resource type. It can also contain resource state that is used to further distinguish the lookup of the resource.
The resource lookup takes additional information of the request into account (if available). This is the current locale, the client device, markup chosen for the client, and the theme name.

Parameters:

name - Name (without path) of the resource. Must not be null.

type - Portal resource type. Must not be null.

state - Additional resource state. Must not be null.

Returns:

A DisposableURL object that can be serialized to a stream. Not null.

Throws:

ResourceNotFoundException - If the resource cannot be located.

InvalidResourceTypeException - If the resource type is unknown.

ResourceUrlException - If the resource URL cannot be created.

newResourceURL

DisposableURL newResourceURL(java.lang.String name,
                             Theme theme,
                             PortalResources.Type type)
                             throws ResourceNotFoundException,
                                    InvalidResourceTypeException,
                                    ResourceUrlException,
                                    ModelException

Creates a DisposableURL object that points to a generic resource. The resource is identified by its filename and resource type.
The resouce lookup takes additional information of the request into account (if available). This is the current locale, the client device, markup chosen for the client, and the theme name.
This method is a convenience method for newResourceURL called with state PortalResources.NO_STATE.

Parameters:

name - The relative path of the resource. Must not be null.

theme - the theme object, may be null

type - Portal resource type. Must not be null.

Returns:

A DisposableURL object that can be serialized to a stream. Not null.

Throws:

ResourceNotFoundException - If the resource cannot be located.

InvalidResourceTypeException - If the resource type is unknown.

ResourceUrlException - If the resource URL cannot be created.

ModelException

Since:

6.1.0

newResourceURL

DisposableURL newResourceURL(java.lang.String name,
                             Theme theme,
                             PortalResources.Type type,
                             PortalResources.State state)
                             throws ResourceNotFoundException,
                                    InvalidResourceTypeException,
                                    ResourceUrlException,
                                    ModelException

Creates a DisposableURL object that points to a generic resource. The resource is identified by its filename and resource type. It can also contain resource state that is used to further distinguish the lookup of the resource.
The resource lookup takes additional information of the request into account (if available). This is the current locale, the client device, markup chosen for the client, and the theme name.

Parameters:

allowedContext - Specifies what type of URL may be generated. May be null to indicate that the server's default URL context should be used.

name - Name (without path) of the resource. Must not be null.

theme - the theme

type - Portal resource type. Must not be null.

state - Additional resource state. Must not be null.

Returns:

A DisposableURL object that can be serialized to a stream. Not null.

Throws:

ResourceNotFoundException - If the resource cannot be located.

InvalidResourceTypeException - If the resource type is unknown.

ResourceUrlException - If the resource URL cannot be created.

ModelException

Since:

6.1.0

newURL

EngineURL newURL(Constants.Clone type)
                 throws CannotCloneDocumentModelException,
                        CannotCreateDocumentException,
                        InvalidConstantException,
                        StateNotInRequestException

Creates a new EngineURL object.
If the factory has access to the current servlet request the created URL will be based on request-specific server information (e.g. hostname, port, path information etc.) including the request-specific state holder which is cloned according to the passed type argument specifying the clone operation. If no request is available, the factory will base the URL on static server information as well as on a new state holder which is initially empty. Note that in the latter case the passed type parameter specifiying the clone operation does not take any effect.

Parameters:

type - Type of the clone operation to get a copy of the state holder for the URL, may be null in which case a SMART_COPY will be generated.

Returns:

The created EngineURL object. Not null.

Throws:

CannotCloneDocumentModelException - If the state holder cannot be cloned.

CannotCreateDocumentException - If a wrapper around the state cannot be created.

InvalidConstantException - If the given clone type is not supported.

StateNotInRequestException - If the request-specific state holder is not available. Note that the factory implementation must not throw this exception in case that it holds no reference to the request at all.

newURL

EngineURL newURL(StateHolder state,
                 Constants.Clone type)
                 throws CannotCloneDocumentModelException,
                        CannotCreateDocumentException,
                        InvalidConstantException

Creates a new EngineURL object.
If the factory has access to the current servlet request the created URL will be based on request-specific server information (e.g. hostname, port, path information etc.). The created URL will operate on a clone of the given StateHolder. The clone operation to use is specified by the the given type argument. If no request is available, the factory will base the URL on static server information.

Parameters:

state - The original StateHolder the URL should be based on. May be null.

type - Type of the clone operation to get a copy of the given StateHolder. May be null in which case a SMART_COPY will be generated.

Returns:

A new EngineURL object. Not null.

Throws:

CannotCloneDocumentModelException - If the given state holder cannot be cloned.

CannotCreateDocumentException - If a wrapper around the state holder cannot be created.

InvalidConstantException - If the given clone type is not supported.

newURL

EngineURL newURL(StateHolder state,
                 URLContext allowedContext,
                 Constants.Clone type)
                 throws CannotCloneDocumentModelException,
                        CannotCreateDocumentException,
                        InvalidConstantException

Creates a new EngineURL object.
If the factory has access to the current servlet request the created URL will be based on request-specific server information (e.g. hostname, port, path information etc.). The created URL will operate on a clone of the given StateHolder. The clone operation to use is specified by the the given type argument. If no request is available, the factory will base the URL on static server information.
The allowedContext argument refers to the type of the URL to be generated i.e. it specifies whether the created URL may be absolute, server-relative or relative. Note that this argument cannot enforce that the URL is server-relative or relative. For example in case of a protocol switch (e.g. http to https), the URL must be absolute in any case.

Parameters:

state - The original StateHolder the URL should be based on. May be null.

allowedContext - Specifies what type of URL may be generated. May be null to indicate that the server's default URL context should be used.

type - Type of the clone operation to get a copy of the given StateHolder. May be null in which case a SMART_COPY will be generated.

Returns:

A new EngineURL object. Not null.

Throws:

CannotCloneDocumentModelException - If the given state cannot be cloned.

CannotCreateDocumentException - If a wrapper around the state cannot be created.

InvalidConstantException - If the given clone type is not supported.

newURL

EngineURL newURL(URLContext allowedContext,
                 Constants.Clone type)
                 throws CannotCloneDocumentModelException,
                        CannotCreateDocumentException,
                        InvalidConstantException,
                        StateNotInRequestException

Creates a new EngineURL object.
If the factory has access to the current servlet request the created URL will be based on request-specific server information (e.g. hostname, port, path information etc.) including the request-specific state holder which is cloned according to the passed type argument specifying the clone operation. If no request is available, the factory will base the URL on static server information as well as on a new state holder which is initially empty. Note that in the latter case the passed type parameter specifiying the clone operation does not take any effect.
The allowedContext argument refers to the type of the URL to be generated i.e. it specifies whether the created URL may be absolute, server-relative or relative. Note that this argument cannot enforce that the URL is server-relative or relative. For example in case of a protocol switch (e.g. http to https), the URL must be absolute in any case.

Parameters:

allowedContext - Specifies what type of URL may be generated. May be null to indicate that the server's default URL context should be used.

type - Type of the clone operation to get a copy of the state holder for the URL, may be null in which case a SMART_COPY will be generated.

Returns:

The created EngineURL object. Not null.

Throws:

CannotCloneDocumentModelException - If the state holder cannot be cloned.

CannotCreateDocumentException - If a wrapper around the state cannot be created.

InvalidConstantException - If the given clone type is not supported.

StateNotInRequestException - If the request-specific state holder is not available. Note that the factory implementation must not throw this exception in case that it holds no reference to the request at all.

getServerContext

ServerContext getServerContext()

Returns information about the URL configuration in the scope of the current request.

Specified by:

getServerContext in interface ServerContextProvider

Returns:

the server context of the request, not null

Since:

7.0