org.apache.cocoon.transformation
Class SQLTransformer

java.lang.Object
  extended byorg.apache.cocoon.util.AbstractLogEnabled
      extended byorg.apache.cocoon.xml.AbstractXMLProducer
          extended byorg.apache.cocoon.xml.AbstractXMLPipe
              extended byorg.apache.cocoon.transformation.AbstractTransformer
                  extended byorg.apache.cocoon.transformation.AbstractSAXTransformer
                      extended byorg.apache.cocoon.transformation.SQLTransformer
All Implemented Interfaces:
Configurable, ContentHandler, Disposable, LexicalHandler, Poolable, Recyclable, Serviceable, org.apache.cocoon.sitemap.SitemapModelComponent, org.apache.cocoon.transformation.Transformer, org.apache.cocoon.xml.XMLConsumer, XMLConsumer, org.apache.cocoon.xml.XMLPipe, org.apache.cocoon.xml.XMLProducer

public class SQLTransformer
extends org.apache.cocoon.transformation.AbstractSAXTransformer

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 1304280 2012-03-23 11:18:01Z ilgrosso $

Field Summary
static String CLOB_ENCODING
           
protected  Connection conn
          The connection shared by top level queries (if configuration allows)
protected  int connectAttempts
          How many connection attempts to do? (default is 5 times)
protected  int connectWaittime
          How long wait between connection attempts? (default is 5000 ms)
protected  String connName
          The "name" of the connection shared by top level queries (if configuration allows)
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? (default is off)
protected  SAXParser parser
           
protected  org.apache.cocoon.transformation.SQLTransformer.Query query
          The current query we are working on
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
           
 
Fields inherited from class org.apache.cocoon.transformation.AbstractSAXTransformer
context, defaultNamespaceURI, EMPTY_ATTRIBUTES, ignoreEmptyCharacters, ignoreEventsCount, ignoreHooksCount, ignoreWhitespaces, manager, namespaceURI, objectModel, parameters, recorderStack, removeOurNamespacePrefixes, request, resolver, response, source, stack
 
Fields inherited from class org.apache.cocoon.xml.AbstractXMLProducer
contentHandler, EMPTY_CONTENT_HANDLER, lexicalHandler, xmlConsumer
 
Fields inherited from interface org.apache.cocoon.transformation.Transformer
ROLE
 
Constructor Summary
SQLTransformer()
          Constructor
 
Method Summary
 void configure(Configuration conf)
          Configure transformer.
protected  void data(String data)
          Helper method for generating SAX events
 void dispose()
           
protected  void end(String uri, String prefix, String name)
          Helper method for generating SAX events
protected  void endAncestorValueElement()
          </ancestor-value>
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 service(ServiceManager aManager)
           
 void setup(org.apache.cocoon.environment.SourceResolver resolver, Map objectModel, String source, Parameters parameters)
          Setup for the current request.
protected  void start(String uri, String prefix, String name, Attributes attr)
          Helper method for generating SAX events
protected  void startAncestorValueElement(Attributes attributes)
          <ancestor-value>
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.transformation.AbstractSAXTransformer
addRecorder, characters, comment, endCDATA, endDocument, endDTD, endElement, endEntity, endParametersRecording, endParametersRecording, endPrefixMapping, endRecording, endSAXRecording, endSerializedXMLRecording, endTextRecording, findPrefixMapping, getMutableAttributes, ignorableWhitespace, processingInstruction, removeRecorder, sendEndElementEvent, sendEndElementEventNS, sendEndPrefixMapping, sendEvents, sendParametersEvents, sendStartElementEvent, sendStartElementEvent, sendStartElementEventNS, sendStartElementEventNS, sendStartPrefixMapping, sendTextEvent, setDocumentLocator, setupTransforming, skippedEntity, startCDATA, startDocument, startDTD, startElement, startEntity, startParametersRecording, startPrefixMapping, startRecording, startSAXRecording, startSerializedXMLRecording, startTextRecording
 
Methods inherited from class org.apache.cocoon.xml.AbstractXMLProducer
setConsumer, setContentHandler, setLexicalHandler
 
Methods inherited from class org.apache.cocoon.util.AbstractLogEnabled
getLogger, setLogger
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.apache.cocoon.xml.XMLProducer
setConsumer
 

Field Detail

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.transformation.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
Constructor Detail

SQLTransformer

public SQLTransformer()
Constructor

Method Detail

service

public void service(ServiceManager aManager)
             throws ServiceException
Throws:
ServiceException
See Also:
AbstractSAXTransformer.service(org.apache.avalon.framework.service.ServiceManager)

dispose

public void dispose()
See Also:
AbstractSAXTransformer.dispose()

configure

public void configure(Configuration conf)
               throws ConfigurationException
Configure transformer. Supported configuration elements:
  • old-driver
  • connect-attempts
  • connect-waittime

Throws:
ConfigurationException

setup

public void setup(org.apache.cocoon.environment.SourceResolver resolver,
                  Map objectModel,
                  String source,
                  Parameters parameters)
           throws org.apache.cocoon.ProcessingException,
                  SAXException,
                  IOException
Setup for the current request.

Throws:
org.apache.cocoon.ProcessingException
SAXException
IOException

recycle

public void recycle()
Recycle this component


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 org.apache.cocoon.ProcessingException,
                               SAXException
</query>

Throws:
org.apache.cocoon.ProcessingException
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 org.apache.cocoon.ProcessingException,
                                         SAXException
<ancestor-value>

Throws:
org.apache.cocoon.ProcessingException
SAXException

endAncestorValueElement

protected void endAncestorValueElement()
</ancestor-value>


startSubstituteValueElement

protected void startSubstituteValueElement(Attributes attributes)
                                    throws org.apache.cocoon.ProcessingException,
                                           SAXException
<substitute-value>

Throws:
org.apache.cocoon.ProcessingException
SAXException

endSubstituteValueElement

protected void endSubstituteValueElement()
</substitute-value>


startEscapeStringElement

protected void startEscapeStringElement(Attributes attributes)
                                 throws org.apache.cocoon.ProcessingException,
                                        SAXException
<escape-string>

Throws:
org.apache.cocoon.ProcessingException
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 org.apache.cocoon.ProcessingException,
                                     SAXException
ContentHandler method

Throws:
org.apache.cocoon.ProcessingException
SAXException

endTransformingElement

public void endTransformingElement(String uri,
                                   String name,
                                   String raw)
                            throws org.apache.cocoon.ProcessingException,
                                   IOException,
                                   SAXException
ContentHandler method

Throws:
org.apache.cocoon.ProcessingException
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 1999-2008 The Apache Software Foundation. All Rights Reserved.