oracle.portal.provider.v2.webservice
Class WebServiceRenderer

java.lang.Object
  oracle.portal.provider.v2.render.ManagedRenderer
      oracle.portal.provider.v2.render.http.BaseManagedRenderer
          oracle.portal.provider.v2.webservice.WebServiceRenderer

All Implemented Interfaces:

Validateable, InitializableXMLObject

Direct Known Subclasses:

DocWebServiceRenderer, RPCWebServiceRenderer

public abstract class WebServiceRenderer
extends BaseManagedRenderer

WebServiceRenderer is the base class for web service enabled renderers. A WebServiceRenderer is responsible for invoking a web service and presenting its results as a portlet. Parameters in the request to the web service can be bound to any of the following sources:

• Arbitrary constants (see WebServiceRenderer.ConstParam)
• Portlet render request parameters (see WebServiceRenderer.RequestParam)
• Parameters from the URL query string sent to the portlet (see WebServiceRenderer.URLParam)
• Provider session attributes (see WebServiceRenderer.SessionAttrib)
• Items of customization data from a NameValuePersonalizationObject (see WebServiceRenderer.EditData)

Parameter bindings are controlled by the literal property, when the request to the web service is a literal XML structure, or through properties in a subclass (e.g. the param property on RPCWebServiceRenderer).

The transformation from web service response to portlet response is controlled by an XSL stylesheet, named by the responseXSL property. Although, this file must be specified, it need not exist, since a default stylesheet is generated based on the parameter bindings if one does not exist.

A WebServiceRenderer supports an XML logging feature, where XML documents corresponding to various stages in the renderering process are dumped to the filesystem to help debugging. The feature is controlled by the logging boolean property. When activated, one or more XML documents are dumped to the directory named by the loggingDirectory property if it is set, or the provider 'repository path' otherwise (usually the same directory as the XML provider definition). Each document has a filename that has the portlet instance name as a prefix, and one of the following suffixes

• _literal.xml: A dump of the instantiated literal XML structure which was sent to the web service. This is only written when the web service arguments are defined with the literal property.
• _request.xml: A snapshot of the combined response document before the web service was invoked. This helps when validating that all the correct arguments are being passed.
• _response.xml: A snapshot of the combined response document after the web service has been invoked and its response has been added. This is the XML document to which the stylesheet is applied. If this document is missing, it probably means that an exception occurred when calling the web service. You should check application.log to find a log of all the exceptions that occurred.

The main entry point is the renderBody(oracle.portal.provider.v2.render.PortletRenderRequest) method.

Nested Class Summary

static class	WebServiceRenderer.ConstParam Class representing a parameter bound to a constant value
static class	WebServiceRenderer.DefaultableParameterBinding Superclass for ParameterBindings that can have a default value.
static class	WebServiceRenderer.EditData Class representing a parameter bound to an item of customization data from a NameValuePersonalizationObject.
static class	WebServiceRenderer.ParameterBinding Base class for objects representing a parameter in the request to the web service to that can be 'bound' to a variety of sources.
static class	WebServiceRenderer.PromptedBinding Base class for objects representing a prompt in the request to the web service to that is used show prompt in edit mode.
static class	WebServiceRenderer.RequestParam Class representing a parameter bound to an item of data in the current WebServiceRenderRequest.
static class	WebServiceRenderer.SessionAttrib Class representing a parameter bound to an item of session data in the ProviderSession.
static class	WebServiceRenderer.URLParam Class representing a parameter bound to the value of a parmeter in the query string of the request to the provider.

Constructor Summary

WebServiceRenderer()

Method Summary

