org.jasig.portal.channels
Class CAbstractXslt

java.lang.Object
  extended by org.jasig.portal.channels.CAbstractXslt
All Implemented Interfaces:
IChannel
Direct Known Subclasses:
CMissingProperties, CTimeTitle

public abstract class CAbstractXslt
extends java.lang.Object
implements IChannel

CAbstractXslt is an abstract IChannel which implements the boilerplate of applying a parameterized XSLT to an XML to render the channel output. Your IChannel can extend CAbstactXSLT and implement the template methods to provide the XML, XSLT, and parameters.

Since:
uPortal 2.5
Version:
$Revision$ $Date$

Field Summary
protected  org.apache.commons.logging.Log log
          Commons Logging logger for the runtime class of this channel instance.
private  ChannelRuntimeData runtimeData
          The most recently set ChannelRuntimeData.
private  ChannelStaticData staticData
          The ChannelStaticData.
 
Constructor Summary
CAbstractXslt()
           
 
Method Summary
protected  ChannelRuntimeData getRuntimeData()
           
 ChannelRuntimeProperties getRuntimeProperties()
          Acquires ChannelRuntimeProperties from the channel.
protected  ChannelStaticData getStaticData()
           
protected abstract  java.util.Map getStylesheetParams()
          Get a Map from parameter names to parameter values for parameters to be passed to the XSLT.
protected abstract  org.w3c.dom.Document getXml()
          Get the Document we should feed to our XSLT.
protected abstract  java.lang.String getXsltUri()
          Get the URI whereat we can obtain the XSLT we should use to render.
 void renderXML(org.xml.sax.ContentHandler out)
          Ask channel to render its content.
 void setRuntimeData(ChannelRuntimeData rd)
          Passes ChannelRuntimeData to the channel.
 void setStaticData(ChannelStaticData sd)
          Passes ChannelStaticData to the channel.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.jasig.portal.IChannel
receiveEvent
 

Field Detail

runtimeData

private ChannelRuntimeData runtimeData
The most recently set ChannelRuntimeData. This data is available to our subclasses via an accessor method.


staticData

private ChannelStaticData staticData
The ChannelStaticData. This data is available to our subclasses via an accessor method.


log

protected org.apache.commons.logging.Log log
Commons Logging logger for the runtime class of this channel instance.

Constructor Detail

CAbstractXslt

public CAbstractXslt()
Method Detail

setRuntimeData

public final void setRuntimeData(ChannelRuntimeData rd)
Description copied from interface: IChannel
Passes ChannelRuntimeData to the channel. This function is called prior to the renderXML() call.

Specified by:
setRuntimeData in interface IChannel
Parameters:
rd - channel runtime data
See Also:
ChannelRuntimeData

getRuntimeData

protected final ChannelRuntimeData getRuntimeData()

setStaticData

public final void setStaticData(ChannelStaticData sd)
Description copied from interface: IChannel
Passes ChannelStaticData to the channel. This is done during channel instantiation time. see org.jasig.portal.ChannelStaticData

Specified by:
setStaticData in interface IChannel
Parameters:
sd - channel static data
See Also:
ChannelStaticData

getStaticData

protected final ChannelStaticData getStaticData()

getRuntimeProperties

public ChannelRuntimeProperties getRuntimeProperties()
Description copied from interface: IChannel
Acquires ChannelRuntimeProperties from the channel. This function may be called by the portal framework throughout the session. Currently, as of uPortal 2.5.1, the framework calls this method after each invocation of renderXML (to determine if there is a dynamic channel title). Prior to uPortal 2.5.1, the framework would not call this method.

Specified by:
getRuntimeProperties in interface IChannel
See Also:
ChannelRuntimeProperties

renderXML

public final void renderXML(org.xml.sax.ContentHandler out)
                     throws PortalException
Description copied from interface: IChannel
Ask channel to render its content.

Specified by:
renderXML in interface IChannel
Parameters:
out - the SAX ContentHandler to output content to
Throws:
PortalException

getXml

protected abstract org.w3c.dom.Document getXml()
                                        throws java.lang.Exception
