org.wpi.gdc.cms.main
Class DataSource

java.lang.Object
  |
  +--org.wpi.gdc.cms.main.DataSource

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler

Direct Known Subclasses:

DataSourcePassthrough

public abstract class DataSource

extends java.lang.Object

implements org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler

A DataSource takes SAX events and based on them passes new SAX events onto the XMLConsumer object.

There are a few helper functions in this class that make writing a DataSource much easier:

• sendString(java.lang.String) - converts a String in a SAX characters event
• sendDatabaseException(org.wpi.gdc.cms.db.DatabaseException) - sends a bunch of SAX events to report a DatabaseException
• sendException(java.lang.Throwable) - sends a bunch of SAX events to report an Exception

Version:

1.6

Author:

dmpotter

Field Summary

protected org.xml.sax.Locator	locator The document locator as set via the default setDocumentLocator method.
protected javax.servlet.http.HttpServletRequest	request The HTTP Request which eventually resulted in the usage of this DataSource.
protected javax.servlet.http.HttpServletResponse	response The HTTP Response which uses this DataSource.
protected Session	session The session associated with the caller for this data source.
protected User	user The User object which is logged in for this request.
protected org.apache.cocoon.xml.XMLConsumer	xmlConsumer This is the consumer as set via the standard interface.

Constructor Summary

DataSource()

Method Summary

void	characters(char[] c, int start, int len) A SAX event; this implementation does nothing.
void	comment(char[] ch, int start, int len) A SAX event; this implementation does nothing.
void	endCDATA() A SAX event; this implementation does nothing.
abstract void	endDataSource() Signals that this DataSource has just been left.
void	endDocument() A SAX event; this implementation does nothing.
void	endDTD() A SAX event; this implementation does nothing.
void	endElement(java.lang.String uri, java.lang.String loc, java.lang.String raw) A SAX event; this implementation does nothing.
void	endEntity(java.lang.String name) A SAX event; this implementation does nothing.
void	endPrefixMapping(java.lang.String prefix) This event should never be passed to the consumer via a DataSource, the engine takes care of passing the event.
void	ignorableWhitespace(char[] c, int start, int len) A SAX event; this implementation does nothing.
void	processingInstruction(java.lang.String target, java.lang.String data) A SAX event; this implementation does nothing.
protected void	sendDatabaseException(DatabaseException de) Standard method for creating writing out a DatabaseException that occured while processing a DataSource.
protected void	sendException(java.lang.Throwable exception) Standard method for creating writing out an Exception that occured while processing a DataSource.
protected void	sendString(java.lang.String string) Creates a SAX characters corresponding to the given string.
static void	sendString(org.apache.cocoon.xml.XMLConsumer xmlConsumer, java.lang.String string) Creates a SAX characters corresponding to the given string.
void	setDocumentLocator(org.xml.sax.Locator locator) Passes the Locator onto this datasource - this should NOT be passed onto the consumer as it already will have been.
void	setupDataSource(org.apache.cocoon.xml.XMLConsumer consumer, Session session, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, User user) Sets up the DataSource, this is called before any other method via the CMS engine.
void	skippedEntity(java.lang.String name) A SAX event; this implementation does nothing.
void	startCDATA() A SAX event; this implementation does nothing.
abstract void	startDataSource() Signals that this DataSource has just been activated.
void	startDocument() A SAX event; this implementation does nothing.
void	startDTD(java.lang.String name, java.lang.String publicId, java.lang.String systemId) A SAX event; this implementation does nothing.
void	startElement(java.lang.String uri, java.lang.String loc, java.lang.String raw, org.xml.sax.Attributes a) A SAX event; this implementation does nothing.
void	startEntity(java.lang.String name) A SAX event; this implementation does nothing.
void	startPrefixMapping(java.lang.String prefix, java.lang.String uri) This event should never be passed to the consumer via a DataSource, the engine takes care of passing the event.

Methods inherited from class java.lang.Object

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

Field Detail

session

protected Session session

The session associated with the caller for this data source.

xmlConsumer

protected org.apache.cocoon.xml.XMLConsumer xmlConsumer

This is the consumer as set via the standard interface.

locator

protected org.xml.sax.Locator locator

The document locator as set via the default setDocumentLocator method.

See Also:

setDocumentLocator(org.xml.sax.Locator)

request

protected javax.servlet.http.HttpServletRequest request

The HTTP Request which eventually resulted in the usage of this DataSource.

response

protected javax.servlet.http.HttpServletResponse response

The HTTP Response which uses this DataSource.

user

protected User user

The User object which is logged in for this request. This will be set to null if there is no logged in user.

Constructor Detail

DataSource

public DataSource()

Method Detail

setupDataSource

public void setupDataSource(org.apache.cocoon.xml.XMLConsumer consumer,
                            Session session,
                            javax.servlet.http.HttpServletRequest request,
                            javax.servlet.http.HttpServletResponse response,
                            User user)

Sets up the DataSource, this is called before any other method via the CMS engine.

The default version sets the various protected fields with the values passed. Generally speaking there really is no other use for this method, but you can use it to do any processing that needs to be done before startDataSource() is called.

Parameters:

consumer - The XML consumer for this DataSource.

session - The CMS session for this DataSource.

request - The HTTP request for that resulted in the usage of the DataSource.

response - The HTTP reponse that will be returned to the client.

user - The logged in User, or null if there is no logged in user.

See Also:

xmlConsumer, session, request, response, user

startDataSource

public abstract void startDataSource()
                              throws org.xml.sax.SAXException