void	addLiteral(java.lang.Object literal) Defines the literal XML structure that should be sent in the request to the web service.
WebServiceRenderer.ParameterBinding[]	getBindings() Gets an array of all the ParameterBindings declared for the request to the web service.
boolean	getEscapeOutput() Determines whether control characters in the response from the web service (such as '<' and '&') are to be escaped in the portlet response so that they display in HTML.
LiteralXML	getLiteral() Gets an object representing the literal XML structure that should be sent in the request to the web service (if applicable).
boolean	getLogging() Determines whether the XML logging debug feature is activated (see class doc for more information).
java.lang.String	getLoggingDirectory(WebServiceRenderRequest wrr) Gets the directory where files are created by the XML logging debug feature.
abstract void	invokeService(WebServiceRenderRequest wrr, org.w3c.dom.Element docEl) Determines the values of parameter bindings using the given WebServiceRenderRequest, invokes the web service, and adds an XML representation of its response to the response XML document.
void	postInitialize() Performs the extra steps required to initialize and validate a WebServiceRenderer once its properties have been set with the appropriate accessor methods.
void	renderBody(PortletRenderRequest pr) The main rendering method, responsible for calling the respective mode depending on PortletRenderRequest mode.
void	renderEdit(PortletRenderRequest pr) This method is responsible for displaying a screen that allows customization of the portlet title and parameters bound to edit data.
void	renderEditDefaults(PortletRenderRequest pr) This method is responsible for displaying a screen that allows default (system) customization of the portlet title and parameters to edit data.
void	renderLink(PortletRenderRequest pr) This method is responsible for displaying the portlet in link mode.
void	renderShow(PortletRenderRequest pr) The show mode method, responsible for calling a web service and presenting its results as a portlet.
void	setEscapeOutput(java.lang.String escapeOutput) Controls whether control characters in the response from the web service (such as '<' and '&') are escaped in the portlet response so that they display in HTML.
void	setLogging(java.lang.String logging) Controls whether the XML logging debug feature is activated (see class doc for more information).
void	setLoggingDirectory(java.lang.String loggingDirectory) Sets the directory where files are created by the XML logging debug feature.
void	setResponseXSL(java.lang.String responseXSL) Sets the filename of the XSL stylesheet used to transform the XML result document into a portlet response.
void	validate(java.lang.String context, ValidationError errors) Validates the internal state of this WebServiceRenderer instance.

Methods inherited from class oracle.portal.provider.v2.render.http.BaseManagedRenderer

addParameter, getContentType, getGeneratesESI, preInitialize, prepareResponse, setContentType, setGeneratesESI, setGeneratesESI, setPageExpires, setPageExpires, setUseInvalidationCaching, setUseInvalidationCaching

Methods inherited from class java.lang.Object

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

Constructor Detail

WebServiceRenderer

public WebServiceRenderer()

Method Detail

postInitialize

public void postInitialize()
                    throws NodeHandlerException

Performs the extra steps required to initialize and validate a WebServiceRenderer once its properties have been set with the appropriate accessor methods.

Specified by:

postInitialize in interface InitializableXMLObject

Overrides:

postInitialize in class BaseManagedRenderer

Throws:

NodeHandlerException - if not all properties have been set correctly

setLogging

public final void setLogging(java.lang.String logging)

Controls whether the XML logging debug feature is activated (see class doc for more information). By default the feature is inactive.

Parameters:

logging - String representation of boolean value. Should be "true" if the feature should be activated, "false" otherwise.

getLogging

public final boolean getLogging()

Determines whether the XML logging debug feature is activated (see class doc for more information).

Returns:

true if the feature is active, false otherwise.

setLoggingDirectory

public final void setLoggingDirectory(java.lang.String loggingDirectory)
                               throws PortletException

Sets the directory where files are created by the XML logging debug feature. If this directory is not set explicitly, the provider 'repository path' (usually the same directory as the XML provider definition) is used.

Parameters:

loggingDirectory - the name of directory where files are created by the XML logging debug feature

Throws:

PortletException - if a directory with the given name does not exist

getLoggingDirectory

public java.lang.String getLoggingDirectory(WebServiceRenderRequest wrr)

Gets the directory where files are created by the XML logging debug feature. If this directory has not been set explicitly with setLoggingDirectory(java.lang.String), the provider 'repository path' (usually the same directory as the XML provider definition) is returned.

Parameters:

wrr - an object exposing the relevant properties of the current render request

Returns:

the directory where files are created by the XML logging debug feature

setEscapeOutput

public final void setEscapeOutput(java.lang.String escapeOutput)

Controls whether control characters in the response from the web service (such as '<' and '&') are escaped in the portlet response so that they display in HTML. By default, control characters are escaped. Escaping should be disabled, e.g. if the web service returns a string containing HTML tags, which should be copied to the portlet response verbatim.

Parameters:

escapeOutput - String representation of boolean value. Should be "true" if control character escaping is to be enabled, "false" otherwise.

getEscapeOutput

public final boolean getEscapeOutput()

Determines whether control characters in the response from the web service (such as '<' and '&') are to be escaped in the portlet response so that they display in HTML.

Returns:

true if control character escaping is enabled, false otherwise.

setResponseXSL

public void setResponseXSL(java.lang.String responseXSL)

