You are viewing a plain text version of this content. The canonical link for it is here.
Posted to taglibs-dev@jakarta.apache.org by mo...@apache.org on 2001/08/07 00:06:03 UTC
cvs commit: jakarta-taglibs/dbtags/xml dbtags.xml description.html documentation.html requirements.html
morgand 01/08/06 15:06:03
Modified: dbtags build.xml
Added: dbtags/xml dbtags.xml description.html documentation.html
requirements.html
Removed: dbtags/conf dbtags.tld
dbtags/doc/web index.html
dbtags/lib jdbc2_0-stdext.jar
Log:
updated to the new build format
Revision Changes Path
1.10 +15 -212 jakarta-taglibs/dbtags/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-taglibs/dbtags/build.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- build.xml 2001/07/30 16:14:09 1.9
+++ build.xml 2001/08/06 22:06:02 1.10
@@ -1,221 +1,24 @@
-<!-- ANT Build Script for the "dbtags" Custom Tag Library -->
-<project name="dbtags" default="main" basedir=".">
+<?xml version="1.0"?>
- <!-- ******************** Adjustable Properties *********************** -->
+<!DOCTYPE project [
+ <!ENTITY common SYSTEM "file:../common.xml">
+]>
- <!--
+<project name="dbtags" default="main">
- The following property values should be examined and customized
- for each custom tag library subproject.
+ <!-- create this file to store the locations of your dependant jars -->
+ <property file="../build.properties"/>
+ <property name="classpath" value="${servlet.jar}:${jdbc2_0-stdext.jar}"/>
- ant.home Home directory for the ANT build tool
- This is normally defaulted from the
- ANT_HOME environment variable in the
- build script.
+ <property name="checkRequirements.pre" value="checkRequirements.pre"/>
- servlet.jar Pathname of the servlet API classes
- you are using to compile, such as the
- one that comes with Tomcat. This is
- normally defaulted from the SERVLET_JAR
- environment variable in the build script.
-
- taglib.name Base name of this tag library subproject.
-
- -->
-
- <property name="taglib.name" value="dbtags"/>
- <property name="ant.home" value="../../jakarta-ant"/>
- <property name="servlet.jar" value="../../jakarta-servletapi/lib/servlet.jar"/>
- <property name="jdbc-ext.jar" value="lib/jdbc2_0-stdext.jar"/>
-
-
- <!-- ****************** Project Standard Properties ******************* -->
-
- <!--
-
- The following property values reflect the standard directory
- organization for the jakarta-taglibs project, and should not
- be changed or overridden.
-
- build.dir Base directory for build targets
- dist.dir Base directory for distribution targets
- taglibs.xsl Taglibs stylesheet
-
- -->
-
- <property name="build.dir" value="../build"/>
- <property name="dist.dir" value="../dist"/>
- <property name="taglibs.xsl" value="../src/doc/stylesheets/taglibs.xsl"/>
-
- <!-- *********************** Default Properties ********************** -->
-
- <!--
-
- The following property values reflect the recommended directory
- structure for each custom tag library subproject. You should only
- need to adjust or override them if you use a different organization.
-
- conf.src Library configuration source directory
- doc.src Documentation app source directory
- examples.src Examples app source directory
- library.src Library Java source directory
-
- -->
-
- <property name="conf.src" value="conf"/>
- <property name="doc.src" value="doc"/>
- <property name="examples.src" value="examples"/>
- <property name="library.src" value="src"/>
- <property name="lib.src" value="lib"/>
-
-
- <!-- ********************* Derived Properties ************************* -->
-
- <!--
-
- These property values are derived from the previously defined values,
- and should not normally be overridden from the command line.
-
- build.doc Target directory for documentation app
- build.examples Target directory for examples app
- build.library Target directory for tag library
- dist.doc Destination WAR for documentation app
- dist.examples Destination WAR for examples app
- dist.library Destination JAR for tag library
- dist.tld Destination TLD file for tag library
-
- -->
-
- <property name="build.doc" value="${build.dir}/${taglib.name}/${taglib.name}-doc"/>
- <property name="build.examples" value="${build.dir}/${taglib.name}/${taglib.name}-examples"/>
- <property name="build.library" value="${build.dir}/${taglib.name}/${taglib.name}"/>
- <property name="dist.doc" value="${dist.dir}/${taglib.name}/${taglib.name}-doc.war"/>
- <property name="dist.examples" value="${dist.dir}/${taglib.name}/${taglib.name}-examples.war"/>
- <property name="dist.library" value="${dist.dir}/${taglib.name}/${taglib.name}.jar"/>
- <property name="dist.tld" value="${dist.dir}/${taglib.name}/${taglib.name}.tld"/>
- <property name="taglibs.doc" value="${dist.dir}/doc/doc/${taglib.name}-doc"/>
-
-
- <!-- ********************** Destination Preparation ********************* -->
-
- <target name="prepare">
- <!-- Set up build directories -->
- <mkdir dir="${build.dir}"/>
- <mkdir dir="${build.doc}"/>
- <mkdir dir="${build.doc}/javadoc"/>
- <mkdir dir="${build.doc}/WEB-INF"/>
- <mkdir dir="${build.doc}/WEB-INF/classes"/>
- <mkdir dir="${build.doc}/WEB-INF/lib"/>
- <mkdir dir="${build.examples}"/>
- <mkdir dir="${build.examples}/WEB-INF"/>
- <mkdir dir="${build.examples}/WEB-INF/classes"/>
- <mkdir dir="${build.examples}/WEB-INF/lib"/>
- <mkdir dir="${build.library}"/>
- <mkdir dir="${build.library}/META-INF"/>
- <!-- Set up distribution directory -->
- <mkdir dir="${dist.dir}"/>
- <mkdir dir="${dist.dir}/${taglib.name}"/>
- </target>
-
-
- <!-- **************** Compile Tag Library Components ******************** -->
-
- <!-- Compile the documentation application -->
- <target name="documentation" depends="prepare">
- <copy todir="${build.doc}/WEB-INF">
- <fileset dir="${doc.src}/conf"/>
- </copy>
- <!-- intro.xml isn't part of the documentation application,
- this is just a handy place to build it for the web site. -->
- <style in="xml/intro.xml"
- destdir="${build.doc}"
- out="${build.doc}/intro.html"
- style="${taglibs.xsl}">
- <param name="prefix" expression="../../"/>
- </style>
- <copy todir="${build.doc}">
- <fileset dir="${doc.src}/web">
- <include name="**/*.html"/>
- </fileset>
- </copy>
-
- <javadoc packagenames="org.apache.taglibs.dbtags.*"
- classpath="${servlet.jar}"
- sourcepath="src"
- destdir="${build.doc}/javadoc"
- author="true"
- version="true"
- use="true"
- windowtitle="Jakarta DBTags custom tag library API"
- doctitle="Jakarta DBTags custom tag library"
- bottom="Copyright © 2000 Apache Software Foundation. All Rights Reserved."
- />
- </target>
-
- <!-- Compile the examples application -->
- <target name="examples" depends="library-dist">
- <copy todir="${build.examples}/WEB-INF">
- <fileset dir="${examples.src}/conf"/>
- </copy>
- <copy todir="${build.examples}">
- <fileset dir="${examples.src}/web"/>
- </copy>
- <copy file="${conf.src}/dbtags.tld" tofile="${dist.tld}"/>
- <copy file="${dist.tld}"
- tofile="${build.examples}/WEB-INF/${taglib.name}.tld"/>
- <copy file="${dist.library}"
- tofile="${build.examples}/WEB-INF/lib/${taglib.name}.jar"/>
- <copy file="${examples.src}/web/jdbc.jsp"
- tofile="${build.examples}/jdbc.txt"/>
- </target>
-
- <!-- Compile the tag library itself -->
- <target name="library" depends="prepare">
- <copy file="${conf.src}/dbtags.tld"
- tofile="${build.library}/META-INF/taglib.tld"/>
- <javac srcdir="${library.src}" destdir="${build.library}"
- classpath="${servlet.jar}:${jdbc-ext.jar}" debug="on"/>
- </target>
-
- <!-- Compile the library as well as the associated applications -->
- <target name="main" depends="library,documentation,examples"/>
-
-
- <!-- ******************* Create Distribution Files ********************** -->
-
- <!-- Create the documentation application WAR file -->
- <target name="documentation-dist" depends="documentation">
- <jar jarfile="${dist.doc}" basedir="${build.doc}" excludes="intro.html"/>
- <mkdir dir="${taglibs.doc}"/>
- <copy todir="${taglibs.doc}">
- <fileset dir="${build.doc}">
- <exclude name="WEB-INF"/>
- </fileset>
- </copy>
- </target>
-
- <!-- Create the examples application WAR file -->
- <target name="examples-dist" depends="examples">
- <jar jarfile="${dist.examples}" basedir="${build.examples}"/>
- </target>
-
- <!-- Create the library distribution files -->
- <target name="library-dist" depends="library">
- <jar jarfile="${dist.library}" basedir="${build.library}"/>
- <copy file="${conf.src}/${taglib.name}.tld" tofile="${dist.tld}"/>
+ <target name="checkRequirements.pre">
+ <antcall target="checkRequiredFile">
+ <param name="file" value="${jdbc2_0-stdext.jar}"/>
+ <param name="fail.message" value="a jar file containing the jdbc2_0-stdext classes is required to compile the dbtags taglib. please define the property jdbc2_0-stdext.jar in your build.properties file and ensure that the file exists"/>
+ </antcall>
</target>
-
- <!-- Create the entire set of distribution files -->
- <target name="dist" depends="library-dist,examples-dist,documentation-dist"/>
-
-
- <!-- ************************ Utility Commands ************************** -->
-
- <!-- Delete output directories and files so we can build from scratch -->
- <target name="clean">
- <delete dir="${build.dir}/${taglib.name}"/>
- <delete dir="${dist.dir}/${taglib.name}"/>
- </target>
+ &common;
</project>
1.1 jakarta-taglibs/dbtags/xml/dbtags.xml
Index: dbtags.xml
===================================================================
<?xml version="1.0" ?>
<!-- Change all instances of application with the jakarta-taglib
name for this tag library.
Change all instances of Application with the name to use
for things such as titles in the tag library documentation.
Change all instances of {your-name} with your name for
for things such as author name in the tag library documentation.
Change <prefix>foo</prefix> below to a short prefix for this
tag library.
-->
<document url="./dbtags.xml">
<!-- More properties can be added. Good place to stick loose
data needed elsewhere. -->
<properties>
<!-- The title here overrides the title generated by the
stylesheet for the documentation HTML <title> tag
<title>Jakarta Project: DBTags JSP Tag Library</title>
-->
<!-- The name here is used in the HTML <meta name="author"...> tag -->
<author>Morgan Delagrange</author>
</properties>
<!-- The following defines elements uses both to create the taglib
documentation and the tag library descriptor .tld file. The
elements used are those from the JSP 1.2 TLD DTD and special
elements used when creating the tagib documentation. Although
the JSP1.2 TLD DTD is used, this document can be used to
generate both a JSP 1.1 and a JSP 1.2 TLD.
-->
<taglib>
<!-- The following elements are from the JSP 1.2 TLD DTD -->
<!-- Version number of this tagib -->
<tlib-version>1.0</tlib-version>
<!-- Minimum version of JSP spec required -->
<jsp-version>1.1</jsp-version>
<!-- jakarta-taglib name of this tag library -->
<short-name>DBTags</short-name>
<!-- URI of taglib -->
<uri>http://jakarta.apache.org/taglibs/dbtags</uri>
<!-- The name to use in titles, etc. for the taglib -->
<display-name>DBTags Tag library (Pre Beta)</display-name>
<description uri="../../dbtags/xml/description.html"/>
<!-- The taglib-location is used to fill in the web.xml configuration
information in the HTML doc. -->
<taglib-location>/WEB-INF/dbtags.tld</taglib-location>
<!-- The prefix is used to fill in the taglib directive
configuration information in the HTML doc. -->
<prefix>sql</prefix>
<!-- This element must be straight text and is copied right into
the "Requirements" section of the HTML doc. -->
<requirements-info uri="../../dbtags/xml/requirements.html"/>
<documentation>
<doctoc>
<li anchor="overview.usage">Simple Usage Example</li>
<li anchor="overview.tags">Tags In Detail</li>
<ul>
<li anchor="overview.tags.connection">Connection Tags</li>
<li anchor="overview.tags.statement">Statement Tags</li>
<li anchor="overview.tags.preparedstatement">PreparedStatement Tags</li>
<li anchor="overview.tags.resultset">ResultSet Tags</li>
</ul>
</doctoc>
<docs uri="../../dbtags/xml/documentation.html"/>
</documentation>
<tagtoc name="Connection Tags">
<tag>
<name>connection</name>
<tag-class>org.apache.taglibs.dbtags.connection.ConnectionTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.connection.ConnectionTEI</tei-class>
<body-content>JSP</body-content>
<description>
Get a java.sql.Connection object from the DriverManager or a DataSource.
</description>
<availability>1.0</availability>
<variable>
<name-from-attribute>id</name-from-attribute>
<variable-class>java.sql.Connection</variable-class>
<declare>true</declare>
<scope>AT_END</scope>
<availability>1.0</availability>
<beanprop>
<name>catalog</name>
<get>yes</get>
<set>yes</set>
<description>Set the catalog for this connection.</description>
<availability>1.0</availability>
</beanprop>
<beanprop>
<name>closed</name>
<get>yes</get>
<set>no</set>
<description>False if the connection is open, true if it is not.</description>
<availability>1.0</availability>
</beanprop>
<beanprop>
<name>readOnly</name>
<get>yes</get>
<set>yes</set>
<description>True if the connection has read-only permission.</description>
<availability>1.0</availability>
</beanprop>
</variable>
<attribute>
<name>id</name>
<required>yes</required>
<rtexprvalue>no</rtexprvalue>
<description>
Name of the resulting Connection attribute.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>dataSource</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Name of an existing page attribute that
contains a DataSource object.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>jndiName</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Name used to find a datasource via jndi.
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<comment>
Method 1: using the DriverManager
</comment>
<code>
<![CDATA[
<%-- open a database connection --%>
<sql:connection id="conn1">
<%-- required --%>
<sql:url>jdbc:mysql://localhost/test</sql:url>
<%-- optional --%>
<sql:driver>org.gjt.mm.mysql.Driver</sql:driver>
<%-- optional --%>
<sql:userId>root</sql:userId>
<%-- optional --%>
<sql:password>notVerySecure</sql:password>
</sql:connection>
]]>
</code>
</usage>
<usage>
<comment>
Method 2: using a DataSource
</comment>
<code>
<![CDATA[
<%-- open a database connection --%>
<sql:connection id="conn1" dataSource="ds1">
<%-- optional --%>
<sql:userId>root</sql:userId>
<%-- optional --%>
<sql:password>notVerySecure</sql:password>
</sql:connection>
]]>
</code>
</usage>
<usage>
<comment>
Method 3: using a jndi named DataSource
</comment>
<code>
<![CDATA[
<%-- open a database connection --%>
<sql:connection id="conn1" jndiName="java:/comp/jdbc/test"/>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>url</name>
<tag-class>org.apache.taglibs.dbtags.connection.DatabaseURLTag</tag-class>
<body-content>JSP</body-content>
<description>
Sets the database URL of the enclosing connection tag.
</description>
<availability>1.0</availability>
<restrictions>Use inside a connection tag.</restrictions>
<attribute>
<name>initParameter</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optional attribute, indicating the name of
an init parameter
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- example 1: using the tag body --%>
<sql:connection id="conn1">
<sql:url>jdbc:mysql://localhost/test</sql:url>
</sql:connection>
<%-- example 2: using an init parameter --%>
<sql:connection id="conn1">
<sql:url initParameter="dbURL"/>
</sql:connection>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>jndiName</name>
<tag-class>org.apache.taglibs.dbtags.connection.JndiNameTag</tag-class>
<body-content>JSP</body-content>
<description>
Sets the JNDI named JDBC DataSource of the enclosing connection tag.
</description>
<availability>1.0</availability>
<restrictions>Use inside a connection tag.</restrictions>
<attribute>
<name>initParameter</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optional attribute, indicating the name of
an init parameter
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- example 1: using the tag body --%>
<sql:connection id="conn1">
<sql:jndiName>java:/comp/jdbc/test</sql:jndiName>
</sql:connection>
<%-- example 2: using an init parameter --%>
<sql:connection id="conn1">
<sql:jndiName initParameter="jndiDataSource"/>
</sql:connection>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>driver</name>
<tag-class>org.apache.taglibs.dbtags.connection.DriverTag</tag-class>
<body-content>JSP</body-content>
<display-name>existsAttribute</display-name>
<description>
Sets the driver class name for the connection tag.
</description>
<availability>1.0</availability>
<restrictions>Use inside a connection tag.</restrictions>
<attribute>
<name>initParameter</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>Optional attribute, indicating the name of
an init parameter.</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- example 1: using the tag body --%>
<sql:connection id="conn1">
<sql:url>jdbc:mysql://localhost/test</sql:url>
<sql:driver>org.gjt.mm.mysql.Driver</sql:driver>
</sql:connection>
<%-- example 2: using an init parameter --%>
<sql:connection id="conn1">
<sql:url initParameter="dbURL"/>
<sql:driver initParameter="dbDriver"/>
</sql:connection>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>userId</name>
<tag-class>org.apache.taglibs.dbtags.connection.UserIdTag</tag-class>
<body-content>JSP</body-content>
<description>Sets the user id for the connection tag.</description>
<availability>1.0</availability>
<restrictions>Use inside a connection tag.</restrictions>
<attribute>
<name>initParameter</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>Optional attribute, indicating the name of
an init parameter.</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- example 1: using the tag body --%>
<sql:connection id="conn1">
<sql:url>jdbc:mysql://localhost/test</sql:url>
<sql:userId>root</sql:userId>
</sql:connection>
<%-- example 2: using an init parameter --%>
<sql:connection id="conn1">
<sql:url initParameter="dbURL"/>
<sql:userId initParameter="dbUserId"/>
</sql:connection>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>password</name>
<tag-class>org.apache.taglibs.dbtags.connection.PasswordTag</tag-class>
<body-content>JSP</body-content>
<description>
Sets the password for the connection tag.
</description>
<availability>1.0</availability>
<restrictions>Use inside a connection tag.</restrictions>
<attribute>
<name>initParameter</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optional attribute, indicating the name of
an init parameter.
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- example 1: using the tag body --%>
<sql:connection id="conn1">
<sql:url>jdbc:mysql://localhost/test</sql:url>
<sql:userId>root</sql:userId>
<sql:password>notVerySecure</sql:password>
</sql:connection>
<%-- example 2: using an init parameter --%>
<sql:connection id="conn1">
<sql:url initParameter="dbURL"/>
<sql:userId initParameter="dbUserId"/>
<sql:password initParameter="dbPassword"/>
</sql:connection>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>closeConnection</name>
<tag-class>org.apache.taglibs.dbtags.connection.CloseConnectionTag</tag-class>
<body-content>empty</body-content>
<description>
Close the specified connection. The "conn" attribute is the name of a
connection object in the page context.
</description>
<availability>1.0</availability>
<attribute>
<name>conn</name>
<required>yes</required>
<rtexprvalue>no</rtexprvalue>
<description>
Id of the connection you
want to close.
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- open a database connection --%>
<sql:connection id="conn1">
<sql:url>jdbc:mysql://localhost/test</sql:url>
<sql:userId>root</sql:userId>
<sql:password>notVerySecure</sql:password>
</sql:connection>
<%-- statement tags go here --%>
<sql:closeConnection conn="conn1"/>
]]>
</code>
</usage>
</example>
</tag>
</tagtoc>
<tagtoc name="Statement Only Tags">
<tag>
<name>statement</name>
<tag-class>org.apache.taglibs.dbtags.statement.StatementImplTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.statement.StatementTEI</tei-class>
<body-content>JSP</body-content>
<description>
Create and execute a database query.
</description>
<availability>1.0</availability>
<variable>
<name-from-attribute>id</name-from-attribute>
<variable-class>java.sql.Statement</variable-class>
<declare>true</declare>
<scope>NESTED</scope>
<availability>1.0</availability>
<beanprop>
<name>fetchSize</name>
<get>yes</get>
<set>yes</set>
<description>
the number of rows that should be fetched from the
database when more rows are needed
</description>
<availability>1.0</availability>
</beanprop>
<beanprop>
<name>maxRows</name>
<get>yes</get>
<set>yes</set>
<description>
the maximum number of rows that a ResultSet object
can contain (handy!)
</description>
<availability>1.0</availability>
</beanprop>
<beanprop>
<name>queryTimeout</name>
<get>yes</get>
<set>yes</set>
<description>
the number of seconds the driver will wait for a
Statement object to execute
</description>
<availability>1.0</availability>
</beanprop>
</variable>
<attribute>
<name>id</name>
<required>yes</required>
<rtexprvalue>no</rtexprvalue>
<description>
Script variable id for use with standard jsp:getProperty tag.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>conn</name>
<required>yes</required>
<rtexprvalue>no</rtexprvalue>
<description>
id of the connection to use
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- insert a row into the database --%>
<sql:statement id="stmt1" conn="conn1">
<%-- set the SQL query --%>
<sql:query>
insert into test_books (id, name)
values (3,
'<sql:escapeSql><%= request.getParameter("book_title") %></sql:escapeSql>')
</sql:query>
<%-- execute the query --%>
<sql:execute/>
</sql:statement>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>escapeSql</name>
<tag-class>org.apache.taglibs.dbtags.statement.EscapeSQLTag</tag-class>
<body-content>JSP</body-content>
<description>
Replaces each single quote in the tag body
with a pair of single quotes.
</description>
<availability>1.0</availability>
<restrictions>Use inside a query tag.</restrictions>
<example>
<usage>
<code>
<![CDATA[
<%-- insert a row into the database --%>
<sql:statement id="stmt1" conn="conn1">
<%-- set the SQL query --%>
<sql:query>
insert into test_books (id, name)
values (3,
'<sql:escapeSql><%=request.getParameter("book_title")%></sql:escapeSql>')
</sql:query>
<%-- execute the query --%>
<sql:execute/>
</sql:statement>
]]>
</code>
</usage>
</example>
</tag>
</tagtoc>
<tagtoc name="Statement/PreparedStatement Tags">
<tag>
<name>query</name>
<tag-class>org.apache.taglibs.dbtags.statement.QueryTag</tag-class>
<body-content>JSP</body-content>
<description>
Set a query for a statement or preparedStatement tag
</description>
<availability>1.0</availability>
<restrictions>Use inside a statement or preparedStatement tag.</restrictions>
<example>
<usage>
<code>
<![CDATA[
<%-- insert a row into the database --%>
<sql:statement id="stmt1" conn="conn1">
<%-- set the SQL query --%>
<sql:query>
insert into test_books (id, name)
values (3, '<sql:escapeSql><%=request.getParameter("book_title")%></sql:escapeSql>')
</sql:query>
<%-- execute the query --%>
<sql:execute/>
</sql:statement>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>execute</name>
<tag-class>org.apache.taglibs.dbtags.statement.ExecuteTag</tag-class>
<body-content>JSP</body-content>
<description>
Executes an insert, update or delete for a statement or
preparedStatement tag
</description>
<availability>1.0</availability>
<restrictions>Use inside a statement or preparedStatement tag.</restrictions>
<example>
<usage>
<code>
<![CDATA[
<%-- insert a row into the database --%>
<sql:statement id="stmt1" conn="conn1">
<%-- set the SQL query --%>
<sql:query>
insert into test_books (id, name)
values (3, '<sql:escapeSql><%=request.getParameter("book_title")%></sql:escapeSql>')
</sql:query>
<%-- execute the query --%>
<sql:execute/>
</sql:statement>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>wasEmpty</name>
<tag-class>org.apache.taglibs.dbtags.statement.WasEmptyTag</tag-class>
<body-content>JSP</body-content>
<description>
Executes its body if the last ResultSet tag received 0 rows
from the database. You must be after a ResultSet tag and inside
a StatementTag or PreparedStatementTag, or an error will be generated.
</description>
<availability>1.0</availability>
<restrictions>Use inside a statement or preparedStatement tag and
after a ResultSet tag.</restrictions>
<example>
<usage>
<code>
<![CDATA[
<%-- showing the contents of the table --%>
<table>
<tr><th>id</th><th>name</th><th>description</th></tr>
<sql:preparedStatement id="stmt6" conn="conn1">
<sql:query>
select id, name, description from test_books
</sql:query>
<sql:resultSet id="rset4">
<tr>
<td><sql:getColumn position="1"/></td>
<td><sql:getColumn position="2"/></td>
<td><sql:getColumn position="3" to="description"/></td>
</tr>
</sql:resultSet>
<tr>
<td colspan="3">
<%-- show different text, depending on whether or not
any rows were retrieved --%>
<sql:wasEmpty>No rows retrieved.</sql:wasEmpty>
<sql:wasNotEmpty><sql:rowCount/> rows retrieved.</sql:wasNotEmpty>
</td>
</tr>
</sql:preparedStatement>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>wasNotEmpty</name>
<tag-class>org.apache.taglibs.dbtags.statement.WasNotEmptyTag</tag-class>
<body-content>JSP</body-content>
<description>
Executes its body if the last ResultSet tag received more than 0 rows
from the database. You must be after a ResultSet tag and inside
a StatementTag or PreparedStatementTag, or an error will be generated.
</description>
<availability>1.0</availability>
<restrictions>Use inside a statement or preparedStatement tag and
after a ResultSet tag.</restrictions>
<example>
<usage>
<code>
<![CDATA[
<%-- showing the contents of the table --%>
<table>
<tr><th>id</th><th>name</th><th>description</th></tr>
<sql:preparedStatement id="stmt6" conn="conn1">
<sql:query>
select id, name, description from test_books
</sql:query>
<sql:resultSet id="rset4">
<tr>
<td><sql:getColumn position="1"/></td>
<td><sql:getColumn position="2"/></td>
<td><sql:getColumn position="3" to="description"/></td>
</tr>
</sql:resultSet>
<tr>
<td colspan="3">
<%-- show different text, depending on whether or not
any rows were retrieved --%>
<sql:wasEmpty>No rows retrieved.</sql:wasEmpty>
<sql:wasNotEmpty><sql:rowCount/> rows retrieved.</sql:wasNotEmpty>
</td>
</tr>
</sql:preparedStatement>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>rowCount</name>
<tag-class>org.apache.taglibs.dbtags.statement.RowCountTag</tag-class>
<body-content>empty</body-content>
<description>
Prints out the number of rows retrieved from the database.
It can be used inside a ResultSet tag to provide a running
count of rows retreived, or after the ResultSet tag to
display the total number. Using the tag before the ResultSet
or outside of a Statement or PreparedStatement will
produce an error.
</description>
<availability>1.0</availability>
<restrictions>Use inside a statement or preparedStatement tag and not
before a ResultSet tag.</restrictions>
<example>
<usage>
<code>
<![CDATA[
<%-- showing the contents of the table --%>
<table>
<tr><th>id</th><th>name</th><th>description</th></tr>
<sql:preparedStatement id="stmt6" conn="conn1">
<sql:query>
select id, name, description from test_books
</sql:query>
<sql:resultSet id="rset4">
<tr>
<td><sql:getColumn position="1"/></td>
<td><sql:getColumn position="2"/></td>
<td><sql:getColumn position="3" to="description"/></td>
</tr>
</sql:resultSet>
<tr>
<td colspan="3">
<%-- show different text, depending on whether or not
any rows were retrieved --%>
<sql:wasEmpty>No rows retrieved.</sql:wasEmpty>
<sql:wasNotEmpty><sql:rowCount/> rows retrieved.</sql:wasNotEmpty>
</td>
</tr>
</sql:preparedStatement>
]]>
</code>
</usage>
</example>
</tag>
</tagtoc>
<tagtoc name="PreparedStatement Only Tags">
<tag>
<name>preparedStatement</name>
<tag-class>org.apache.taglibs.dbtags.preparedstatement.PreparedStatementImplTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.preparedstatement.PreparedStatementTEI</tei-class>
<body-content>JSP</body-content>
<description>
Create and execute a tokenized database query
</description>
<availability>1.0</availability>
<restrictions>The scipt variable is not available until after the query
tag is called.</restrictions>
<variable>
<name-from-attribute>id</name-from-attribute>
<variable-class>java.sql.PreparedStatement</variable-class>
<declare>true</declare>
<scope>NESTED</scope>
<availability>1.0</availability>
<beanprop>
<name>fetchSize</name>
<get>yes</get>
<set>yes</set>
<description>the number of rows that should be fetched from the
database when more rows are needed</description>
<availability>1.0</availability>
</beanprop>
<beanprop>
<name>maxRows</name>
<get>yes</get>
<set>yes</set>
<description>the maximum number of rows that a ResultSet object
can contain (handy!)</description>
<availability>1.0</availability>
</beanprop>
<beanprop>
<name>queryTimeout</name>
<get>yes</get>
<set>yes</set>
<description>the number of seconds the driver will wait for a
Statement object to execute</description>
<availability>1.0</availability>
</beanprop>
</variable>
<attribute>
<name>id</name>
<required>yes</required>
<rtexprvalue>no</rtexprvalue>
<description>
Script variable id
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>conn</name>
<required>yes</required>
<rtexprvalue>no</rtexprvalue>
<description>
id of the connection to use
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- insert a row into the database --%>
<sql:preparedStatement id="stmt1" conn="conn1">
<sql:query>
insert into test_books (id, name)
values (?, ?)
</sql:query>
<sql:execute>
<sql:setColumn position="1">3</sql:setColumn>
<sql:setColumn position="2"><%=request.getParameter("book_title")%></sql:setColumn>
</sql:execute>
</sql:preparedStatement>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>setColumn</name>
<tag-class>org.apache.taglibs.dbtags.preparedstatement.SetColumnTag</tag-class>
<body-content>JSP</body-content>
<description>
Set a field in a preparedStatement. Set the value as a
String inside the tag body.
</description>
<availability>1.0</availability>
<restrictions>Use within the preparedStatement tag</restrictions>
<attribute>
<name>position</name>
<required>yes</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column position
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- use the tag body --%>
<sql:setColumn position="1"><%= someValue %></sql:setColumn>
]]>
</code>
</usage>
</example>
</tag>
</tagtoc>
<tagtoc name="ResultSet Tags">
<tag>
<name>resultSet</name>
<tag-class>org.apache.taglibs.dbtags.resultset.ResultSetTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.resultset.ResultSetTEI</tei-class>
<body-content>JSP</body-content>
<description>
JSP tag resulset, executes the query and loops through the results
for the enclosing statement or preparedstatement tag. The body of
this tag is executed once per row in the resultset. The optional
"loop" attribute, which default to true, specifies whether to execute
the tag body once per row "true", or to simply assign the ResultSet
to the page attribute specified by "id".
</description>
<availability>1.0</availability>
<restrictions>Use within a statement or preparedStatement
and after a query.</restrictions>
<variable>
<name-from-attribute>id</name-from-attribute>
<variable-class>java.sql.ResultSet</variable-class>
<declare>true</declare>
<scope>NESTED</scope>
<availability>1.0</availability>
<beanprop>
<name>fetchSize</name>
<get>yes</get>
<set>yes</set>
<description>the number of rows that should be fetched from the
database when more rows are needed</description>
<availability>1.0</availability>
</beanprop>
</variable>
<attribute>
<name>id</name>
<required>yes</required>
<rtexprvalue>no</rtexprvalue>
<description>
Script variable id
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>loop</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
True: execute the tag body once per row in the
result set, automatically advancing the rows. False: execute
the tag body once.
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- open a database query --%>
<table>
<sql:statement id="stmt1" conn="conn1">
<sql:query>
select id, name, description from test_books
order by 1
</sql:query>
<%-- loop through the rows of your query --%>
<sql:resultSet id="rset2">
<tr>
<td><sql:getColumn position="1"/></td>
<td><sql:getColumn position="2"/></td>
<td><sql:getColumn position="3"/>
<sql:wasNull>[no description]</sql:wasNull></td>
</tr>
</sql:resultSet>
</sql:statement>
</table>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>wasNull</name>
<tag-class>org.apache.taglibs.dbtags.resultset.WasNullTag</tag-class>
<body-content>JSP</body-content>
<description>
Executes its body if the last getColumn tag received a null value
from the database. You must be inside a resultset tag and there must
be a previous getColumn tag, or an error will be generated.
</description>
<availability>1.0</availability>
<restrictions>Must be used following a
getColumn tag.</restrictions>
<example>
<usage>
<code>
<![CDATA[
<%-- open a database query --%>
<table>
<sql:statement id="stmt1" conn="conn1">
<sql:query>
select id, name, description from test_books
order by 1
</sql:query>
<%-- loop through the rows of your query --%>
<sql:resultSet id="rset2">
<tr>
<td><sql:getColumn position="1"/></td>
<td><sql:getColumn position="2"/></td>
<td><sql:getColumn position="3"/>
<sql:wasNull>[no description]</sql:wasNull></td>
</tr>
</sql:resultSet>
</sql:statement>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>wasNotNull</name>
<tag-class>org.apache.taglibs.dbtags.resultset.WasNotNullTag</tag-class>
<body-content>JSP</body-content>
<description>
Executes its body if the last getColumn tag did not encounter a
null value from the database.
</description>
<availability>1.0</availability>
<restrictions>Must be used following a
getColumn tag.</restrictions>
<example>
<usage>
<code>
<![CDATA[
<%-- open a database query --%>
<table>
<sql:statement id="stmt1" conn="conn1">
<sql:query>
select id, name, description from test_books
order by 1
</sql:query>
<%-- loop through the rows of your query --%>
<sql:resultSet id="rset2">
<tr>
<td><sql:getColumn position="1"/></td>
<td><sql:getColumn position="2"/></td>
<td><sql:getColumn position="3" to="description"/>
<sql:wasNotNull>Description: <%= pageContext.getAttribute("description") %></sql:wasNotNull></td>
</tr>
</sql:resultSet>
</sql:statement>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>getColumn</name>
<tag-class>org.apache.taglibs.dbtags.resultset.GetColumnTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.resultset.BaseGetterTEI</tei-class>
<body-content>empty</body-content>
<description>
Gets the value, as a String, of a coulmn in the enclosing
resultset. The column number is set via the "position" attribute.
You can optionally set the value, as a String, to a serlvet attribute
instead of the tag body with the "to" attribute. The scope of the servlet
attribute is specified by the "scope" XML attribute (default = page).
</description>
<availability>1.0</availability>
<restrictions>Use within the resultSet tag</restrictions>
<attribute>
<name>position</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column position
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>colName</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column name
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>to</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally assign the String to an attribute rather
than the JSP output.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>scope</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally change the scope of the attribute designated
in "to" (default = page).
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- output to the JSP directly --%>
<sql:getColumn position="1"/>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>getNumber</name>
<tag-class>org.apache.taglibs.dbtags.resultset.GetNumberTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.resultset.BaseGetterTEI</tei-class>
<body-content>empty</body-content>
<description>
Similar to getColumn, but provides more precise control over
number formatting.
The "format" attribute can be either a pattern as
accepted by the DecimalFormat constructor or a style: "CURRENCY",
"PERCENT" or "NUMBER".
The "locale" attribute can have one to three
components as accepted by the Locale constructor: language,
country and variant. They are separated by "_".
If neither the format nor locale attribute is set, output should be
identical to getColumn.
</description>
<availability>1.0</availability>
<restrictions>Use within the resultSet tag</restrictions>
<attribute>
<name>position</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column position
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>colName</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column name
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>to</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally assign the String to an attribute rather
than the JSP output.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>scope</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally change the scope of the attribute designated
in "to" (default = page).
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>locale</name>
<required>no</required>
<rtexprvalue>yes</rtexprvalue>
<description>
Format according to a particular locale.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>format</name>
<required>no</required>
<rtexprvalue>yes</rtexprvalue>
<description>
Specify a format for the number.
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<%-- format a database value as English currency --%>
<sql:getNumber colName="id" format="CURRENCY" locale="en_GB"/>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>getTime</name>
<tag-class>org.apache.taglibs.dbtags.resultset.GetTimeTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.resultset.BaseGetterTEI</tei-class>
<body-content>empty</body-content>
<description>
Similar to getColumn, but provides more precise control over
java.sql.Time formatting.
The "format" attribute can be either a pattern as
accepted by SimpleDateFormat or a style: "FULL",
"LONG", "MEDIUM" or "SHORT".
The "locale" attribute can have one to three
components as accepted by the Locale constructor: language,
country and variant. They are separated by "_".
If neither the format nor locale attribute is set, output should be
identical to getColumn.
</description>
<availability>1.0</availability>
<restrictions>Use within the resultSet tag</restrictions>
<attribute>
<name>position</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column position
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>colName</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column name
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>to</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally assign the String to an attribute rather
than the JSP output.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>scope</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally change the scope of the attribute designated
in "to" (default = page).
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>locale</name>
<required>no</required>
<rtexprvalue>yes</rtexprvalue>
<description>
Format according to a particular locale.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>format</name>
<required>no</required>
<rtexprvalue>yes</rtexprvalue>
<description>
Specify a format for the time.
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<sql:getTime colName="time"/>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>getTimestamp</name>
<tag-class>org.apache.taglibs.dbtags.resultset.GetTimestampTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.resultset.BaseGetterTEI</tei-class>
<body-content>empty</body-content>
<description>
Similar to getColumn, but provides more precise control over
java.sql.Timestamp formatting.
The "format" attribute can be either a pattern as
accepted by SimpleDateFormat or a style: "FULL",
"LONG", "MEDIUM" or "SHORT".
The "locale" attribute can have one to three
components as accepted by the Locale constructor: language,
country and variant. They are separated by "_".
If neither the format nor locale attribute is set, output should be
identical to getColumn.
</description>
<availability>1.0</availability>
<restrictions>Use within the resultSet tag</restrictions>
<attribute>
<name>position</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column position
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>colName</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column name
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>to</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally assign the String to an attribute rather
than the JSP output.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>scope</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally change the scope of the attribute designated
in "to" (default = page).
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>locale</name>
<required>no</required>
<rtexprvalue>yes</rtexprvalue>
<description>
Format according to a particular locale.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>format</name>
<required>no</required>
<rtexprvalue>yes</rtexprvalue>
<description>
Specify a format for the timestamp.
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<sql:getTimestamp colName="time"/>
]]>
</code>
</usage>
</example>
</tag>
<tag>
<name>getDate</name>
<tag-class>org.apache.taglibs.dbtags.resultset.GetDateTag</tag-class>
<tei-class>org.apache.taglibs.dbtags.resultset.BaseGetterTEI</tei-class>
<body-content>empty</body-content>
<description>
Similar to getColumn, but provides more precise control over
java.sql.Date formatting.
The "format" attribute can be either a pattern as
accepted by SimpleDateFormat or a style: "FULL",
"LONG", "MEDIUM" or "SHORT". It is required.
The "locale" attribute can have one to three
components as accepted by the Locale constructor: language,
country and variant. They are separated by "_".
</description>
<availability>1.0</availability>
<restrictions>Use within the resultSet tag</restrictions>
<attribute>
<name>position</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column position
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>colName</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Column name
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>to</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally assign the String to an attribute rather
than the JSP output.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>scope</name>
<required>no</required>
<rtexprvalue>no</rtexprvalue>
<description>
Optionally change the scope of the attribute designated
in "to" (default = page).
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>locale</name>
<required>no</required>
<rtexprvalue>yes</rtexprvalue>
<description>
Format according to a particular locale.
</description>
<availability>1.0</availability>
</attribute>
<attribute>
<name>format</name>
<required>no</required>
<rtexprvalue>yes</rtexprvalue>
<description>
Specify a format for the date.
</description>
<availability>1.0</availability>
</attribute>
<example>
<usage>
<code>
<![CDATA[
<sql:getDate colName="time" format="FULL"/>
]]>
</code>
</usage>
</example>
</tag>
</tagtoc>
</taglib>
<revision release="Pre Beta" date="08/06/2001">
<description>
Clean up of tag library prior to performing a beta
release, moving toward an official release.
</description>
</revision>
</document>
1.1 jakarta-taglibs/dbtags/xml/description.html
Index: description.html
===================================================================
<span id="description">
<P>The DBTags custom tag library contains tags which can be used to
read from and write to a SQL database.</P>
</span>
1.1 jakarta-taglibs/dbtags/xml/documentation.html
Index: documentation.html
===================================================================
<span id="documentation">
<A NAME="overview.usage"><h2>Simple Usage Example</h2></A>
<P>Here is a JSP page that prints out the names of books in a table:</P>
<pre><%@ taglib uri="http://jakarta.apache.org/taglibs/dbtags" prefix="sql" %>
<%-- open a database connection --%>
<sql:connection id="conn1">
<sql:url>jdbc:mysql://localhost/test</sql:url>
<sql:driver>org.gjt.mm.mysql.Driver</sql:driver>
</sql:connection>
<%-- open a database query --%>
<table>
<sql:statement id="stmt1" conn="conn1">
<sql:query>
select id, name, description from test_books
order by 1
</sql:query>
<%-- loop through the rows of your query --%>
<sql:resultSet id="rset2">
<tr>
<td><sql:getColumn position="1"/></td>
<td><sql:getColumn position="2"/></td>
<td><sql:getColumn position="3"/>
<sql:wasNull>[no description]</sql:wasNull></td>
</tr>
</sql:resultSet>
</sql:statement>
</table>
<%-- close a database connection --%>
<sql:closeConnection conn="conn1"/></pre>
<A NAME="overview.tags"><h2>Tags in Detail</h2></A>
<p>Here are general descriptions of the tags included in the DBTags tag library. Some
details, such as the possible properties of the connection, statement, resultSet, and
preparedStatement tags, are not covered here. An enumeration of all the configurable
aspects of these tags is in the <a href="#reference">Tag Reference</a> section.</p>
<A NAME="overview.tags.connection"><h3>Connection Tags</h3></A>
<P><B>Opening connections</B></P>
<P>There are two ways to open a database connection:</P>
<P><I>1. Use a database URL</I></P>
<P>The connection tag accepts a database URL that can obtain a Connection through
Driver Manager:</P>
<pre><%-- open a database connection --%>
<sql:connection id="conn1">
<%-- required --%>
<sql:url>jdbc:mysql://localhost/test</sql:url>
<%-- optional --%>
<sql:driver>org.gjt.mm.mysql.Driver</sql:driver>
<%-- optional --%>
<sql:userId>root</sql:userId>
<%-- optional --%>
<sql:password>notVerySecure</sql:password>
</sql:connection></pre>
<p>The "id" attribute is required by every "connection" tag. After the end tag,
a java.sql.Connection object will be added as a pageContext attribute, and it can
then be referenced by other tags, including statement, preparedStatement, and
closeConnection.</p>
<P>Instead of including your database URL, driver name, user id, or password
inside your tag body, you may optionally use the "initParameter"
attribute:</P>
<pre><%-- store your connection info in the web.xml file --%>
<sql:connection id="conn1">
<sql:url initParameter="dbURL"/>
<sql:driver initParameter="mysqlDriver"/>
<sql:userId initParameter="dbUserId"/>
<sql:password initParameter="dbPassword"/>
</sql:connection></pre>
<P><I>2. Use a DataSource object</I></P>
<P>The connection tag also accepts a reference to a Servlet attribute containing
a javax.sql.DataSource object. (The attribute is found via the
findAttribute() method of PageContext.):</P>
<pre><%-- open a database connection --%>
<sql:connection id="conn1" dataSource="ds1">
<%-- optional --%>
<sql:userId>root</sql:userId>
<%-- optional --%>
<sql:password>notVerySecure</sql:password>
</sql:connection></pre>
<P><I>3. Use a JNDI named JDBC DataSource</I></P>
<p>The Connection tag also accepts a JNDI named JDBC DataSource.</p>
<pre><%-- open a database connection --%>
<sql:connection id="conn1" jndiName="java:/comp/jdbc/test"/></pre>
<P><B>Closing connections</B></P>
<P>Close a connection by pasing its reference to the "closeConnection" tag:</P>
<pre><%-- unless you're performing your own connection pooling,
always close your connection --%>
<sql:closeConnection conn="conn1"/></pre>
<A NAME="overview.tags.statement"><h3>Statement Tags</h3></A>
<P>"Statements" are one of two ways to submit a query to the database. (The other
method is the "<a href="#overview.tags.preparedstatement">preparedStatement</a>".)
The syntax of a statement-based query should be familiar to anyone with
knowledge of SQL. In order to query the database, open a "statement" tag, pass
it an sql "query", and then either "execute" the statement for inserts, updates, and
deletes, or call the <a href="#overview.tags.resultset">resultSet</a> tag to
iterate over a select statement. Here is a sample insert using the statement
tag:</P>
<pre><%-- insert a row into the database --%>
<sql:statement id="stmt1" conn="conn1">
<%-- set the SQL query --%>
<sql:query>
insert into test_books (id, name)
values (3, '<sql:escapeSql><%=request.getParameter("book_title")%></sql:escapeSql>')
</sql:query>
<%-- execute the query --%>
<sql:execute/>
</sql:statement></pre>
<p><b>escaping SQL</b></p>
<p>The "escapeSql" tag can be used inside a SQL query
to SQL-escape your input values if they contain single quotes.</p>
<p><b>error handling</b></p>
<p>By default, errors caused by the execution of the SQL query (e.g. primary key
violations, malformed SQL statements) will cause the JSP page to fail. You may
optionally set the "ignoreErrors" attribute of the "execute" tag to true, which
will print the SQL error to standard out without terminating the page:</p>
<pre><sql:statement id="stmt1" conn="conn1">
<%-- this SQL query is malformed --%>
<sql:query>delete * from test_books</sql:query>
<%-- the query will fail, but the page will continue --%>
<sql:execute ignoreErrors="true"/>
</sql:statement></pre>
<p><b>whitespace handling</b></p>
<p>All statements and preparedStatements automatically trim whitespace from the
body.</p>
<p><b>"wasEmpty" and "wasNotEmpty" tags</b></p>
<p>The "wasEmpty" tag only executes its body if the last ResultSet
tag received 0 rows from the database. You must be after a ResultSet tag and
inside a StatementTag or PreparedStatementTag, or an error will be generated.
The "wasNotEmpty" tag executes its body if the last ResultSet
received <i>more than</i> 0 rows from the database.
See the <A HREF="#summary">Tag Reference</A> for examples.</p>
<p><b>"rowCount" tag</b></p>
<p>The "rowCount" tag prints out the number of rows retrieved from the database.
It can be used inside a ResultSet tag to provide a running
count of rows retreived, or after the ResultSet tag to
display the total number. See the <A HREF="#summary">Tag Reference</A> for examples.
Using the tag before the ResultSet
or outside of a Statement or PreparedStatement will
produce an error.</p>
<A NAME="overview.tags.preparedstatement"><h3>PreparedStatement Tags</h3></A>
<P>"Prepared statements" are a somewhat more advanced format for generating SQL
queries. Instead of inserting values directly into the SQL statement, you
include the '?' symbol in places where you want to set a value, and then you use
a separate group of tags to actually set the value. Here is a version
of the query we used in the <a href="#overview.tags.statement">statement</a>
section, but this version uses the preparedstatement tag and syntax instead:</P>
<pre><%-- insert a row into the database --%>
<sql:preparedStatement id="stmt1" conn="conn1">
<%-- set the SQL query. note the lack of quotes around the "name" value --%>
<sql:query>
insert into test_books (id, name)
values (?, ?)
</sql:query>
<sql:execute>
<sql:setColumn position="1">3</sql:setColumn>
<sql:setColumn position="2"><%=request.getParameter("book_title")%></sql:setColumn>
</sql:execute>
</sql:preparedStatement></pre>
<p>One advantage of prepared statements is that you do not need to perform sql escaping on
text, as you have to do in a standard statement. However,
be aware that standard statements may be more performant for databases and drivers that
do not peform pooling of connections <i>and</i> prepared statements.</p>
<p><b>setColumn tag</b></p>
<p>You can put the setColumn tags of prepared statements either before the execute or
resultset tag, or inside the execute tag. The execute tag never outputs its body
so putting setColumn tags inside may prevent unnecessary whitespace.</p>
<A NAME="overview.tags.resultset"><h3>ResultSet Tags</h3></A>
<p>Result sets are the product of a select statement. The resultSet tag
automatically loops, once per row, through a result set. Use the "getColumn"
tag to grab values from each row and either display them or store them away
as a String:</p>
<pre><%-- print the rows in an HTML table --%>
<table>
<sql:statement id="stmt1" conn="conn1">
<sql:query>
select id, name, description from test_books
order by 1
</sql:query>
<%-- loop through the rows of your query --%>
<sql:resultSet id="rset2">
<tr>
<td><sql:getColumn position="1"/></td>
<td><sql:getColumn position="2"/></td>
<td><sql:getColumn position="3"/>
<%-- print out a comment if the book has no description --%>
<sql:wasNull>[no description]</sql:wasNull></td>
</tr>
</sql:resultSet>
</sql:statement>
</table></pre>
<p><b>"wasNull" and "wasNotNull" tags</b></p>
<p>The "wasNull" tag only executes its body if the previous "getColumn" tag encountered a
null value in the database. You can only use the "wasNull" tag if you are
inside a resultset and if a "getColumn" tag has already been executed. The
"wasNotNull" tag
executes its body if the previous getColumn tag did <i>not</i> produce a null.
See the <A HREF="#summary">Tag Reference</A> for examples.</p>
<p><b>"getColumn" tag</b></p>
<p>The getColumn tag performs one of two functions. You may either:</p>
<ol>
<li><p>Write the column value directly to the JSP (default behavior)</p>
<pre><%-- Print the value to the JSP output --%>
<sql:getColumn position="1"/></pre>
<p>, or</p></li>
<li><p>Write the column value, as a String, to a page attribute via the "to"
attribute. If you want, you may optionally assign a scope other
than "page" with the "scope" attribute. If the database column is null, the
getColumn tag <i>will not</i> create an attribute. Here's a getColumn tag that
creates an Integer request attribute:</p>
<pre><%-- Note that the request attribute will be a String --%>
<sql:getColumn position="1" to="someId" scope="request"/></pre>
</li>
</ol>
<p><b>"getNumber" tag</b></p>
<p>When you want more precise control over number formatting, use
the getNumber tag.</p>
<p>The "format" attribute can be either a pattern as
accepted by the DecimalFormat constructor or a style: "CURRENCY",
"PERCENT" or "NUMBER".</p>
<p>The "locale" attribute can have one to three
components as accepted by the Locale constructor: language,
country and variant. They are separated by "_". For example:</p>
<p><pre><%-- format a database value as English currency --%>
<sql:getNumber colName="id" format="CURRENCY" locale="en_GB"/></pre></p>
If neither the format nor locale attribute is set, output should be
identical to getColumn.
<p><b>time tags</b></p>
<p>There are several tags designed for displaying time-related
data: getTime, getTimestamp and getDate.</p>
<p>The "format" attribute can be either a pattern as
accepted by SimpleDateFormat or a style: "FULL",
"LONG", "MEDIUM" or "SHORT". This attribute is optional.</p>
<p>The "locale" attribute can have one to three
components as accepted by the Locale constructor: language,
country and variant. They are separated by "_".</p>
<p><b>disabling looping</b></p>
<p>By default, the body of the result set tag is executed once per row in the
ResultSet. By setting the option "loop" attribute to false, however, you may
disable this feature and manipulate the ResultSet object manually, or pass it
off to another custom tag.</p>
<pre><sql:statement id="stmt1" conn="conn1">
<sql:query>
select id, name, description from test_books
order by 1
</sql:query>
<%-- disable looping in resultset tag --%>
<sql:resultSet id="rset2" loop="false">
<%
ResultSet rset = (ResultSet) pageContext.getAttribute("rset2");
// manual result set manipulation here
%>
</sql:resultSet>
</sql:statement></pre>
</span>
1.1 jakarta-taglibs/dbtags/xml/requirements.html
Index: requirements.html
===================================================================
<span id="requirements-info">
<p><i>JSP requirements</i></p>
<P>This custom tag library requires a servlet container
that supports the JavaServer Pages Specification, version 1.2.</P>
<P>The tag library also works in some JSP version 1.1 servlet containers,
such as Tomcat, but not in others, such as Weblogic. The tags in this tag
library are designed according to the JSP 1.2 specification, which makes
this requirement of the <jsp:getProperty ... /> tag:</P>
<DL><DD>
The value of the name attribute in jsp:setProperty and jsp:getProperty
will refer to an object that is obtained from the pageContext object
through its findAttribute() method.
</DD></DL>
<P>The JSP 1.1 specification does not require this behaviour, and while
Tomcat happens to support it, Weblogic does not. Note that it is fairly
straightforward to write a custom tag that emulates this behaviour for
Weblogic users. Sample source code for such a tag can be
found <a href="GetPropertyTag.java">here</a>.</P>
<p><i>DBTags requirements</i></p>
<p>The DBTags tag library supports the use of DataSource objects, which are
not part of the Java 2 Standard Edition. In order to use DataSources,
either use Java 2 Enterprise Edition, or download the Optional API for
JDBC 2.0.</p>
</span>