org.apache.cocoon.sax.component
Class SQLTransformer

java.lang.Object
  extended by org.apache.cocoon.pipeline.component.AbstractPipelineComponent
      extended by org.apache.cocoon.sax.AbstractSAXPipelineComponent
          extended by org.apache.cocoon.sax.AbstractSAXProducer
              extended by org.apache.cocoon.sax.AbstractSAXTransformer
                  extended by 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


Copyright © 2008-2012 The Apache Software Foundation. All Rights Reserved.