Sets the filename of the XSL stylesheet used to transform the XML result document into a portlet response. The file is assumed to be stored in the provider 'repository' directory (usually the same directory as the XML provider definition).

Parameters:

responseXSL - filename of the XSL stylesheet used to transform the XML result document into a portlet reponse

addLiteral

public void addLiteral(java.lang.Object literal)
                throws PortletException

Defines the literal XML structure that should be sent in the request to the web service.

Parameters:

literal - object representing the literal XML structure that should be sent in the request to the web service. Should be an instance of LiteralXML.

Throws:

PortletException - if the given object is not a valid LiteralXML

getLiteral

public LiteralXML getLiteral()

Gets an object representing the literal XML structure that should be sent in the request to the web service (if applicable).

Returns:

object representing the literal XML structure that should be sent in the request to the web service or null if not applicable.

invokeService

public abstract void invokeService(WebServiceRenderRequest wrr,
                                   org.w3c.dom.Element docEl)
                            throws PortletException

Determines the values of parameter bindings using the given WebServiceRenderRequest, invokes the web service, and adds an XML representation of its response to the response XML document. Subclasses should implement.

Parameters:

wrr - an object exposing the relevant properties of the current render request

docEl - the document element of the XML document to which an XML representation of the response should be added

Throws:

PortletException - if an error occurs.

getBindings

public final WebServiceRenderer.ParameterBinding[] getBindings()

Gets an array of all the ParameterBindings declared for the request to the web service. These are set up either indirectly through addLiteral(java.lang.Object) or directly through a subclass method.

Returns:

an array of all the ParameterBindings declared for the request to the web service

renderBody

public void renderBody(PortletRenderRequest pr)
                throws PortletException

The main rendering method, responsible for calling the respective mode depending on PortletRenderRequest mode. The method proceeds as follows:

1. Call renderShow(oracle.portal.provider.v2.render.PortletRenderRequest) to render the show mode.
2. Call renderEdit(oracle.portal.provider.v2.render.PortletRenderRequest) to render the edit mode.
3. Call renderEditDefaults(oracle.portal.provider.v2.render.PortletRenderRequest) to render the edit mode.
4. Call renderLink(oracle.portal.provider.v2.render.PortletRenderRequest) to render the link mode.

Specified by:

renderBody in class ManagedRenderer

Parameters:

pr - a PortletRenderRequest

Throws:

PortletException - if an error occurs while renderering

renderShow

public void renderShow(PortletRenderRequest pr)
                throws PortletException

The show mode method, responsible for calling a web service and presenting its results as a portlet. The method proceeds as follows:

1. Construct a WebServiceRenderRequest from the given PortletRenderRequest.
2. 'Serialize' it to the output XML document.
3. Call invokeService(oracle.portal.provider.v2.webservice.WebServiceRenderRequest, org.w3c.dom.Element) to send the request to the web service and add the response to the output XML document.
4. If the XSL file specified in responseXSL does not yet exist, generate a default one (that includes HTML form input fields for all declared WebServiceRenderer.URLParams).
5. Parse the XSL if it has been updated since it was last read.
6. Apply the XSL transformation to the XML document to produce portlet HTML.

Parameters:

pr - a PortletRenderRequest

Throws:

PortletException - if an error occurs while renderering

renderEdit

public void renderEdit(PortletRenderRequest pr)
                throws PortletException

This method is responsible for displaying a screen that allows customization of the portlet title and parameters bound to edit data.

Parameters:

pr - a PortletRenderRequest

Throws:

PortletException - if an error occurs while renderering

renderLink

public void renderLink(PortletRenderRequest pr)
                throws PortletException

This method is responsible for displaying the portlet in link mode.

Parameters:

pr - a PortletRenderRequest

Throws:

PortletException - if an error occurs while renderering

renderEditDefaults

public void renderEditDefaults(PortletRenderRequest pr)
                        throws PortletException

This method is responsible for displaying a screen that allows default (system) customization of the portlet title and parameters to edit data.

Parameters:

pr - a PortletRenderRequest

Throws:

PortletException - if an error occurs while renderering

validate

public void validate(java.lang.String context,
                     ValidationError errors)

Validates the internal state of this WebServiceRenderer instance. Errors found are reported using the supplied ValidationError instance.

Specified by:

validate in interface Validateable

Overrides:

validate in class BaseManagedRenderer

Parameters:

context - The context of the calling instance.

errors - The current list of errors.