You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beehive.apache.org by st...@apache.org on 2005/06/15 18:58:01 UTC
svn commit: r190777 -
/incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml
/incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml
Author: steveh
Date: Wed Jun 15 09:58:00 2005
New Revision: 190777
URL: http://svn.apache.org/viewcvs?rev=190777&view=rev
Log:
Prose edits contributed by Liza Ketchum.
Modified:
incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml
incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml
Modified: incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml
URL: http://svn.apache.org/viewcvs/incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml?rev=190777&r1=190776&r2=190777&view=diff
==============================================================================
--- incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml (original)
+++ incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jdbc/jdbcControlDevGuide.xml Wed Jun 15 09:58:00 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>
-@SQL(statement="{sql: sqlStatement}")
+@SQL(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/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml
URL: http://svn.apache.org/viewcvs/incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml?rev=190777&r1=190776&r2=190777&view=diff
==============================================================================
--- incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml (original)
+++ incubator/beehive/branches/v1/m1/docs/forrest/src/documentation/content/xdocs/system-controls/jms/jmsDoc.xml Wed Jun 15 09:58:00 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>