Author: steveh
Date: Wed Jun 15 10:01:27 2005
New Revision: 190778
URL: http://svn.apache.org/viewcvs?rev=190778&view=rev
Log:
Integrating changes from v1m1 branch. (Prose edits.)
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml?rev=190778&r1=190777&r2=190778&view=diff
==============================================================================
---
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml
(original)
+++
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml
Wed Jun 15 10:01:27 2005
@@ -60,8 +60,8 @@
<tr><td>statement</td><td>String</td><td>Yes</td><td>The SQL statement to send
to the database</td></tr>
<tr><td>arrayMaxLength</td><td>int</td><td>No</td><td>If the method return type
is an array type, limit the size of the array to this value</td></tr>
<tr><td>batchUpdate</td><td>boolean</td><td>No</td><td>Defaults to false, JDBC
3.0 batch update</td></tr>
-
<tr><td>fetchSize</td><td>int</td><td>No</td><td>Performance hint for fetching
ResultSet rows, defaults to zero, indicating db shoud determine fectch
size.</td></tr>
-
<tr><td>fetchDirection</td><td>FetchDirection</td><td>No</td><td>Performance
hint for fetching ResultSet rows, defaults to foward.</td></tr>
+
<tr><td>fetchSize</td><td>int</td><td>No</td><td>Performance hint for fetching
ResultSet rows, defaults to zero, indicating db should determine fetch
size.</td></tr>
+
<tr><td>fetchDirection</td><td>FetchDirection</td><td>No</td><td>Performance
hint for fetching ResultSet rows, defaults to forward.</td></tr>
<tr><td>getGeneratedKeys</td><td>boolean</td><td>No</td><td>Defaults to false,
JDBC 3.0 generated keys</td></tr>
<tr><td>generatedKeyColumnNames</td><td>String array</td><td>No</td><td>Defines
column names of columns with generated keys to be returned</td></tr>
<tr><td>generatedKeyColumnIndexes</td><td>int array</td><td>No</td><td>Defines
column indexes of columns with generated keys to be returned</td></tr>
@@ -92,7 +92,7 @@
<li><strong>The type of the method parameter
must be compatible with the type of the associated database field in the
statement.</strong> If you attempt to substitute a Java String where the
database expects a NUMBER, the statement will fail. For information on mapping
between database types and Java types, see Mapping Database Field Types to Java
Types in the Database Control.</li>
- <li><strong>Substitution will not occur if the
substitution pattern contains spaces.</strong> The Java Database Connectivity
(JDBC) API allows access to built-in database functions via escapes of the form
{fn user()}. If spaces occur in an item enclosed in curly braces ({}) item, the
Database control treats the item as a JDBC escape and passes it on without
substitution. For example, the custCity method parameter will not be
substituted if the substitution is specified as {custCity } or { custCity}. For
more information on JDBC escapes, please consult the documentation for your
JDBC driver.</li>
+ <li><strong>Substitution will not occur if the
substitution pattern contains spaces.</strong> The Java Database Connectivity
(JDBC) API allows access to built-in database functions via escapes of the form
{fn user()}. If spaces occur in an item enclosed in curly braces ({}), the
Database control treats the item as a JDBC escape and passes it on without
substitution. For example, the custCity method parameter will not be
substituted if the substitution is specified as {custCity } or { custCity}. For
more information on JDBC escapes, please consult the documentation for your
JDBC driver.</li>
<li><strong>When substituting date or time
values, use the classes in the java.sql package.</strong> For example,
attempting to substitute java.util.Date in a SQL Date field will not work. Use
java.sql.Date instead.</li>
</ul>
@@ -188,10 +188,10 @@
<section>
<title>Generic Substitution</title>
- <p>To pass a whole SQL statement to the database, use
the substitution syntax shown in red.</p>
+ <p>To pass a whole SQL statement to the database, use
the substitution syntax shown in bold.</p>
<source>
[EMAIL PROTECTED](statement="{sql: sqlStatement}")
[EMAIL PROTECTED](statement="{<strong>sql: sqlStatement</strong>}")
public myRecordType myQuery( String sqlStatement );
</source>
@@ -224,7 +224,7 @@
Customer[] callInternalFunction(Integer[] customerIDs);
</source>
- <p>Not all databases and database drivers support internal functions
within substitution brackets, for example, Oracle drivers do not support this
scenario.</p>
+ <p>Not all databases and database drivers support internal functions
within substitution brackets; for example, Oracle drivers do not support this
scenario.</p>
</section>
<section>
@@ -393,7 +393,7 @@
<p>Note that Jdbc control method call_sp_squareInt does not
return the result of the procedure call.
Instead the result of the procedure is loaded directly
into the procedure's OUT parameter,
and this in turn is loaded directly into the
corresponding SQLParameter object. To get the
- result of the procedure, examine the .value property
of the of the SQLParameter object.</p>
+ result of the procedure, examine the .value property
of the SQLParameter object.</p>
<source>
params[1].value
@@ -439,7 +439,7 @@
<p>Some XA database drivers contain restrictions on
code that rollsback or commits a
transaction independently of the driver's
transaction management. Since DDL
- statements are implicitly transactional
(COMMIT is called whether it or not
+ statements are implicitly transactional
(COMMIT is called whether or not
it explicitly appears in the DDL statement),
you may have to suspend the
transaction with these XA drivers. For example
if you send a DDL statement
using the Oracle XA thin client without
suspending the transaction, the driver
@@ -482,8 +482,8 @@
<section>
<title>Calling Stored Functions</title>
- <p>To call a stored function, place the function call
in a @SQL statement annotation. When the
- Java method callMyFunction is called the SQL
statement in the @SQLl statement annotation
+ <p>To call a stored function, place the function call
in an @SQL statement annotation. When the
+ Java method callMyFunction is called, the SQL
statement in the @SQLl statement annotation
is passed to the database. Any data returned by
the SQL statement is passed back to, and
returned by, the Java method.</p>
@@ -493,7 +493,7 @@
</source>
<p>In most cases, the Jdbc control automatically
converts between the appropriate database data types
- to the Java data types. For example, if the
database function my_function returns the database
+ and Java data types. For example, if the
database function my_function returns the database
type INTEGER, the Java method callMyFunction()
will automatically convert it into the Java type int.</p>
<p>You can substitute values dynamically into the
database function call using curly braces.
@@ -513,9 +513,9 @@
void create_fn_squareInt() throws SQLException;
</source>
- <p>Some XA database drivers contain restrictions on
code that rolls back or commits a
+ <p>Some XA database drivers contain restrictions on
code that rollsback or commits a
transaction independently of the driver's
transaction management. Since DDL
- statements are implicitly transactional (COMMIT
is called whether it or not
+ statements are implicitly transactional (COMMIT
is called whether or not
it explicitly appears in the DDL statement),
you may have to suspend the
transaction with these XA drivers. For example
if you send a DDL statement
using the Oracle XA thin client without
suspending the transaction, the driver
@@ -584,7 +584,7 @@
<section>
<title>Returning an Update Count</title>
- <p>Suppose that with the same database table a row
is inserted, the following code could be
+ <p>Suppose that with the same database table a row
is inserted; the following code could be
used to get the update count from the
insert statement:</p>
<source>
@@ -639,7 +639,7 @@
Customer findCustomer(int customerID)
</source>
- <p>Note: The Customer class above is simplified for
the sake of clarity. For data modelling
+ <p>Note: The Customer class above is simplified for
the sake of clarity. For data modeling
classes, it is generally good design
practice to have private fields, with public
setter and getter methods.</p>
@@ -687,7 +687,7 @@
set to null or 0, depending on whether the
member is an primitive or an object.</p>
<p>If the query returns columns that cannot be
matched to the members of the class, an exception is
- thrown. If you don't know the columns that
will be returned or they may change, you should
+ thrown. If you don't know the columns that
will be returned or if they may change, you should
consider returning a HashMap instead of a
specific class. For more information, see the
Returning a HashMap section, below.</p>
@@ -764,7 +764,7 @@
<p>Returning an array of objects is the easiest way to
return multiple rows, so it is a good choice
if you think your users will prefer simplicity
when using your control. However, when an
- array is returned only one database operation
is performed and the entire resultset must
+ array is returned only one database operation
is performed, and the entire resultset must
be stored in memory. For large resultsets,
this is problematic. You can limit the size
of the returned array, but then you cannot
provide a way for your user to get the remainder
of the resultset. To learn how to return an
array of objects, see the Returning an Array of Objects
@@ -1060,7 +1060,7 @@
<p>When the XSD file is compiled, XMLBean types are generated that
can be returned by the methods in the database control.</p>
</section>
<section>
- <title>Editting Schemas to Create New "Document" Types</title>
+ <title>Editing Schemas to Create New "Document" Types</title>
<p>Note that only one of the generated types is a "Document" XMLBean
type: XCustomerDocument. The other types,
XCustomerDocument.XCustomer and
XCustomerDocument.XCustomer.XCustomerRow, can only be used with reference
@@ -1139,7 +1139,7 @@
<title>Mapping to a RowSet</title>
<p>This topic describes how to write methods on a Jdbc control
that return a RowSet from the database.
- Since the RowSet implementations provided by the JDK
are part of the javax.sql package the
+ Since the RowSet implementations provided by the JDK
are part of the javax.sql, package the
JdbcControl does not support any of them by default.
A sample ResultSetMapper for RowSet's is
included as part of the Jdbc Control's distribution
but must be explicitly set in the @SQL
annotation in order to be invoked.</p>
@@ -1153,7 +1153,7 @@
public RowSet getAllUsers() throws SQLException;
</source>
- <p>ResultSetMapper's can be created for other types of RowSets
and most any other type of mapping
+ <p>ResultSetMapper's can be created for other types of RowSets
and almost any other type of mapping
from a result set to any object. See the [Jdbc
Control Custom ResultSetMappers] topic for more information.
</p>
</section>
@@ -1163,10 +1163,10 @@
<section>
<title>Overview</title>
- <p>When the Jdbc Control maps a ResultSet to a return
type it first checks to see if a resultSetMapper
+ <p>When the Jdbc Control maps a ResultSet to a return
type, it first checks to see if a resultSetMapper
has been set in the method's @SQL annotation.
If a mapper has been set, it is always the one used
for mapping the ResultSet to the method's
return type. If resultSetMapper has not been
- set the Jdbc control looks for a
_resultSetMapper_ based on the method's return type.</p>
+ set, the Jdbc control looks for a
_resultSetMapper_ based on the method's return type.</p>
<table>
<tr><th>Mapper Class Name</th><th>Method
Return Type</th></tr>
Modified:
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml
URL:
http://svn.apache.org/viewcvs/incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml?rev=190778&r1=190777&r2=190778&view=diff
==============================================================================
---
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml
(original)
+++
incubator/beehive/trunk/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml
Wed Jun 15 10:01:27 2005
@@ -11,7 +11,7 @@
<p>The JMS control provides for sending messages to a queue or
topic destination. It is an extensible
control where sub-classes are bound to specific
queues/topics and methods may be defined to
send messages of specific types with specific properties
and headers. The queue connections
- are transparently managed by the controls relieving the
developer of that responsibility.</p>
+ are transparently managed by the controls, relieving the
developer of that responsibility.</p>
<p>In the example below, the OrderQueue control class has one
submitOrder() method that takes an
Order object as the body and a string that sets the
'DeliverBy' property in the
@@ -89,7 +89,7 @@
<table>
<tr><th>Attribute</th><th>Value</th><th>Description</th></tr>
<tr><td>sendJndiName</td><td>string</td><td>JNDI name of
the queue or topic. Required.</td></tr>
- <tr><td>sendCorrelationProperty</td><td>string</td><td>The
correlation property to be used for message sent. Default is empty which
signifies that the JMS correlation header is to be used. Optional.</td></tr>
+ <tr><td>sendCorrelationProperty</td><td>string</td><td>The
correlation property to be used for message sent. Default is empty, which
signifies that the JMS correlation header is to be used. Optional.</td></tr>
<tr><td>connectionFactoryJndiName</td><td>string</td><td>JNDI name of the
connection factory. Required</td></tr>
<tr><td>transacted</td><td>boolean</td><td>True if
en-queuing is under transactional semantics of the enclosing container. Default
is true. See JMS documentation on transactional semantics of en-queueing and
de-queueing.</td></tr>
<tr><td>acknowledgeMode</td><td>enum
AcknowledgeMode</td><td>The acknowledgement strategy, one of Auto, Client,
DupsOk. Default is Auto. See JMS API documentation on
javax.jms.Session.AUTO_ACKNOWLEDGE/CLIENT_ACKNOWLEDGE/DUPS_OK_ACKNOWLEDGE for
more information</td></tr>
@@ -104,19 +104,19 @@
<title>Extension Method Annotation</title>
<p>The jms-control is intended to be extended. One or more methods
may be defined that send messages
- to the given destination may be annotated with:</p>
+ to the given destination. They may be annotated with:</p>
<ul>
<li>@Message( message-type) or @Message or nothing.</li>
- <li>@Priority - the int valued attribute contains a JMS
priority (0-9). If not given then
+ <li>@Priority - the int valued attribute contains a JMS
priority (0-9). If not given, then
the default for the provider is used.</li>
<li>@Expiration - the long valued attribute contains a JMS
expiration in milliseconds.
- If not given then the default for the provider is
used.</li>
+ If not given, then the default for the provider is
used.</li>
<li>@Delivery - the DeliveryMode valued attribute
determines the delivery mode of the
- message. If not given then the default for the
provider is used.</li>
+ message. If not given, then the default for the
provider is used.</li>
<li>@Type - the string valued attribute determines the JMS
type.</li>
@@ -125,19 +125,19 @@
<li>@Properties( PropertyValue[] ) - One or more
string/int/long valued properties to be added
to the message. PropertyValue has the string
valued attributes 'name', 'value' and class
valued 'type'. The allowed values for 'type' are
String.class, Integer.class and Long.class.
- If not given then 'String.class' is assumed.</li>
+ If not given, then 'String.class' is assumed.</li>
</ul>
<p>The message-type value is a MessageType enumerated value.
Values are: Auto, Object, Bytes, Text,
- Map and JMSMessage. If not given or no message-type string
then the default is Auto. If Auto
+ Map and JMSMessage. If not given or no message-type
string, then the default is Auto. If Auto,
then the type of JMS message is determined by the type of
the body passed in. If the body is a
- String or XmlObject then a TextMessage is sent, if the
body is a byte[] then a StreamMessage
- is sent, if the body is a Map then a MapMessage is sent,
if the body is a JMSMessage then it is sent,
- otherwise if the body is Serializable then an
ObjectMessage is sent. Any other type
+ String or XmlObject, then a TextMessage is sent; if the
body is a byte[], then a StreamMessage
+ is sent; if the body is a Map, then a MapMessage is sent;
if the body is a JMSMessage, then it is sent;
+ otherwise if the body is Serializable, then an
ObjectMessage is sent. Any other type
results in a control exception.</p>
- <p>The values of the DeliveryMode enumerated value are:
NonPersistent, Persistent and Auto where
+ <p>The values of the DeliveryMode enumerated value are:
NonPersistent, Persistent, and Auto, where
Auto is the default.</p>
</section>
<section>
@@ -148,15 +148,15 @@
<li>@Property (name= blah ) - the parameter contains the
value of the property blah.</li>
<li>@Priority - the int or integer valued String parameter
contains a JMS priority (0-9). If
- not given then the method-level annotation is used
if given else the default for
+ not given, then the method-level annotation is
used; else the default for
the provider is used.</li>
<li>@Expiration - the long or integer valued String
parameter contains a JMS expiration in
- milliseconds. If not given then the method-level
annotation is used if given else
+ milliseconds. If not given, then the method-level
annotation is used; else
the default for the provider is used.</li>
<li>@Delivery - the DeliveryMode valued parameter
determines the delivery mode of the message.
- If not given then the method-level annotation is
used if given else the default for
+ If not given, then the method-level annotation is
used; else the default for
the provider is used.</li>
<li>@Type - the string valued parameter determines the JMS
type.</li>
