com.ibm.portal.resolver.accessors.url
Interface PocURLFactory

All Superinterfaces:

PocServerContextProvider, ServerContextProvider

All Known Subinterfaces:

DisposablePocURLFactory

public interface PocURLFactory
extends PocServerContextProvider

Factory to create POC URLs. Depending on the factory method, the URL will directly point to the portal servlet, if it represents a view that keeps the navigational state of the current interaction with portal. Refer to the method documentation for more detail. The following pattern helps to classify the URL generation methods.

• methods that take a Constants.Clone parameter refer to portal URLs, because the Constants.Clone represents the way to keep or dismiss the current navigational state. The resulting URLs will always point to the portal servlet. Use these methods if you intend to produce URLs that integrate into the interaction flow with portal.
• methods that do not take a Constants.Clone will never keep navigational state and will point to the service endpoint of a POC URI, that is not neccessarily the portal servlet. Use these methods to create URLs to the binary representation of resources (download) or to generate URLs to initial, bookmarkable entry points to resources or resource views.
• The lateBinding parameter controls if the resolution of the final endpoint of the URL is done at URL generation time or later, when the resource is actually accessed. The most efficient way is to set this parameter to TRUE, which is also the default, if left empty. However late binding URLs might result in a redirect to be issued by the server when invoked and as a result they can only be used if the resources will be addressed via a GET request. If you need to POST data to an endpoint, use the early binding alternative.

Note that the PocURL objects that are returned by the factory methods need to be disposed if they are no longer used. Prefer the writeDispose method on the PocURL to stream and dispose the URLs in one single step.

Since:

6.0.1

Field Summary

static java.lang.Boolean	EARLY_BINDING Identifies early binding
static java.lang.Boolean	LATE_BINDING Identifies late binding
static java.lang.Boolean	RESOLUTION_BINDING Identifies the portal binding
static java.lang.Boolean	UNDEFINED_BINDING Identifies an undefined binding

Method Summary

PocServerContext	getServerContext() Returns information about the URL configuration in the scope of the current request.
ServerContext	getServerContext(java.lang.Boolean bLateBinding) Returns information about the URL configuration in the scope of the current request.
PocURL	newURL(java.lang.Boolean bLateBinding) Generates a URL that points to the POC servlet and that does not contain navigational state.
PocURL	newURL(Constants.Clone type, java.lang.Boolean bLateBinding) Generates a URL that points to the portal servlet and it based on the navigational state of the current request.
PocURL	newURL(DataSource ds) Constructs a URL that points to the POC servlet and that does not contain navigational state.
PocURL	newURL(StateHolder state, Constants.Clone type, java.lang.Boolean bLateBinding) Generates a URL that points to the portal servlet and it based on navigational state explicitly.
PocURL	newURL(StateHolder state, URLContext allowedContext, Constants.Clone type, java.lang.Boolean bLateBinding) Generates a URL that points to the portal servlet and it based on navigational state explicitly.
DisposableURL	newURL(java.lang.String aPublicID, java.lang.String aSystemID) Constructs a URL object that tries to resolve the public and system identifier via the entity resolver to a local representation of the resource.
PocURL	newURL(URLContext allowedContext, java.lang.Boolean bLateBinding) Generates a URL that points to the POC servlet and that does not contain navigational state.
PocURL	newURL(URLContext allowedContext, Constants.Clone type, java.lang.Boolean bLateBinding) Generates a URL that points to the portal servlet and it based on the navigational state of the current request.

Field Detail

EARLY_BINDING

static final java.lang.Boolean EARLY_BINDING

Identifies early binding

Since:

7.0

LATE_BINDING

static final java.lang.Boolean LATE_BINDING

Identifies late binding

Since:

7.0

RESOLUTION_BINDING

static final java.lang.Boolean RESOLUTION_BINDING

Identifies the portal binding

Since:

8.0

UNDEFINED_BINDING

static final java.lang.Boolean UNDEFINED_BINDING

Identifies an undefined binding

Since:

7.0

Method Detail

getServerContext

PocServerContext getServerContext()

Returns information about the URL configuration in the scope of the current request. The server context points to the poc servlet, i.e. to the late binding servlet of the POC framework.

Specified by:

getServerContext in interface PocServerContextProvider

Specified by:

getServerContext in interface ServerContextProvider

Returns:

the server context of the request, not null

Since:

6.1.0.3

getServerContext

ServerContext getServerContext(java.lang.Boolean bLateBinding)

Returns information about the URL configuration in the scope of the current request. The parameter identifies if the context is for late binding (LATE_BINDING) or for early binding ( EARLY_BINDING). If left RESOLUTION_BINDING the method returns the server context of the portal servlet.

Returns:

the server context of the request, not null

Since:

6.1.0.3

newURL

PocURL newURL(java.lang.Boolean bLateBinding)
              throws java.io.IOException

Generates a URL that points to the POC servlet and that does not contain navigational state.

Parameters:

bLateBinding - Specifies if the POC URL uses late binding or early binding to the actual resource. In case of early binding there will be a call to the LookupService before the URL is serialized. In case of late binding the call to the LookupService will be done when the URL is invoked. Note that in case you need to generate URLs that can be posted to, this parameter must be set to FALSE to void redirects. If left null the parameter defaults to TRUE.

