org.apache.cocoon.sax.component
Class SQLTransformer

java.lang.Object
  org.apache.cocoon.pipeline.component.AbstractPipelineComponent
      org.apache.cocoon.sax.AbstractSAXPipelineComponent
          org.apache.cocoon.sax.AbstractSAXProducer
              org.apache.cocoon.sax.AbstractSAXTransformer
                  org.apache.cocoon.sax.component.SQLTransformer

All Implemented Interfaces:

Consumer, PipelineComponent, Producer, SAXConsumer, SAXPipelineComponent, SAXProducer, ContentHandler, LexicalHandler

public class SQLTransformer
extends AbstractSAXTransformer
implements SAXConsumer

The SQLTransformer can be plugged into a pipeline to transform SAX events into updated or queries and responses to/from a SQL interface.

It is declared and configured as follows:

 <map:transformers default="...">
   <map:transformer name="sql" src="org.apache.cocoon.transformation.SQLTransformer">
     <old-driver>false</old-driver>
     <connection-attempts>5</connection-attempts>
     <connection-waittime>5000</connection-waittime>
   </map:transformer>
 </map:transformers>
 

It can be used in the sitemap pipeline as follows: <map:transform type="sql"> <map:parameter name="own-connection" value="..."/> <map:parameter name="use-connection" value="..."/> <map:parameter name="dburl" value="..."/> <map:parameter name="username" value="..."/> <map:parameter name="password" value="..."/> <map:parameter name="show-nr-or-rows" value="false"/> <map:parameter name="doc-element" value="rowset"/> <map:parameter name="row-element" value="row"/> <map:parameter name="namespace-uri" value="http://apache.org/cocoon/SQL/2.0"/> <map:parameter name="namespace-prefix" value="sql"/> <map:parameter name="clob-encoding" value=""/> </map:transform>