Signals that this DataSource has just been activated. At this point, any variables should be reinitialized as the same DataSource object may be reused for multiple sessions. This event will be followed with the startElement() SAX event containing the event that triggered this event.

endDataSource

public abstract void endDataSource()
                            throws org.xml.sax.SAXException

Signals that this DataSource has just been left. This event will follow the SAX event that terminated this DataSource.

sendString

protected void sendString(java.lang.String string)
                   throws org.xml.sax.SAXException

Creates a SAX characters corresponding to the given string.

If the given String is null this method does nothing.

Parameters:

string - the string to create a characters event for

Throws:

org.xml.sax.SAXException - Any SAX event can cause a SAXException; this method does not directly cause one, but events in the pipeline might.

sendString

public static void sendString(org.apache.cocoon.xml.XMLConsumer xmlConsumer,
                              java.lang.String string)
                       throws org.xml.sax.SAXException

Creates a SAX characters corresponding to the given string.

If the given String is null this method does nothing.

Parameters:

xmlConsumer - the XMLConsumer to receive the SAX event

string - the string to create a characters event for

Throws:

org.xml.sax.SAXException - Any SAX event can cause a SAXException; this method does not directly cause one, but events in the pipeline might.

sendDatabaseException

protected void sendDatabaseException(DatabaseException de)
                              throws org.xml.sax.SAXException

Standard method for creating writing out a DatabaseException that occured while processing a DataSource. The default XSL knows how to handle these errors and displays them accordingly.

The actual generated SAX events correspond with:

<cms-error class="org.wpi.gdc.cms.db.DatabaseException">
    <message>Exception message</message>
    <stack-trace>Stack trace</stack-trace>
    <embedded-exception class="Fully qualified class name">
        <message>Exception message</message>
        <stack-trace>Stack trace</stack-trace>
    </embedded-exception>
</cms-error>

Parameters:

de - the database exception to have SAX events created for

Throws:

org.xml.sax.SAXException - Any SAX event can cause a SAXException; this method does not directly cause one, but events in the pipeline might.

sendException

protected void sendException(java.lang.Throwable exception)
                      throws org.xml.sax.SAXException

Standard method for creating writing out an Exception that occured while processing a DataSource. The default XSL knows how to handle these errors and displays them accordingly.

The actual generated SAX events correspond with:

<cms-error class="Fully qualified class name">
    <message>Exception message</message>
    <stack-trace>Stack trace</stack-trace>
</cms-error>

Parameters:

exception - the exception to have SAX events created for

Throws:

org.xml.sax.SAXException - Any SAX event can cause a SAXException; this method does not directly cause one, but events in the pipeline might.

setDocumentLocator

public void setDocumentLocator(org.xml.sax.Locator locator)

Passes the Locator onto this datasource - this should NOT be passed onto the consumer as it already will have been.

Specified by:

setDocumentLocator in interface org.xml.sax.ContentHandler

startDocument

public void startDocument()
                   throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

startDocument in interface org.xml.sax.ContentHandler

endDocument

public void endDocument()
                 throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

endDocument in interface org.xml.sax.ContentHandler

startPrefixMapping

public void startPrefixMapping(java.lang.String prefix,
                               java.lang.String uri)
                        throws org.xml.sax.SAXException

This event should never be passed to the consumer via a DataSource, the engine takes care of passing the event.

Specified by:

startPrefixMapping in interface org.xml.sax.ContentHandler

endPrefixMapping

public void endPrefixMapping(java.lang.String prefix)
                      throws org.xml.sax.SAXException

This event should never be passed to the consumer via a DataSource, the engine takes care of passing the event.

Specified by:

endPrefixMapping in interface org.xml.sax.ContentHandler

startElement

public void startElement(java.lang.String uri,
                         java.lang.String loc,
                         java.lang.String raw,
                         org.xml.sax.Attributes a)
                  throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

startElement in interface org.xml.sax.ContentHandler

endElement

public void endElement(java.lang.String uri,
                       java.lang.String loc,
                       java.lang.String raw)
                throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

endElement in interface org.xml.sax.ContentHandler

characters

public void characters(char[] c,
                       int start,
                       int len)
                throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

characters in interface org.xml.sax.ContentHandler

ignorableWhitespace

public void ignorableWhitespace(char[] c,
                                int start,
                                int len)
                         throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

ignorableWhitespace in interface org.xml.sax.ContentHandler

processingInstruction

public void processingInstruction(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

processingInstruction in interface org.xml.sax.ContentHandler

skippedEntity

public void skippedEntity(java.lang.String name)
                   throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

skippedEntity in interface org.xml.sax.ContentHandler

startDTD

public void startDTD(java.lang.String name,
                     java.lang.String publicId,
                     java.lang.String systemId)
              throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

startDTD in interface org.xml.sax.ext.LexicalHandler

endDTD

public void endDTD()
            throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

endDTD in interface org.xml.sax.ext.LexicalHandler

startEntity

public void startEntity(java.lang.String name)
                 throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

startEntity in interface org.xml.sax.ext.LexicalHandler

endEntity

public void endEntity(java.lang.String name)
               throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

endEntity in interface org.xml.sax.ext.LexicalHandler

startCDATA

public void startCDATA()
                throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

startCDATA in interface org.xml.sax.ext.LexicalHandler

endCDATA

public void endCDATA()
              throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

endCDATA in interface org.xml.sax.ext.LexicalHandler

comment

public void comment(char[] ch,
                    int start,
                    int len)
             throws org.xml.sax.SAXException

A SAX event; this implementation does nothing.

Specified by:

comment in interface org.xml.sax.ext.LexicalHandler