Overview | Package | Class | Tree | Deprecated | Index | Help
| The PDK Java API is part of the Portal Developer Kit on Portal Studio
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  InitializableXMLObject, Validateable

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.

Inner Class Summary
`static class` | `WebServiceRenderer.ConstParam` Class representing a parameter bound to a constant value
`static class` | `WebServiceRenderer.DefaultableParameterBinding` Superclass for `ParameterBinding`s 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 `ParameterBinding`s 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.
  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 `ParameterBinding`s 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 `ParameterBinding`s 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 `to render the edit mode.`
  3. Call {@link #renderEditDefaults to render the edit mode.
  4. Call `renderLink(oracle.portal.provider.v2.render.PortletRenderRequest)` to render the link mode.
  Overrides:
    `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.URLParam`s).
  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.
  Overrides:
    `validate` in class `BaseManagedRenderer`
  Parameters:
    `context` - The context of the calling instance.
    `errors` - The current list of errors.

Overview | Package | Class | Tree | Deprecated | Index | Help
| The PDK Java API is part of the Portal Developer Kit on Portal Studio
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2002, Oracle Corporation. All Rights Reserved.