The following DTD is valid: <!ENTITY % param "(own-connection?,(use-connection|(dburl,username,password))?,show-nr-or-rows?,doc-element?,row-element?,namespace-uri?,namespace-prefix?,clob-encoding?)">
<!ELEMENT execute-query (query,(in-parameter|out-parameter)*,execute-query?, %param;)>
<!ELEMENT own-connection (#PCDATA)>
<!ELEMENT use-connection (#PCDATA)>
<!ELEMENT query (#PCDATA | substitute-value | ancestor-value | escape-string)*>
<!ATTLIST query name CDATA #IMPLIED isstoredprocedure (true|false) "false" isupdate (true|false) "false">
<!ELEMENT substitute-value EMPTY>
<!ATTLIST substitute-value name CDATA #REQUIRED>
<!ELEMENT ancestor-value EMPTY>
<!ATTLIST ancestor-value name CDATA #REQUIRED level CDATA #REQUIRED>
<!ELEMENT in-parameter EMPTY>
<!ATTLIST in-parameter nr CDATA #REQUIRED type CDATA #REQUIRED>
<!ELEMENT out-parameter EMPTY>
<!ATTLIST out-parameter nr CDATA #REQUIRED name CDATA #REQUIRED type CDATA #REQUIRED>
<!ELEMENT escape-string (#PCDATA)>


Each query can override default transformer parameters. Nested queries do not inherit parent query parameters, but only transformer parameters. Each query can have connection to different database, directly or using the connection pool. If database connection parameters are the same as for any of the ancestor queries, nested query will re-use ancestor query connection.

Connection sharing between queries can be disabled, globally or on per-query basis, using own-connection parameter.

By default, CLOBs are read from the database using character stream, so that character decoding is performed by the database. Using clob-encoding parameter, this behavior can be overrided, so that data is read as byte stream and decoded using specified character encoding.

TODO: Support inserting of the XML data into the database without need to escape it. Can be implemented by introducing new <sql:xml/> tag to indicate that startSerializedXMLRecording(...) should be used.

Version:

$Id: SQLTransformer.html 1343757 2012-05-29 14:45:42Z ilgrosso $

Field Summary

static String	CLOB_ENCODING
protected Connection	conn The connection shared by top level queries (if configuration allows)
static String	CONNECT_ATTEMPTS
protected int	connectAttempts How many connection attempts to do?
protected int	connectWaittime How long wait between connection attempts?
protected String	connName The "name" of the connection shared by top level queries (if configuration allows)
protected int	ignoreEventsCount Controlls SAX event handling.
protected int	ignoreHooksCount Controlls SAX event handling.
static String	MAGIC_ANCESTOR_VALUE
static String	MAGIC_ANCESTOR_VALUE_LEVEL_ATTRIBUTE
static String	MAGIC_ANCESTOR_VALUE_NAME_ATTRIBUTE
static String	MAGIC_COLUMN_CASE
static String	MAGIC_CONNECTION
static String	MAGIC_DBURL
static String	MAGIC_DOC_ELEMENT
static String	MAGIC_ERROR
static String	MAGIC_ESCAPE_STRING
static String	MAGIC_EXECUTE_QUERY
static String	MAGIC_IN_PARAMETER
static String	MAGIC_IN_PARAMETER_NR_ATTRIBUTE
static String	MAGIC_IN_PARAMETER_VALUE_ATTRIBUTE
static String	MAGIC_NAME_ATTRIBUTE
static String	MAGIC_NR_OF_ROWS
static String	MAGIC_NS_PREFIX_ELEMENT
static String	MAGIC_NS_URI_ELEMENT
static String	MAGIC_OUT_PARAMETER
static String	MAGIC_OUT_PARAMETER_NAME_ATTRIBUTE
static String	MAGIC_OUT_PARAMETER_NR_ATTRIBUTE
static String	MAGIC_OUT_PARAMETER_TYPE_ATTRIBUTE
static String	MAGIC_PASSWORD
static String	MAGIC_QUERY
static String	MAGIC_ROW_ELEMENT
static String	MAGIC_STORED_PROCEDURE_ATTRIBUTE
static String	MAGIC_SUBSTITUTE_VALUE
static String	MAGIC_SUBSTITUTE_VALUE_NAME_ATTRIBUTE
static String	MAGIC_UPDATE_ATTRIBUTE
static String	MAGIC_USERNAME
static String	MAGIC_VALUE
static String	NAMESPACE The SQL transformer namespace
protected boolean	oldDriver Is the old-driver turned on?
protected SAXParser	parser
protected org.apache.cocoon.sax.component.SQLTransformer.Query	query The current query we are working on
protected Stack<String>	stack A stack for collecting information.
protected int	state The current state of the event receiving FSM
protected static int	STATE_INSIDE_ANCESTOR_VALUE_ELEMENT
protected static int	STATE_INSIDE_ESCAPE_STRING
protected static int	STATE_INSIDE_EXECUTE_QUERY_ELEMENT
protected static int	STATE_INSIDE_IN_PARAMETER_ELEMENT
protected static int	STATE_INSIDE_OUT_PARAMETER_ELEMENT
protected static int	STATE_INSIDE_QUERY_ELEMENT
protected static int	STATE_INSIDE_SUBSTITUTE_VALUE_ELEMENT
protected static int	STATE_INSIDE_VALUE_ELEMENT
protected static int	STATE_OUTSIDE

Constructor Summary

SQLTransformer()
FIXME: Constructor

Method Summary

protected void	data(String data) Helper method for generating SAX events
protected void	end(String uri, String prefix, String name) Helper method for generating SAX events
protected void	endAncestorValueElement() </ancestor-value>
void	endElement(String uri, String name, String raw) Process the SAX event.
protected void	endEscapeStringElement() </escape-string>
protected void	endExecuteQueryElement() </execute-query>
protected void	endInParameterElement() </in-parameter>
protected void	endOutParameterElement() </out-parameter>
protected void	endQueryElement() </query>
protected void	endSubstituteValueElement() </substitute-value>
void	endTransformingElement(String uri, String name, String raw) ContentHandler method
protected void	endValueElement() </*>
protected String	nsQualify(String name, String prefix) Qualifies an element name by giving it a prefix.
void	recycle() Recycle this component
void	setConfiguration(Map<String,? extends Object> configuration) Configure transformer.
protected void	start(String uri, String prefix, String name, Attributes attr) Helper method for generating SAX events
protected void	startAncestorValueElement(Attributes attributes) <ancestor-value>
void	startElement(String uri, String name, String raw, Attributes attr) Process the SAX event.
protected void	startEscapeStringElement(Attributes attributes) <escape-string>
protected void	startExecuteQueryElement() <execute-query>
protected void	startInParameterElement(Attributes attributes) <in-parameter>
protected void	startOutParameterElement(Attributes attributes) <out-parameter>
protected void	startQueryElement(Attributes attributes) <query>
protected void	startSubstituteValueElement(Attributes attributes) <substitute-value>
void	startTransformingElement(String uri, String name, String raw, Attributes attributes) ContentHandler method
protected void	startValueElement(String name) <*>
protected static void	throwIllegalStateException(String message)

Methods inherited from class org.apache.cocoon.sax.AbstractSAXTransformer

characters, comment, endCDATA, endDocument, endDTD, endEntity, endPrefixMapping, endSAXRecording, endTextRecording, findPrefixMapping, ignorableWhitespace, processingInstruction, removeRecorder, sendEndPrefixMapping, sendStartPrefixMapping, setDocumentLocator, setRecorder, skippedEntity, startCDATA, startDocument, startDTD, startEntity, startPrefixMapping, startSAXRecording, startTextRecording

Methods inherited from class org.apache.cocoon.sax.AbstractSAXProducer

getSAXConsumer, setConsumer, setSAXConsumer, toString

Methods inherited from class org.apache.cocoon.pipeline.component.AbstractPipelineComponent

finish, setup

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.xml.sax.ContentHandler

characters, endDocument, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startPrefixMapping

Methods inherited from interface org.xml.sax.ext.LexicalHandler

comment, endCDATA, endDTD, endEntity, startCDATA, startDTD, startEntity

Methods inherited from interface org.apache.cocoon.pipeline.component.PipelineComponent

finish, setup

Field Detail

CONNECT_ATTEMPTS

public static final String CONNECT_ATTEMPTS

See Also:

Constant Field Values

NAMESPACE

public static final String NAMESPACE

The SQL transformer namespace

See Also:

Constant Field Values

MAGIC_EXECUTE_QUERY

public static final String MAGIC_EXECUTE_QUERY

See Also:

Constant Field Values

MAGIC_CONNECTION

public static final String MAGIC_CONNECTION

See Also:

Constant Field Values

MAGIC_DBURL

public static final String MAGIC_DBURL

See Also:

Constant Field Values

MAGIC_USERNAME

public static final String MAGIC_USERNAME

See Also:

Constant Field Values

MAGIC_PASSWORD

public static final String MAGIC_PASSWORD

See Also:

Constant Field Values

MAGIC_NR_OF_ROWS

public static final String MAGIC_NR_OF_ROWS

See Also:

Constant Field Values

MAGIC_QUERY

public static final String MAGIC_QUERY

See Also:

Constant Field Values

MAGIC_VALUE

public static final String MAGIC_VALUE

See Also:

Constant Field Values

MAGIC_COLUMN_CASE

public static final String MAGIC_COLUMN_CASE

See Also:

Constant Field Values

MAGIC_DOC_ELEMENT

public static final String MAGIC_DOC_ELEMENT

See Also:

Constant Field Values

MAGIC_ROW_ELEMENT

public static final String MAGIC_ROW_ELEMENT

See Also:

Constant Field Values

MAGIC_IN_PARAMETER

public static final String MAGIC_IN_PARAMETER

See Also:

Constant Field Values

MAGIC_IN_PARAMETER_NR_ATTRIBUTE

public static final String MAGIC_IN_PARAMETER_NR_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_IN_PARAMETER_VALUE_ATTRIBUTE

public static final String MAGIC_IN_PARAMETER_VALUE_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_OUT_PARAMETER

public static final String MAGIC_OUT_PARAMETER

See Also:

Constant Field Values

MAGIC_OUT_PARAMETER_NAME_ATTRIBUTE

public static final String MAGIC_OUT_PARAMETER_NAME_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_OUT_PARAMETER_NR_ATTRIBUTE

public static final String MAGIC_OUT_PARAMETER_NR_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_OUT_PARAMETER_TYPE_ATTRIBUTE

public static final String MAGIC_OUT_PARAMETER_TYPE_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_ESCAPE_STRING

public static final String MAGIC_ESCAPE_STRING

See Also:

Constant Field Values

MAGIC_ERROR

public static final String MAGIC_ERROR

See Also:

Constant Field Values

MAGIC_NS_URI_ELEMENT

public static final String MAGIC_NS_URI_ELEMENT

See Also:

Constant Field Values

MAGIC_NS_PREFIX_ELEMENT

public static final String MAGIC_NS_PREFIX_ELEMENT

See Also:

Constant Field Values

MAGIC_ANCESTOR_VALUE

public static final String MAGIC_ANCESTOR_VALUE

See Also:

Constant Field Values

MAGIC_ANCESTOR_VALUE_LEVEL_ATTRIBUTE

public static final String MAGIC_ANCESTOR_VALUE_LEVEL_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_ANCESTOR_VALUE_NAME_ATTRIBUTE

public static final String MAGIC_ANCESTOR_VALUE_NAME_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_SUBSTITUTE_VALUE

public static final String MAGIC_SUBSTITUTE_VALUE

See Also:

Constant Field Values

MAGIC_SUBSTITUTE_VALUE_NAME_ATTRIBUTE

public static final String MAGIC_SUBSTITUTE_VALUE_NAME_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_NAME_ATTRIBUTE

public static final String MAGIC_NAME_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_STORED_PROCEDURE_ATTRIBUTE

public static final String MAGIC_STORED_PROCEDURE_ATTRIBUTE

See Also:

Constant Field Values

MAGIC_UPDATE_ATTRIBUTE

public static final String MAGIC_UPDATE_ATTRIBUTE

See Also:

Constant Field Values

CLOB_ENCODING

public static final String CLOB_ENCODING

See Also:

Constant Field Values

STATE_OUTSIDE

protected static final int STATE_OUTSIDE

See Also:

Constant Field Values

STATE_INSIDE_EXECUTE_QUERY_ELEMENT

protected static final int STATE_INSIDE_EXECUTE_QUERY_ELEMENT

See Also:

Constant Field Values

STATE_INSIDE_VALUE_ELEMENT

protected static final int STATE_INSIDE_VALUE_ELEMENT

See Also:

Constant Field Values

STATE_INSIDE_QUERY_ELEMENT

protected static final int STATE_INSIDE_QUERY_ELEMENT

See Also:

Constant Field Values

STATE_INSIDE_ANCESTOR_VALUE_ELEMENT

protected static final int STATE_INSIDE_ANCESTOR_VALUE_ELEMENT

See Also:

Constant Field Values

STATE_INSIDE_SUBSTITUTE_VALUE_ELEMENT

protected static final int STATE_INSIDE_SUBSTITUTE_VALUE_ELEMENT

See Also:

Constant Field Values

STATE_INSIDE_IN_PARAMETER_ELEMENT

protected static final int STATE_INSIDE_IN_PARAMETER_ELEMENT

See Also:

Constant Field Values

STATE_INSIDE_OUT_PARAMETER_ELEMENT

protected static final int STATE_INSIDE_OUT_PARAMETER_ELEMENT

See Also:

Constant Field Values

STATE_INSIDE_ESCAPE_STRING

protected static final int STATE_INSIDE_ESCAPE_STRING

See Also:

Constant Field Values

oldDriver

protected boolean oldDriver

Is the old-driver turned on? (default is off)

connectAttempts

protected int connectAttempts

How many connection attempts to do? (default is 5 times)

connectWaittime

protected int connectWaittime

How long wait between connection attempts? (default is 5000 ms)

query

protected org.apache.cocoon.sax.component.SQLTransformer.Query query

The current query we are working on

state

protected int state

The current state of the event receiving FSM

connName

protected String connName

The "name" of the connection shared by top level queries (if configuration allows)

conn

protected Connection conn

The connection shared by top level queries (if configuration allows)

parser

protected SAXParser parser

stack

protected final Stack<String> stack

A stack for collecting information. The stack is important for collection information especially when the tags can be nested.

ignoreEventsCount

protected int ignoreEventsCount

Controlls SAX event handling. If this is incremented all events are not forwarded to the next pipeline component, but the hooks are still called.

ignoreHooksCount

protected int ignoreHooksCount

Controlls SAX event handling. If this is greater than zero, the hooks are not called. Attention, make sure, that you decrement this counter properly as your hooks are not called anymore!

Constructor Detail

SQLTransformer

public SQLTransformer()

FIXME: Constructor

Method Detail

recycle

public void recycle()

Recycle this component

setConfiguration

public void setConfiguration(Map<String,? extends Object> configuration)

Configure transformer. Supported configuration elements:

• old-driver
• connect-attempts
• connect-waittime

Specified by:

setConfiguration in interface PipelineComponent

Overrides:

setConfiguration in class AbstractPipelineComponent

Parameters:

configuration - The Map of configuration parameters.

startElement

public void startElement(String uri,
                         String name,
                         String raw,
                         Attributes attr)
                  throws SAXException

Process the SAX event. The namespace of the event is checked. If it is the defined namespace for this transformer, the startTransformingElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes) hook is called.

Specified by:

startElement in interface ContentHandler

Overrides:

startElement in class AbstractSAXTransformer

Throws:

SAXException

See Also:

ContentHandler.startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endElement

public void endElement(String uri,
                       String name,
                       String raw)
                throws SAXException

Process the SAX event. The namespace of the event is checked. If it is the defined namespace for this transformer, the endTransformingElement(java.lang.String, java.lang.String, java.lang.String) hook is called.

Specified by:

endElement in interface ContentHandler

Overrides:

endElement in class AbstractSAXTransformer

Throws:

SAXException

See Also:

ContentHandler.endElement(java.lang.String, java.lang.String, java.lang.String)

throwIllegalStateException

protected static void throwIllegalStateException(String message)

startExecuteQueryElement

protected void startExecuteQueryElement()

<execute-query>

startValueElement

protected void startValueElement(String name)
                          throws SAXException

<*>

Throws:

SAXException

startQueryElement

protected void startQueryElement(Attributes attributes)
                          throws SAXException

<query>

Throws:

SAXException

endQueryElement

protected void endQueryElement()
                        throws SAXException

</query>

Throws:

SAXException

endValueElement

protected void endValueElement()
                        throws SAXException

</*>

Throws:

SAXException

endExecuteQueryElement

protected void endExecuteQueryElement()
                               throws SAXException

</execute-query>

Throws:

SAXException

startAncestorValueElement

protected void startAncestorValueElement(Attributes attributes)
                                  throws SAXException

<ancestor-value>

Throws:

SAXException

endAncestorValueElement

protected void endAncestorValueElement()

</ancestor-value>

startSubstituteValueElement

protected void startSubstituteValueElement(Attributes attributes)
                                    throws SAXException

<substitute-value>

Throws:

SAXException

endSubstituteValueElement

protected void endSubstituteValueElement()

</substitute-value>

startEscapeStringElement

protected void startEscapeStringElement(Attributes attributes)
                                 throws SAXException

<escape-string>

Throws:

SAXException

endEscapeStringElement

protected void endEscapeStringElement()
                               throws SAXException

</escape-string>

Throws:

SAXException

startInParameterElement

protected void startInParameterElement(Attributes attributes)

<in-parameter>

endInParameterElement

protected void endInParameterElement()

</in-parameter>

startOutParameterElement

protected void startOutParameterElement(Attributes attributes)

<out-parameter>

endOutParameterElement

protected void endOutParameterElement()

</out-parameter>

startTransformingElement

public void startTransformingElement(String uri,
                                     String name,
                                     String raw,
                                     Attributes attributes)
                              throws SAXException

ContentHandler method

Throws:

SAXException

endTransformingElement

public void endTransformingElement(String uri,
                                   String name,
                                   String raw)
                            throws IOException,
                                   SAXException

ContentHandler method

Throws:

IOException

SAXException

nsQualify

protected String nsQualify(String name,
                           String prefix)

Qualifies an element name by giving it a prefix.

Parameters:

name - the element name

prefix - the prefix to qualify with

Returns:

a namespace qualified name that is correct

start

protected void start(String uri,
                     String prefix,
                     String name,
                     Attributes attr)
              throws SAXException

Helper method for generating SAX events

Throws:

SAXException

end

protected void end(String uri,
                   String prefix,
                   String name)
            throws SAXException

Helper method for generating SAX events

Throws:

SAXException

data

protected void data(String data)
             throws SAXException

Helper method for generating SAX events

Throws:

SAXException