Returns:

A new PocURL object. Not null.

Throws:

StateException - - if the URL could not be created

java.io.IOException

newURL

PocURL newURL(Constants.Clone type,
              java.lang.Boolean bLateBinding)
              throws StateException

Generates a URL that points to the portal servlet and it based on the navigational state of the current request.

Parameters:

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.

bLateBinding - Specifies if the POC URL uses late binding or early binding to the actual resource. In case of early binding there will be a call to the ResolutionService before the URL is serialized. In case of late binding the call to the ResolutionService will be done when the URL is invoked. Note that in case you need to generate URLs that can be posted to, this parameter must be set to FALSE to void redirects. If left null the parameter defaults to TRUE.

Returns:

A new PocURL object. Not null.

Throws:

StateException - - if the URL could not be created

newURL

PocURL newURL(DataSource ds)
              throws java.io.IOException,
                     java.net.URISyntaxException

Constructs a URL that points to the POC servlet and that does not contain navigational state. The resulting URL is an early binding URL, since the actual lookup to the data source has already been done.

The advantage of using this method over newURL(Boolean) and early binding is that the URI will not be resolved to perform the lookup for the data source. This lookup can be saved, because the data source is already available at URL generation time. This can in particular be a benefit, if the result of the data source lookup would require expensive computations that can be saved if the data source is only used for URL generation.

Parameters:

ds - the data source to create the URL to, must not be null and must provide a valid URI via its Addressable.getURI() method.

Returns:

the POC URI, not null

Throws:

java.io.IOException

java.net.URISyntaxException

Since:

7.0

newURL

PocURL newURL(StateHolder state,
              Constants.Clone type,
              java.lang.Boolean bLateBinding)
              throws StateException

Generates a URL that points to the portal servlet and it based on navigational state explicitly. Use this method with care, since it will not work for WSRP.

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.

bLateBinding - Specifies if the POC URL uses late binding or early binding to the actual resource. In case of early binding there will be a call to the ResolutionService before the URL is serialized. In case of late binding the call to the ResolutionService will be done when the URL is invoked. Note that in case you need to generate URLs that can be posted to, this parameter must be set to FALSE to void redirects. If left null the parameter defaults to TRUE.

Returns:

A new PocURL object. Not null.

Throws:

StateException - - if the URL could not be created

newURL

PocURL newURL(StateHolder state,
              URLContext allowedContext,
              Constants.Clone type,
              java.lang.Boolean bLateBinding)
              throws StateException

Generates a URL that points to the portal servlet and it based on navigational state explicitly. Use this method with care, since it will not work for WSRP.

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.

bLateBinding - Specifies if the POC URL uses late binding or early binding to the actual resource. In case of early binding there will be a call to the ResolutionService before the URL is serialized. In case of late binding the call to the ResolutionService will be done when the URL is invoked. Note that in case you need to generate URLs that can be posted to, this parameter must be set to FALSE to void redirects. If left null the parameter defaults to TRUE.

Returns:

A new PocURL object. Not null.

Throws:

StateException - - if the URL could not be created

newURL

DisposableURL newURL(java.lang.String aPublicID,
                     java.lang.String aSystemID)
                     throws java.io.IOException,
                            java.net.URISyntaxException

Constructs a URL object that tries to resolve the public and system identifier via the entity resolver to a local representation of the resource. If this is not possible, the system identifier is used. This method uses the standard entity resolver.

Parameters:

aPublicID - the publicID, may be null

aSystemID - the systemID, may be null

Returns:

the URL or null if none could be generated

Throws:

java.io.IOException

java.net.URISyntaxException

Since:

8.0

newURL

PocURL newURL(URLContext allowedContext,
              java.lang.Boolean bLateBinding)
              throws java.io.IOException

Generates a URL that points to the POC servlet and that does not contain navigational state.

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.

bLateBinding - Specifies if the POC URL uses late binding or early binding to the actual resource. In case of early binding there will be a call to the ResolutionService before the URL is serialized. In case of late binding the call to the ResolutionService will be done when the URL is invoked. Note that in case you need to generate URLs that can be posted to, this parameter must be set to FALSE to void redirects. If left null the parameter defaults to TRUE.

Returns:

A new PocURL object. Not null.

Throws:

StateException - - if the URL could not be created

java.io.IOException

newURL

PocURL newURL(URLContext allowedContext,
              Constants.Clone type,
              java.lang.Boolean bLateBinding)
              throws StateException

Generates a URL that points to the portal servlet and it based on the navigational state of the current request.

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 given StateHolder. May be null in which case a SMART_COPY will be generated.

bLateBinding - Specifies if the POC URL uses late binding or early binding to the actual resource. In case of early binding there will be a call to the ResolutionService before the URL is serialized. In case of late binding the call to the ResolutionService will be done when the URL is invoked. Note that in case you need to generate URLs that can be posted to, this parameter must be set to FALSE to void redirects. If left null the parameter defaults to TRUE.

Returns:

A new PocURL object. Not null.

Throws:

StateException - - if the URL could not be created