Author: steveh
Date: Sat Nov 13 14:20:23 2004
New Revision: 65516
Modified:
incubator/beehive/site/build/site/controls/sample_controls-db.html
incubator/beehive/site/build/site/index.html
incubator/beehive/site/build/site/reference.html
incubator/beehive/site/build/site/wsm/sample_AddressBook.html
incubator/beehive/site/src/documentation/content/xdocs/controls/sample_controls-db.xml
incubator/beehive/site/src/documentation/content/xdocs/wsm/sample_AddressBook.xml
Log:
Control docs contribution for Hoi Lam.
Also highlighting relationship between EmployeeWS and Database Control samples.
Modified: incubator/beehive/site/build/site/controls/sample_controls-db.html
==============================================================================
--- incubator/beehive/site/build/site/controls/sample_controls-db.html
(original)
+++ incubator/beehive/site/build/site/controls/sample_controls-db.html Sat Nov
13 14:20:23 2004
@@ -289,49 +289,32 @@
<ul class="minitoc">
<li>
<a href="#Control+Programming%3A+Simplifying+Access+to+Resources">Control
Programming: Simplifying Access to Resources</a>
-<ul class="minitoc">
-<li>
-<a href="#Structure+of+the+Database+Control">Structure of the Database
Control</a>
</li>
-</ul>
+<li>
+<a href="#Building+the+Database+Control">Building the Database Control</a>
</li>
</ul>
<a name="N1000C"></a><a
name="Control+Programming%3A+Simplifying+Access+to+Resources"></a>
<h3>Control Programming: Simplifying Access to Resources</h3>
<div style="margin-left: 0 ; border: 2px">
-<p>Control Programming...simplifying access to a resource, in this case a
database.
-
- <!-- From Hoi Lam's email:
- A Database control makes it easy to access a relational database from
your Java code using SQL commands. The Database control handles the work of
connecting to the database, so you don’t have to understand JDBC to work with
a database.
-
-All Database controls are subclassed from the DatabaseControl interface. The
interface defines methods that Database control instances can call from an
application.
-
-The methods that you add to a Database control execute SQL commands against
the database. You can send any SQL command to the database via the Database
control, so that you can retrieve data, perform operations like inserts and
updates.
-
-A method on a Database control always has an associated SQL statement, which
executes against the database when the method is called. The method’s @SQL
annotation describes the method’s SQL statement. The method’s SQL
statement may include substitution parameters. These parameters are replaced at
runtime with the values that were passed to the method. The names of the
substitution parameters in the SQL statement must match those in the method
signature, so that the Database control knows which parameter to replace with
which value.
-
-The following example Database control method illustrates using parameter
substitution in Database control methods:
-
- @SQL(statement="INSERT INTO EMPLOYEE " +
+<p>A Database control makes it easy to access a relational database from your
Java code using SQL commands. The Database control handles the work of
connecting to the database, so you don’t have to understand JDBC to work
with a database.</p>
+<p>All Database controls are subclassed from the DatabaseControl interface.
The interface defines methods that Database control instances can call from an
application.</p>
+<p>The methods in the Database control execute SQL commands against the
database. You can send any SQL command to the database via the Database
control, so that you can retrieve data and perform operations like inserts and
updates.</p>
+<p>A method on a Database control always has an associated SQL statement,
which executes against the database when the method is called. The
method’s @SQL annotation describes the method’s SQL statement. The
method’s SQL statement may include substitution parameters. These
parameters are replaced at runtime with the values that were passed to the
method. The names of the substitution parameters in the SQL statement must
match those in the method signature, so that the Database control knows which
parameter to replace with which value.</p>
+<p>The following example Database control method illustrates using parameter
substitution in Database control methods:</p>
+<pre class="code"> @SQL(statement="INSERT INTO EMPLOYEE " +
"(id, fName, lName, title) " +
"VALUES ({emp.id}, {emp.fName}, {emp.lName}, {emp.title})")
- public void insertEmployee(Employee emp) throws SQLException;
-
-In the example above, the SQL statement includes the substitution {emp.id},
{emp.fName}, ... These map to the various class variables of the "emp"
parameter in the insertEmployee method. When the method is invoked, the values
of any referenced parameters are substituted in the SQL statement before it is
executed. Note that parameter substitution is case sensitive, so parameters
mentioned in substitutions must exactly match the spelling and case of the
parameters to the method.
-
-The return type of the database operation is determined by the return type of
the Java method. The Database control attempts to format the results in
whatever type you have specified for the method to return. A method of a
Database control can return a single value, a single row, or multiple rows.
-
-When your method returns a single value, its return type must be compatible
with the value returned from the query. The following example looks up an
employee's title.
-
- @SQL(statement="SELECT title FROM EMPLOYEE WHERE id={id}")
- public String getEmployeeTitle(int id) throws SQLException;
-
-In this example, the title field is of type VARCHAR, so the return value is
declared as String.
-
-When your method returns a single row with multiple fields, its return type
can be a user-defined object or a java.util.HashMap object. When the return
type is a user-defined object, it must contain members with names that match
the names of the columns that will be returned by the query. Because database
column names are case-insensitive, the matching names are case-insensitive. The
class may also contain other members, members not matching any column names
will not be set. The following example declares an Employee class with members
corresponding to fields in the Employee table. The findEmployee method returns
an object of type Employee:
-
- @SQL(statement="SELECT * FROM EMPLOYEE WHERE id={id}")
+ public void insertEmployee(Employee emp) throws SQLException;</pre>
+<p>In the example above, the SQL statement includes the substitution {emp.id},
{emp.fName}, ... These map to the various class variables of the "emp"
parameter in the insertEmployee method. When the method is invoked, the values
of any referenced parameters are substituted in the SQL statement before it is
executed. Note that parameter substitution is case sensitive, so parameters
mentioned in substitutions must exactly match the spelling and case of the
parameters to the method.</p>
+<p>The return type of the database operation is determined by the return type
of the Java method. The Database control attempts to format the results in
whatever type you have specified for the method to return. A method of a
Database control can return a single value, a single row, or multiple rows. </p>
+<p>When your method returns a single value, its return type must be compatible
with the value returned from the query. The following example looks up an
employee's title.</p>
+<pre class="code"> @SQL(statement="SELECT title FROM EMPLOYEE WHERE
id={id}")
+ public String getEmployeeTitle(int id) throws SQLException;</pre>
+<p>In this example, the title field is of type VARCHAR, so the return value is
declared as String. </p>
+<p>When your method returns a single row with multiple fields, its return type
can be a user-defined object or a java.util.HashMap object. When the return
type is a user-defined object, it must contain members with names that match
the names of the columns that will be returned by the query. Because database
column names are case-insensitive, the matching names are case-insensitive. The
class may also contain other members, members not matching any column names
will not be set. The following example declares an Employee class with members
corresponding to fields in the Employee table. The findEmployee method returns
an object of type Employee:</p>
+<pre class="code"> @SQL(statement="SELECT * FROM EMPLOYEE WHERE id={id}")
public Employee findEmployee(int id) throws SQLException;
public class Employee
@@ -340,82 +323,52 @@
public String fName;
public String lName;
public String title;
- }
-
-When your method returns multiple rows from the database, its return type can
be an array, a java.util.Iterator, or a java.sql.ResultSet.
-When you want to return an Iterator object, you must specify the
iteratorElementType element to the @SQL annotation to indicate the underlying
type that the Iterator will contain. The following example returns a iterator
of all employees sorted by their last names.
-
- @SQL(statement="SELECT * FROM EMPLOYEE ORDER BY lName",
iteratorElementType=Employee.class, maxRows=500)
- public Iterator getEmployeesSortedByLastName() throws SQLException;
-
-You can limit the number of rows returned by setting the maxRows element of
the @SQL annotation. This element can protect you from very large resultsets
that may be returned by very general queries. The default value of maxRow is
1024.
-
-The Database Control defines two annotations: SQL and ConnectionDataSource.
-
-The SQL Annotation specifies the SQL statement and associated attributes that
correspond to a method in a Database control.
-
- public @interface SQL
+ }</pre>
+<p>When your method returns multiple rows from the database, its return type
can be an array, a java.util.Iterator, or a java.sql.ResultSet. </p>
+<p>When you want to return an Iterator object, you must specify the
iteratorElementType element to the @SQL annotation to indicate the underlying
type that the Iterator will contain. The following example returns a iterator
of all employees sorted by their last names.</p>
+<pre class="code"> @SQL(statement="SELECT * FROM EMPLOYEE ORDER BY lName",
iteratorElementType=Employee.class, maxRows=500)
+ public Iterator getEmployeesSortedByLastName() throws SQLException;</pre>
+<p>You can limit the number of rows returned by setting the maxRows element of
the @SQL annotation. This element can protect you from very large resultsets
that may be returned by very general queries. The default value of maxRow is
1024.</p>
+<p>The Database Control defines two annotations: SQL and
ConnectionDataSource.</p>
+<p>The SQL Annotation specifies the SQL statement and associated attributes
that correspond to a method in a Database control.</p>
+<pre class="code"> public @interface SQL
{
String statement() default "";
int maxRows() default MAXROWS_ALL;
@AnnotationMemberTypes.Optional
Class iteratorElementType() default UndefinedIteratorType.class;
- }
-
-The "statement" element is required. It specifies the SQL (Structured Query
Language) statement that will be executed when the associated Database control
method is invoked. The statement may contain substitutions of the form
{varName}, where paramName is a parameter of the Database control method (or a
member accessible from the parameter).
-
-The "iteratorElementType" is required if Database control method return type
is java.util.Iterator. It specifies the underlying class of the Iterator that
will be returned by the Database control method.
-
-The "maxRows" element is optional. It sets the maximum number of records to be
returned by the query. The maxRows element limits the size of all types of data
sets, including Arrays, Iterator, ResultSet, etc. The default value of this
element is 1024.
-
-The ConnectionDataSource annotation specifies the data source that the
Database control will use to obtain connection. At the time of writing, this
has not been fully implemented yet. The Database control currently uses the
embedded Derby database driver to obtain connection, and it is expecting the
value provided for the "jndiName" element to be a database URL.
-
- public @interface ConnectionDataSource
+ }</pre>
+<p>The "statement" element is required. It specifies the SQL (Structured Query
Language) statement that will be executed when the associated Database control
method is invoked. The statement may contain substitutions of the form
{varName}, where paramName is a parameter of the Database control method (or a
member accessible from the parameter).</p>
+<p>The "iteratorElementType" is required if Database control method return
type is java.util.Iterator. It specifies the underlying class of the Iterator
that will be returned by the Database control method. </p>
+<p>The "maxRows" element is optional. It sets the maximum number of records to
be returned by the query. The maxRows element limits the size of all types of
data sets, including Arrays, Iterator, ResultSet, etc. The default value of
this element is 1024.</p>
+<p>The ConnectionDataSource annotation specifies the data source that the
Database control will use to obtain connection. At the time of writing, this
has not been fully implemented yet. The Database control currently uses the
embedded Derby database driver to obtain connection, and it is expecting the
value provided for the "jndiName" element to be a database URL.</p>
+<pre class="code"> public @interface ConnectionDataSource
{
String jndiName(); // no default ... value is required
- }
-
-The Database control is current included in the Beehive distribution as a
sample control (\samples\controls-db). Building this control with the Ant
script provided will create a dbControl.jar in \samples\controls-db\build\.
You can start creating your own database control extension by simply including
this JAR file in your classpath.
-
-
- -->
-
- </p>
-<a name="N10017"></a><a name="Structure+of+the+Database+Control"></a>
-<h4>Structure of the Database Control</h4>
-<div style="margin-left: 0 ; border: 2px"></div>
-<p>The Database Control is a <em>base control</em>: it is designed to be
extented by a <em>control extension</em>. Base controls package the
boilerplate code, the common routines that any code must execute in order to
access a resource. Control extensions contain the interesting, variable
aspects of accessing the resource. If this model were applied to the case of
JMS access, the base control would contain the boilerplate tasks consisting of
obtaining sessions, referencing queues, etc. The control extension configures
the base control for access to a particular JMS resource. The control
extension would anwser the questions: What the JNDI name of the JMS resources?
What message should be sent?
-</p>
-<p>
-In the case of a database resource, The boilerplate parts of the code are
tasks such as making a JDBC connection with the database and handling the
resultsets, tasks specified in the base control. An extension of the base
database control configures the base control by setting the JNDI name the
target database, the SQL statements used to communicate with the database, the
maximum size of resultsets that the control will accept, etc.
-</p>
-<p>
-Not all base controls need to extended to be used: they can be designed to be
used directly by the client, without an control extension intermediary. But in
the case of the database Database Control is designed in order to be extended
by another class, which answers all of the parameter questions: the interesting
parts of accessing the particular resource, whatever it is. An example of a
control extention off of the base Database Control is EmployeeDBControl.jcx
(located at
BEEHIVE_HOME/samples/EmployeeWS/WEB-INF/src/org/apache/beehive/sample). The
fragment below shows how the control extension configures the base control for
a JDBC connection to a particular Derby database.
- </p>
-<p>
-<strong>EmployeeDBControl.jcx</strong>
-</p>
-<pre class="code">@ControlExtension
[EMAIL PROTECTED](jndiName="jdbc:derby:build/databaseControlTestDB;create=true")
-public interface EmployeeDBControl extends DatabaseControl
+ }</pre>
+<p>The Database control is current included in the Beehive distribution as a
sample control (\samples\controls-db). Building this control with the Ant
script provided will create a <span class="codefrag">dbControl.jar</span> in
\samples\controls-db\build\. You can start creating your own database control
extension by simply including this JAR file in your classpath.</p>
+<p>Notice that the sample <a
href="../wsm/sample_AddressBook.html">EmployeeWS</a> uses this same technique
(subclassing DatabaseControl) for database access. The EmployeeWS sample is a
database control exposed as a web service. The exposed database control,
EmployeeDBControl, is a subclass of DatabaseControl (archived in <span
class="codefrag">dbControl.jar</span>).</p>
+<pre class="code">public interface EmployeeDBControl extends DatabaseControl
{
...
}
</pre>
-<ul>
-
-<li>Metadata annotations: reduces configuring the control for resource access
to a matter of setting properties throught annotations. To a client, the
control appears as a JavaBean that is instantiated and operated upon for
resource access. Base controls configure the container using annotations.
Control extensions configure the base.</li>
-<!-- <li>events (<link
href="http://incubator.apache.org/beehive/ControlsOverview.html#Operations";>http://incubator.apache.org/beehive/ControlsOverview.html#Operations</link>)</li>
- <li>resource management (<link
href="http://incubator.apache.org/beehive/ControlsOverview.html#Resource%20Management";>http://incubator.apache.org/beehive/ControlsOverview.html#Resource%20Management</link>)....
[todo]</li>
--->
-
-</ul>
</div>
-<!-- <section>
- <title>Distributing the Database Control</title>
- <p>[todo]</p>
- </section>-->
-
+
+
+<a name="N10083"></a><a name="Building+the+Database+Control"></a>
+<h3>Building the Database Control</h3>
+<div style="margin-left: 0 ; border: 2px">
+<p>To build <span class="codefrag">dbControl.jar</span> run the following Ant
command:</p>
+<p>On Windows:</p>
+<p>
+<span class="codefrag">ant -f %BEEHIVE_HOME%\samples\controls-db\build.xml
build</span>.</p>
+<p>On Unix:</p>
+<p>
+<span class="codefrag">ant -f $BEEHIVE_HOME\samples\controls-db\build.xml
build</span>.</p>
+<p>This produces the file <span class="codefrag">dbControl.jar</span> in the
directory <span
class="codefrag">BEEHIVE_HOME/samples/controls-db/build</span>.</p>
+<p></p>
+</div>
<div class="attribution"></div>
</div>
</td><td width="10"><img width="10" height="1" alt=""
src="../skin/images/spacer.gif" class="spacer"></td>
Modified: incubator/beehive/site/build/site/index.html
==============================================================================
--- incubator/beehive/site/build/site/index.html (original)
+++ incubator/beehive/site/build/site/index.html Sat Nov 13 14:20:23 2004
@@ -303,20 +303,20 @@
<a href="#Get+Involved">Get Involved</a>
</li>
</ul>
- <!--
- Beehive
- Welcome<should link to the HTML page created from Welcome.doc>
- License<should link to http://www.apache.org/licenses/LICENSE-2.0>
-
- Documentation
- FAQ<should link to the HTML page created from FAQ.doc>
- Controls Overview<should link to Kyle's control Overview>
- Controls Programming<should link to Kyle's Controls programming pdf>
- Web Services (JSR 181)<should link to
http://jcp.org/en/jsr/detail?id=181>
-
- Contributing
- Mailing Lists<should link to HTML Page created from MailingLists.doc>
- Contributers<should link to HTML Page created from Contributers.doc>
+ <!--
+ Beehive
+ Welcome<should link to the HTML page created from Welcome.doc>
+ License<should link to http://www.apache.org/licenses/LICENSE-2.0>
+
+ Documentation
+ FAQ<should link to the HTML page created from FAQ.doc>
+ Controls Overview<should link to Kyle's control Overview>
+ Controls Programming<should link to Kyle's Controls programming pdf>
+ Web Services (JSR 181)<should link to
http://jcp.org/en/jsr/detail?id=181>
+
+ Contributing
+ Mailing Lists<should link to HTML Page created from MailingLists.doc>
+ Contributers<should link to HTML Page created from Contributers.doc>
-->
Modified: incubator/beehive/site/build/site/reference.html
==============================================================================
--- incubator/beehive/site/build/site/reference.html (original)
+++ incubator/beehive/site/build/site/reference.html Sat Nov 13 14:20:23 2004
@@ -300,8 +300,8 @@
<a target="_blank" href="reference/classref_pageflows/index.html">Page Flow
API Reference</a>
</li>
- <!--<li>
- <fork
href="pageflow/config/netui-config.html">Configuration: netui-config.xml</fork>
+ <!--<li>
+ <fork
href="pageflow/config/netui-config.html">Configuration: netui-config.xml</fork>
</li>-->
<li>
Modified: incubator/beehive/site/build/site/wsm/sample_AddressBook.html
==============================================================================
--- incubator/beehive/site/build/site/wsm/sample_AddressBook.html
(original)
+++ incubator/beehive/site/build/site/wsm/sample_AddressBook.html Sat Nov
13 14:20:23 2004
@@ -314,13 +314,14 @@
<div style="margin-left: 0 ; border: 2px">
<p>The <strong>AddressBookWS</strong> sample is an annotation-aware web
service based on the Apache Axis sample of the same name. AddressBookWS is
organized as an application with POJO (Plain Old Java Objects) models, service
interface, service implementation, and unit tests for the service. Apache Axis
provides automatic client-generation and junit test cases for the sample. The
directory structure and ant build file can be used as a template for building
new standalone web services.</p>
<p>
-<strong>EmployeeWS</strong> provides a web service interface for an Employee
database. Using SOAP messages, the web service queries the backend database:
selecting, updating and inserting employee data. A Beehive database control
connects the web service and the database. The web service class is located at
<span class="codefrag">EmployeeWS/WEB-INF/src/web/Service.jws</span>. The
database control is located at <span
class="codefrag">EmployeeWS/WEB-INF/src/org/apache/beehive/sample/EmployeeDBControl.jcx</span>.
Apache Derby supplies the database implementation. (Installing Derby
requires a simple JAR file download, described below.) Apache Axis provides
the automatic client-generation for the web service. Custom unit tests are
provided to exercise the webservice methods. The unit tests creates the
database table, inserts a new record, queries the database, and finally drops
the table. Use the junit tests as a template for building automatic tests for
your own controls.</p>
+<strong>EmployeeWS</strong> provides a web service interface for an Employee
database. Using SOAP messages, the web service queries the backend database:
selecting, updating and inserting employee data. A Beehive database control
connects the web service and the database. The web service class is located at
<span class="codefrag">EmployeeWS/WEB-INF/src/web/Service.jws</span>. The
database control is located at <span
class="codefrag">EmployeeWS/WEB-INF/src/org/apache/beehive/sample/EmployeeDBControl.jcx</span>.
Note that EmployeeDBControl is a subclass of DatabaseControl, another Beehive
sample. For more information see <a
href="../controls/sample_controls-db.html">Database Control</a>. </p>
+<p>Apache Derby supplies the database implementation. (Installing Derby
requires a simple JAR file download, described below.) Apache Axis provides
the automatic client-generation for the web service. Custom unit tests are
provided to exercise the webservice methods. The unit tests creates the
database table, inserts a new record, queries the database, and finally drops
the table. Use the junit tests as a template for building automatic tests for
your own controls.</p>
</div>
-<a name="N10024"></a><a name="Running+the+Samples"></a>
+<a name="N1002B"></a><a name="Running+the+Samples"></a>
<h3>Running the Samples</h3>
<div style="margin-left: 0 ; border: 2px">
-<a name="N1002A"></a><a name="Requirements+for+Running+the+Sample"></a>
+<a name="N10031"></a><a name="Requirements+for+Running+the+Sample"></a>
<h4>Requirements for Running the Sample</h4>
<div style="margin-left: 0 ; border: 2px">
<p>To run the Samples, you need:</p>
@@ -340,7 +341,7 @@
</ul>
</div>
-<a name="N10049"></a><a name="Setting+up+the+Environment"></a>
+<a name="N10050"></a><a name="Setting+up+the+Environment"></a>
<h4>Setting up the Environment</h4>
<div style="margin-left: 0 ; border: 2px">
<p>Download a Beehive distribution archive (<a target="_blank"
href="http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/";>http://cvs.apache.org/dist/incubator/beehive/v1.0-alpha/bin/</a>),
and explode it on your local machine. In the instructions below, the top
level directory of the exploded Beehive archive is called '<span
class="codefrag"><dist-dir></span>'. For example if you explode the
archive into </p>
@@ -368,7 +369,7 @@
<p> Copy <span class="codefrag">junit.jar</span> to <span
class="codefrag">ANT_HOME/lib</span>.</p>
<p> Download derby_46005.jar from <a
href="http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP";>http://incubator.apache.org/derby/binaries/derby_snapshot_svnversion_46005.ZIP</a>.</p>
<p> Copy <span class="codefrag">derby_46005.jar</span> to <span
class="codefrag">BEEHIVE_HOME/samples/EmployeeWS/WEB-INF/lib</span>.</p>
-<a name="N100A3"></a><a name="Setting+up+the+Server"></a>
+<a name="N100AA"></a><a name="Setting+up+the+Server"></a>
<h4>Setting up the Server</h4>
<div style="margin-left: 0 ; border: 2px">
<p>
@@ -413,7 +414,7 @@
<a href="http://localhost:8080/EmployeeWS/web/Service.jws?wsdl";>
http://localhost:8080/EmployeeWS/web/Service.jws?wsdl</a>
</p>
</div>
-<a name="N100F7"></a><a name="Setting+up+the+Clients"></a>
+<a name="N100FE"></a><a name="Setting+up+the+Clients"></a>
<h4>Setting up the Clients</h4>
<div style="margin-left: 0 ; border: 2px">
<p>To generate the clients run the following build files.</p>
Modified:
incubator/beehive/site/src/documentation/content/xdocs/controls/sample_controls-db.xml
==============================================================================
---
incubator/beehive/site/src/documentation/content/xdocs/controls/sample_controls-db.xml
(original)
+++
incubator/beehive/site/src/documentation/content/xdocs/controls/sample_controls-db.xml
Sat Nov 13 14:20:23 2004
@@ -7,38 +7,36 @@
<body>
<section>
<title>Control Programming: Simplifying Access to Resources</title>
- <p>Control Programming...simplifying access to a resource, in this
case a database.
- <!-- From Hoi Lam's email:
- A Database control makes it easy to access a relational database from
your Java code using SQL commands. The Database control handles the work of
connecting to the database, so you don’t have to understand JDBC to work with
a database.
+ <p>A Database control makes it easy to access a relational database
from your Java code using SQL commands. The Database control handles the work
of connecting to the database, so you don’t have to understand JDBC to work
with a database.</p>
-All Database controls are subclassed from the DatabaseControl interface. The
interface defines methods that Database control instances can call from an
application.
+<p>All Database controls are subclassed from the DatabaseControl interface.
The interface defines methods that Database control instances can call from an
application.</p>
-The methods that you add to a Database control execute SQL commands against
the database. You can send any SQL command to the database via the Database
control, so that you can retrieve data, perform operations like inserts and
updates.
+<p>The methods in the Database control execute SQL commands against the
database. You can send any SQL command to the database via the Database
control, so that you can retrieve data and perform operations like inserts and
updates.</p>
-A method on a Database control always has an associated SQL statement, which
executes against the database when the method is called. The method’s @SQL
annotation describes the method’s SQL statement. The method’s SQL
statement may include substitution parameters. These parameters are replaced at
runtime with the values that were passed to the method. The names of the
substitution parameters in the SQL statement must match those in the method
signature, so that the Database control knows which parameter to replace with
which value.
+<p>A method on a Database control always has an associated SQL statement,
which executes against the database when the method is called. The method’s
@SQL annotation describes the method’s SQL statement. The method’s SQL
statement may include substitution parameters. These parameters are replaced at
runtime with the values that were passed to the method. The names of the
substitution parameters in the SQL statement must match those in the method
signature, so that the Database control knows which parameter to replace with
which value.</p>
-The following example Database control method illustrates using parameter
substitution in Database control methods:
+<p>The following example Database control method illustrates using parameter
substitution in Database control methods:</p>
- @SQL(statement="INSERT INTO EMPLOYEE " +
+<source> @SQL(statement="INSERT INTO EMPLOYEE " +
"(id, fName, lName, title) " +
"VALUES ({emp.id}, {emp.fName}, {emp.lName}, {emp.title})")
- public void insertEmployee(Employee emp) throws SQLException;
+ public void insertEmployee(Employee emp) throws SQLException;</source>
-In the example above, the SQL statement includes the substitution {emp.id},
{emp.fName}, ... These map to the various class variables of the "emp"
parameter in the insertEmployee method. When the method is invoked, the values
of any referenced parameters are substituted in the SQL statement before it is
executed. Note that parameter substitution is case sensitive, so parameters
mentioned in substitutions must exactly match the spelling and case of the
parameters to the method.
+<p>In the example above, the SQL statement includes the substitution {emp.id},
{emp.fName}, ... These map to the various class variables of the "emp"
parameter in the insertEmployee method. When the method is invoked, the values
of any referenced parameters are substituted in the SQL statement before it is
executed. Note that parameter substitution is case sensitive, so parameters
mentioned in substitutions must exactly match the spelling and case of the
parameters to the method.</p>
-The return type of the database operation is determined by the return type of
the Java method. The Database control attempts to format the results in
whatever type you have specified for the method to return. A method of a
Database control can return a single value, a single row, or multiple rows.
+<p>The return type of the database operation is determined by the return type
of the Java method. The Database control attempts to format the results in
whatever type you have specified for the method to return. A method of a
Database control can return a single value, a single row, or multiple rows. </p>
-When your method returns a single value, its return type must be compatible
with the value returned from the query. The following example looks up an
employee's title.
+<p>When your method returns a single value, its return type must be compatible
with the value returned from the query. The following example looks up an
employee's title.</p>
- @SQL(statement="SELECT title FROM EMPLOYEE WHERE id={id}")
- public String getEmployeeTitle(int id) throws SQLException;
+<source> @SQL(statement="SELECT title FROM EMPLOYEE WHERE id={id}")
+ public String getEmployeeTitle(int id) throws SQLException;</source>
+
+<p>In this example, the title field is of type VARCHAR, so the return value is
declared as String. </p>
-In this example, the title field is of type VARCHAR, so the return value is
declared as String.
+<p>When your method returns a single row with multiple fields, its return type
can be a user-defined object or a java.util.HashMap object. When the return
type is a user-defined object, it must contain members with names that match
the names of the columns that will be returned by the query. Because database
column names are case-insensitive, the matching names are case-insensitive. The
class may also contain other members, members not matching any column names
will not be set. The following example declares an Employee class with members
corresponding to fields in the Employee table. The findEmployee method returns
an object of type Employee:</p>
-When your method returns a single row with multiple fields, its return type
can be a user-defined object or a java.util.HashMap object. When the return
type is a user-defined object, it must contain members with names that match
the names of the columns that will be returned by the query. Because database
column names are case-insensitive, the matching names are case-insensitive. The
class may also contain other members, members not matching any column names
will not be set. The following example declares an Employee class with members
corresponding to fields in the Employee table. The findEmployee method returns
an object of type Employee:
-
- @SQL(statement="SELECT * FROM EMPLOYEE WHERE id={id}")
+<source> @SQL(statement="SELECT * FROM EMPLOYEE WHERE id={id}")
public Employee findEmployee(int id) throws SQLException;
public class Employee
@@ -47,47 +45,52 @@
public String fName;
public String lName;
public String title;
- }
+ }</source>
-When your method returns multiple rows from the database, its return type can
be an array, a java.util.Iterator, or a java.sql.ResultSet.
-When you want to return an Iterator object, you must specify the
iteratorElementType element to the @SQL annotation to indicate the underlying
type that the Iterator will contain. The following example returns a iterator
of all employees sorted by their last names.
+<p>When your method returns multiple rows from the database, its return type
can be an array, a java.util.Iterator, or a java.sql.ResultSet. </p>
+<p>When you want to return an Iterator object, you must specify the
iteratorElementType element to the @SQL annotation to indicate the underlying
type that the Iterator will contain. The following example returns a iterator
of all employees sorted by their last names.</p>
- @SQL(statement="SELECT * FROM EMPLOYEE ORDER BY lName",
iteratorElementType=Employee.class, maxRows=500)
- public Iterator getEmployeesSortedByLastName() throws SQLException;
+<source> @SQL(statement="SELECT * FROM EMPLOYEE ORDER BY lName",
iteratorElementType=Employee.class, maxRows=500)
+ public Iterator getEmployeesSortedByLastName() throws
SQLException;</source>
-You can limit the number of rows returned by setting the maxRows element of
the @SQL annotation. This element can protect you from very large resultsets
that may be returned by very general queries. The default value of maxRow is
1024.
+<p>You can limit the number of rows returned by setting the maxRows element of
the @SQL annotation. This element can protect you from very large resultsets
that may be returned by very general queries. The default value of maxRow is
1024.</p>
-The Database Control defines two annotations: SQL and ConnectionDataSource.
+<p>The Database Control defines two annotations: SQL and
ConnectionDataSource.</p>
-The SQL Annotation specifies the SQL statement and associated attributes that
correspond to a method in a Database control.
+<p>The SQL Annotation specifies the SQL statement and associated attributes
that correspond to a method in a Database control.</p>
- public @interface SQL
+<source> public @interface SQL
{
String statement() default "";
int maxRows() default MAXROWS_ALL;
@AnnotationMemberTypes.Optional
Class iteratorElementType() default UndefinedIteratorType.class;
- }
+ }</source>
-The "statement" element is required. It specifies the SQL (Structured Query
Language) statement that will be executed when the associated Database control
method is invoked. The statement may contain substitutions of the form
{varName}, where paramName is a parameter of the Database control method (or a
member accessible from the parameter).
+<p>The "statement" element is required. It specifies the SQL (Structured Query
Language) statement that will be executed when the associated Database control
method is invoked. The statement may contain substitutions of the form
{varName}, where paramName is a parameter of the Database control method (or a
member accessible from the parameter).</p>
-The "iteratorElementType" is required if Database control method return type
is java.util.Iterator. It specifies the underlying class of the Iterator that
will be returned by the Database control method.
+<p>The "iteratorElementType" is required if Database control method return
type is java.util.Iterator. It specifies the underlying class of the Iterator
that will be returned by the Database control method. </p>
-The "maxRows" element is optional. It sets the maximum number of records to be
returned by the query. The maxRows element limits the size of all types of data
sets, including Arrays, Iterator, ResultSet, etc. The default value of this
element is 1024.
+<p>The "maxRows" element is optional. It sets the maximum number of records to
be returned by the query. The maxRows element limits the size of all types of
data sets, including Arrays, Iterator, ResultSet, etc. The default value of
this element is 1024.</p>
-The ConnectionDataSource annotation specifies the data source that the
Database control will use to obtain connection. At the time of writing, this
has not been fully implemented yet. The Database control currently uses the
embedded Derby database driver to obtain connection, and it is expecting the
value provided for the "jndiName" element to be a database URL.
+<p>The ConnectionDataSource annotation specifies the data source that the
Database control will use to obtain connection. At the time of writing, this
has not been fully implemented yet. The Database control currently uses the
embedded Derby database driver to obtain connection, and it is expecting the
value provided for the "jndiName" element to be a database URL.</p>
- public @interface ConnectionDataSource
+<source> public @interface ConnectionDataSource
{
String jndiName(); // no default ... value is required
- }
+ }</source>
-The Database control is current included in the Beehive distribution as a
sample control (\samples\controls-db). Building this control with the Ant
script provided will create a dbControl.jar in \samples\controls-db\build\.
You can start creating your own database control extension by simply including
this JAR file in your classpath.
+<p>The Database control is current included in the Beehive distribution as a
sample control (\samples\controls-db). Building this control with the Ant
script provided will create a <code>dbControl.jar</code> in
\samples\controls-db\build\. You can start creating your own database control
extension by simply including this JAR file in your classpath.</p>
+
+<p>Notice that the sample <link
href="../wsm/sample_AddressBook.html">EmployeeWS</link> uses this same
technique (subclassing DatabaseControl) for database access. The EmployeeWS
sample is a database control exposed as a web service. The exposed database
control, EmployeeDBControl, is a subclass of DatabaseControl (archived in
<code>dbControl.jar</code>).</p>
+<source>public interface EmployeeDBControl extends DatabaseControl
+{
+ ...
+}
+</source>
- -->
-
- </p>
+<!-- </p>
<section>
<title>Structure of the Database Control</title>
</section>
@@ -108,16 +111,23 @@
<ul>
<li>Metadata annotations: reduces configuring the control for resource
access to a matter of setting properties throught annotations. To a client,
the control appears as a JavaBean that is instantiated and operated upon for
resource access. Base controls configure the container using annotations.
Control extensions configure the base.</li>
+-->
<!-- <li>events (<link
href="http://incubator.apache.org/beehive/ControlsOverview.html#Operations";>http://incubator.apache.org/beehive/ControlsOverview.html#Operations</link>)</li>
<li>resource management (<link
href="http://incubator.apache.org/beehive/ControlsOverview.html#Resource%20Management";>http://incubator.apache.org/beehive/ControlsOverview.html#Resource%20Management</link>)....
[todo]</li>
--->
- </ul>
+ </ul>-->
+
</section>
-<!-- <section>
- <title>Distributing the Database Control</title>
- <p>[todo]</p>
- </section>-->
- </body>
+
+<section>
+ <title>Building the Database Control</title>
+ <p>To build <code>dbControl.jar</code> run the following Ant command:</p>
+ <p>On Windows:</p>
+ <p><code>ant -f %BEEHIVE_HOME%\samples\controls-db\build.xml
build</code>.</p>
+ <p>On Unix:</p>
+ <p><code>ant -f $BEEHIVE_HOME\samples\controls-db\build.xml
build</code>.</p>
+ <p>This produces the file <code>dbControl.jar</code> in the directory
<code>BEEHIVE_HOME/samples/controls-db/build</code>.</p>
+ <p></p>
+</section> </body>
<footer>
<legal>Java, J2EE, and JCP are trademarks or registered trademarks of
Sun Microsystems, Inc. in the United States and other countries.<br/>
© 2004, Apache Software Foundation
Modified:
incubator/beehive/site/src/documentation/content/xdocs/wsm/sample_AddressBook.xml
==============================================================================
---
incubator/beehive/site/src/documentation/content/xdocs/wsm/sample_AddressBook.xml
(original)
+++
incubator/beehive/site/src/documentation/content/xdocs/wsm/sample_AddressBook.xml
Sat Nov 13 14:20:23 2004
@@ -8,7 +8,8 @@
<section>
<title>The AddressBookWS and EmployeeWS Samples</title>
<p>The <strong>AddressBookWS</strong> sample is an
annotation-aware web service based on the Apache Axis sample of the same name.
AddressBookWS is organized as an application with POJO (Plain Old Java Objects)
models, service interface, service implementation, and unit tests for the
service. Apache Axis provides automatic client-generation and junit test cases
for the sample. The directory structure and ant build file can be used as a
template for building new standalone web services.</p>
- <p><strong>EmployeeWS</strong> provides a web service interface
for an Employee database. Using SOAP messages, the web service queries the
backend database: selecting, updating and inserting employee data. A Beehive
database control connects the web service and the database. The web service
class is located at <code>EmployeeWS/WEB-INF/src/web/Service.jws</code>. The
database control is located at
<code>EmployeeWS/WEB-INF/src/org/apache/beehive/sample/EmployeeDBControl.jcx</code>.
Apache Derby supplies the database implementation. (Installing Derby
requires a simple JAR file download, described below.) Apache Axis provides
the automatic client-generation for the web service. Custom unit tests are
provided to exercise the webservice methods. The unit tests creates the
database table, inserts a new record, queries the database, and finally drops
the table. Use the junit tests as a template for building automatic tests for
your own controls.</p>
+ <p><strong>EmployeeWS</strong> provides a web service interface
for an Employee database. Using SOAP messages, the web service queries the
backend database: selecting, updating and inserting employee data. A Beehive
database control connects the web service and the database. The web service
class is located at <code>EmployeeWS/WEB-INF/src/web/Service.jws</code>. The
database control is located at
<code>EmployeeWS/WEB-INF/src/org/apache/beehive/sample/EmployeeDBControl.jcx</code>.
Note that EmployeeDBControl is a subclass of DatabaseControl, another Beehive
sample. For more information see <link
href="../controls/sample_controls-db.html">Database Control</link>. </p>
+<p>Apache Derby supplies the database implementation. (Installing Derby
requires a simple JAR file download, described below.) Apache Axis provides
the automatic client-generation for the web service. Custom unit tests are
provided to exercise the webservice methods. The unit tests creates the
database table, inserts a new record, queries the database, and finally drops
the table. Use the junit tests as a template for building automatic tests for
your own controls.</p>
</section>
<section>
<title>Running the Samples</title>