Get the Document we should feed to our XSLT. This method is declared to throw Exception for maximum convenience of the developer extending this class. Such developers should catch or declare exceptions as appropriate to your needs. Just because you can throw Exception here doesn't mean you shouldn't, for example, fallback to a default XSLT URL when your cannot programmatically determine the URL of your XSLT. On the other hand, there's no reason for you to wrap SqlExceptions if you're not going to do anything other than what this abstract class does with them (logs them and wraps them in PortalExceptions). The method invoking this template method, renderXML(), is declared to throw PortalException by the IChannel API. Any PortalException or RuntimeException thrown by getXsltUri() will be thrown all the way out of the abstract class's renderXML() method. This approach ensures that developers extending this class retain control over what exceptions their implementions throw. Note that you can map particular exceptions to particular XML representations and thus particular CError displays as of uPortal 2.5. Exceptions that are neither RuntimeExceptions nor PortalExceptions thrown by this method will be logged and wrapped in PortalExceptions so that this channel will conform to the IChannel API. Implementations of this method should not return null. When this method returns null, renderXML() throws an IllegalStateException.

Returns:
the Document we should feed to our XSLT.
Throws:
java.lang.Exception - including PortalException or any RuntimeException on failure

getXsltUri

protected abstract java.lang.String getXsltUri()
                                        throws java.lang.Exception
Get the URI whereat we can obtain the XSLT we should use to render. This method is declared to throw Exception for maximum convenience of the developer extending this class. Such developers should catch or declare exceptions as appropriate to your needs. Just because you can throw Exception here doesn't mean you shouldn't, for example, fallback to a default XSLT URL when your cannot programmatically determine the URL of your XSLT. On the other hand, there's no reason for you to wrap SqlExceptions if you're not going to do anything other than what this abstract class does with them (logs them and wraps them in PortalExceptions). The method invoking this template method, renderXML(), is declared to throw PortalException by the IChannel API. Any PortalException or RuntimeException thrown by getXsltUri() will be thrown all the way out of the abstract class's renderXML() method. This approach ensures that developers extending this class retain control over what exceptions their implementions throw. Note that you can map particular exceptions to particular XML representations and thus particular CError displays as of uPortal 2.5. Exceptions that are neither RuntimeExceptions nor PortalExceptions thrown by this method will be logged and wrapped in PortalExceptions so that this channel will conform to the IChannel API. Implementations of this method should not return null. The behavior of this class when this method returns null is currently undefined. The current implementation is to throw IllegalStateException. However, it might be an interesting improvement to make the meaning of returning null here be to perform no transformation and just dump the XML to the ContentHandler.

Returns:
URI of the XSLT to use to render the channel
Throws:
java.lang.Exception - including PortalException or any RuntimeException on failure

getStylesheetParams

protected abstract java.util.Map getStylesheetParams()
                                              throws java.lang.Exception
Get a Map from parameter names to parameter values for parameters to be passed to the XSLT. Returning null is equivalent to returning an empty map and will not be considered an error condition by the renderXML() implementation. This method is declared to throw Exception for maximum convenience of the developer extending this class. Such developers should catch or declare exceptions as appropriate to your needs. Just because you can throw Exception here doesn't mean you shouldn't, for example, fallback to default XSLT parameters when you cannot programmatically determine some or all of your XSLT parameters. Or, if you have a very channel-specific UI you want to render on failure, you might pass parameters to your XSLT characterizing the failure and let your XSLT render the response. There's likely no reason for you to wrap IOExceptions if you're not going to do anything other than what this abstract class does with them (logs them and wraps them in PortalExceptions). The method invoking this template method, renderXML(), is declared to throw PortalException by the IChannel API. Any PortalException or RuntimeException thrown by getStylesheetParams() will be thrown all the way out of the abstract class's renderXML() method. This approach ensures that developers extending this class retain control over what exceptions their implementions throw. Note that you can map particular exceptions to particular XML representations and thus particular CError displays as of uPortal 2.5. Exceptions that are neither RuntimeExceptions nor PortalExceptions thrown by this method will be logged and wrapped in PortalExceptions so that this channel will conform to the IChannel API.

Returns:
a Map from parameter names to parameter values, or null (equivalent to empty Map).
Throws:
java.lang.Exception - including PortalException or any RuntimeException on failure.