You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by rh...@apache.org on 2018/06/14 23:29:39 UTC
svn commit: r1833569 [4/4] - in
/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby: agg/
authentication/ catalog/ database/ iapi/db/ iapi/jdbc/ iapi/services/cache/
iapi/services/context/ iapi/services/crypto/ iapi/services/daemon/ iapi...
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/store/raw/Undoable.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/store/raw/Undoable.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/store/raw/Undoable.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/store/raw/Undoable.java Thu Jun 14 23:29:38 2018
@@ -46,16 +46,16 @@ public interface Undoable extends Loggab
<P>
There are 3 ways to implement a redo-only log record:
- <NL>
+ <UL>
<LI>Make the log record a Loggable instead of an Undoable, this is the
- cleanest method.
+ cleanest method.</LI>
<LI>If you want to extend a log operation class that is an Undoable,
you can then either have generateUndo return null - this is preferred -
(the log operation's undoMe should never be called, so you can put a
null body there if the super class you are extending does not implement
- a undoMe).
- <LI>Or, have undoMe do nothing - this is least preferred.
- </NL>
+ a undoMe).</LI>
+ <LI>Or, have undoMe do nothing - this is least preferred.</LI>
+ </UL>
<P>Any resource (e.g., latched page) that is needed for the
undoable.undoMe() must be acquired in undoable.generateUndo().
@@ -74,18 +74,18 @@ public interface Undoable extends Loggab
<P>
The sequence of events in a rollback of a undoable operation is
- <NL>
+ <UL>
<LI> The logging system calls undoable.generateUndo. If this returns
- null, then there is nothing to undo.
+ null, then there is nothing to undo.</LI>
<LI> If generateUndo returns a Compensation operation, then the logging
system will log the Compensation log record and call
Compenstation.doMe(). (Hopefully, this just calls the undoable's
- undoMe)
+ undoMe)</LI>
<LI> After the Compensation operation has been applied, the logging
system will call compensation.releaseResource(). If you do overwrite a
super class's releaseResource(), it would be prudent to call
- super.releaseResource() first.
- </NL>
+ super.releaseResource() first.</LI>
+ </UL>
<P> The available() method of in indicates how much data can be read, i.e.
how much was originally written.
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/RawToBinaryFormatStream.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/RawToBinaryFormatStream.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/RawToBinaryFormatStream.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/RawToBinaryFormatStream.java Thu Jun 14 23:29:38 2018
@@ -139,7 +139,7 @@ public final class RawToBinaryFormatStre
* @param maximumLength maximum length of the column data is inserted into
* @param typeName type name for the column data is inserted into
* @throws IllegalArgumentException if maximum length is negative, or type
- * name is <code>null<code>. This exception should never be exposed
+ * name is <code>null</code>. This exception should never be exposed
* to the user, and seeing it means a programming error exists in the
* code. Although a missing type name is not critical, an exception is
* is thrown to signal the intended use of this constructor.
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/Resetable.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/Resetable.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/Resetable.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/Resetable.java Thu Jun 14 23:29:38 2018
@@ -34,6 +34,9 @@ public interface Resetable
{
/**
* Reset the stream to the beginning.
+ *
+ * @throws IOException on error
+ * @throws StandardException on error
*/
public void resetStream() throws IOException, StandardException;
@@ -41,6 +44,7 @@ public interface Resetable
* Initialize. Needs to be called first, before a resetable stream can
* be used.
*
+ * @throws StandardException on error
*/
public void initStream() throws StandardException;
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/SQLBinary.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/SQLBinary.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/SQLBinary.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/types/SQLBinary.java Thu Jun 14 23:29:38 2018
@@ -61,22 +61,20 @@ import java.sql.PreparedStatement;
* </UL>
<P>
- Format : <encoded length><raw data>
+ Format : <encoded length><raw data>
<BR>
Length is encoded to support Cloudscape 5.x databases where the length was stored as the number of bits.
The first bit of the first byte indicates if the format is an old (Cloudscape 5.x) style or a new Derby style.
Derby then uses the next two bits to indicate how the length is encoded.
<BR>
- <encoded length> is one of N styles.
+ <encoded length> is one of N styles.
<UL>
- <LI> (5.x format zero) 4 byte Java format integer value 0 - either <raw data> is 0 bytes/bits or an unknown number of bytes.
- <LI> (5.x format bits) 4 byte Java format integer value >0 (positive) - number of bits in raw data, number of bytes in <raw data>
- is the minimum number of bytes required to store the number of bits.
- <LI> (Derby format) 1 byte encoded length (0 <= L <= 31) - number of bytes of raw data - encoded = 0x80 & L
- <LI> (Derby format) 3 byte encoded length (32 <= L < 64k) - number of bytes of raw data - encoded = 0xA0 <L as Java format unsigned short>
- <LI> (Derby format) 5 byte encoded length (64k <= L < 2G) - number of bytes of raw data - encoded = 0xC0 <L as Java format integer>
- <LI> (future) to be determined L >= 2G - encoded 0xE0 <encoding of L to be determined>
- (0xE0 is an esacape to allow any number of arbitary encodings in the future).
+ <LI> (5.x format zero) 4 byte Java format integer value 0 - either <raw data> is 0 bytes/bits or an unknown number of bytes.</LI>
+ <LI> (5.x format bits) 4 byte Java format integer value >0 (positive) - number of bits in raw data, number of bytes in <raw data> is the minimum number of bytes required to store the number of bits.</LI>
+ <LI> (Derby format) 1 byte encoded length (0 <= L <= 31) - number of bytes of raw data - encoded = 0x80 & L</LI>
+ <LI> (Derby format) 3 byte encoded length (32 <= L < 64k) - number of bytes of raw data - encoded = 0xA0 <L as Java format unsigned short></LI>
+ <LI> (Derby format) 5 byte encoded length (64k <= L < 2G) - number of bytes of raw data - encoded = 0xC0 <L as Java format integer></LI>
+ <LI> (future) to be determined L >= 2G - encoded 0xE0 <encoding of L to be determined> (0xE0 is an esacape to allow any number of arbitary encodings in the future).</LI>
</UL>
<BR>
When the value was written from a byte array the Derby encoded byte
@@ -406,7 +404,6 @@ abstract class SQLBinary
* delegated to bit
*
* @exception IOException io exception
- * @exception ClassNotFoundException class not found
*/
public final void readExternal(ObjectInput in) throws IOException
{
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/util/InterruptStatus.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/util/InterruptStatus.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/util/InterruptStatus.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/util/InterruptStatus.java Thu Jun 14 23:29:38 2018
@@ -120,15 +120,18 @@ public class InterruptStatus {
/**
+ * <p>
* Checks if the thread has been interrupted in NIO, presumably because we
* saw an exception indicating this. Make a note of this and clear the
* thread's interrupt status flag (NIO doesn't clear it when throwing) so
* we can retry whatever we are doing. It will be set back ON before
* control is transferred back to the application, cf. {@code
* restoreIntrFlagIfSeen}.
- * <p/>
+ * </p>
+ * <p>
* The note that we saw an interrupt is stored in the lcc if available, if
* not, in thread local {@code exception}.
+ * </p>
*
* @param s (debug info) whence
* @param threadsInPageIO (debug info) number of threads inside the NIO
@@ -166,12 +169,14 @@ public class InterruptStatus {
/**
+ * <p>
* Check if the we ever noticed and reset the thread's interrupt status
* flag to allow safe operation during execution. Called from JDBC API
* methods before returning control to user application. Typically, this
* happens just prior to return in methods that catch {@code Throwable} and
* invoke
* {@code handleException} (directly or indirectly) on it, e.g.
+ * </p>
* <pre>
* :
* InterruptStatus.restoreIntrFlagIfSeen();
@@ -180,12 +185,15 @@ public class InterruptStatus {
* throw handleException(t);
* }
* </pre>
+ * <p>
* {@code handleException} does its own calls to {@code
* restoreIntrFlagIfSeen}. If {@code setupContextStack} has been called
* consider using the overloaded variant of {@code restoreIntrFlagIfSeen}
* with an lcc argument.
- * <p/>
+ * </p>
+ * <p>
* If an interrupt status flag was seen, we set it back <em>on</em> here.
+ * </p>
*/
public static void restoreIntrFlagIfSeen() {
@@ -221,6 +229,7 @@ public class InterruptStatus {
}
/**
+ * <p>
* Same purpose as {@code restoreIntrFlagIfSeen()}. This variant presumes
* we are sure we have a {@code lcc != null}, i.e. {@code
* setupContextStack} has been called and not yet restored. Note that we
@@ -228,9 +237,11 @@ public class InterruptStatus {
* typically called in a {@code finally} block, at which point in time, the
* {@code lcc} may be gone due to errors of severity {@code
* SESSION_SEVERITY} or {@code DATABASE_SEVERITY}.
- * <p/>
+ * </p>
+ * <p>
* If no {@code lcc} is available, use the zero-arg variant. We only need
* this variant for performance reasons.
+ * </p>
*
* @param lcc the language connection context for this session
*/
@@ -261,13 +272,16 @@ public class InterruptStatus {
/**
+ * <p>
* Check if the we ever noticed and reset the thread's interrupt status
* flag to allow safe operation during execution, or if the interrupt
* status flag is set now. Called when operations want to be prematurely
* terminated due to interrupt.
- * <p/>
+ * </p>
+ * <p>
* If an interrupt status flag was seen, but temporarily switched off, we
* set it back ON here.
+ * </p>
*
* @param lcc the language connection context for this session
* @throws StandardException (session level SQLState.CONN_INTERRUPT) if
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/util/StringUtil.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/util/StringUtil.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/util/StringUtil.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/iapi/util/StringUtil.java Thu Jun 14 23:29:38 2018
@@ -167,7 +167,7 @@ public class StringUtil
<BR>
For each byte (b) two characaters are generated, the first character
represents the high nibble (4 bits) in hexidecimal (<code>b & 0xf0</code>), the second character
- represents the low nibble (<code>b &xs; 0x0f</code>).
+ represents the low nibble (<code>b & 0x0f</code>).
<BR>
The byte at <code>data[offset]</code> is represented by the first two characters in the returned String.
@@ -333,8 +333,8 @@ public class StringUtil
/**
- * Normalize a SQL identifer, up-casing if <regular identifer>,
- * and handling of <delimited identifer> (SQL 2003, section 5.2).
+ * Normalize a SQL identifer, up-casing if <regular identifer>,
+ * and handling of <delimited identifer> (SQL 2003, section 5.2).
* The normal form is used internally in Derby.
*
* @param id syntacically correct SQL identifier
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/impl/jdbc/EmbedResultSet.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/impl/jdbc/EmbedResultSet.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/impl/jdbc/EmbedResultSet.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/impl/jdbc/EmbedResultSet.java Thu Jun 14 23:29:38 2018
@@ -2966,7 +2966,7 @@ public class EmbedResultSet extends Conn
*
* The updater methods are used to update column values in the current row
* or the insert row. The updater methods do not update the underlying
- * database; instead the <code>updateRow</code> or </code>insertRow</code>
+ * database; instead the <code>updateRow</code> or <code>insertRow</code>
* methods are called to update the database.
*
* @param columnIndex the first column is 1, the second is 2, ...
@@ -3134,7 +3134,7 @@ public class EmbedResultSet extends Conn
*
* The updater methods are used to update column values in the current row
* or the insert row. The updater methods do not update the underlying
- * database; instead the <code>updateRow</code> or </code>insertRow</code>
+ * database; instead the <code>updateRow</code> or <code>insertRow</code>
* methods are called to update the database.
*
* @param columnIndex the first column is 1, the second is 2, ...
@@ -5068,7 +5068,7 @@ public class EmbedResultSet extends Conn
*
* The updater methods are used to update column values in the current row
* or the insert row. The updater methods do not update the underlying
- * database; instead the <code>updateRow</code> or </code>insertRow</code>
+ * database; instead the <code>updateRow</code> or <code>insertRow</code>
* methods are called to update the database.
*
* @param columnName the label for the column specified with the SQL AS
@@ -5170,7 +5170,7 @@ public class EmbedResultSet extends Conn
*
* The updater methods are used to update column values in the current row
* or the insert row. The updater methods do not update the underlying
- * database; instead the <code>updateRow</code> or </code>insertRow</code>
+ * database; instead the <code>updateRow</code> or <code>insertRow</code>
* methods are called to update the database.
*
* @param columnName the label for the column specified with the SQL AS
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/impl/jdbc/TransactionResourceImpl.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/impl/jdbc/TransactionResourceImpl.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/impl/jdbc/TransactionResourceImpl.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/impl/jdbc/TransactionResourceImpl.java Thu Jun 14 23:29:38 2018
@@ -44,15 +44,19 @@ import org.apache.derby.iapi.util.Interr
import java.util.Properties;
import java.sql.SQLException;
-/**
+/**
+ * <P>
* An instance of a TransactionResourceImpl is a bundle of things that
* connects a connection to the database - it is the transaction "context" in
* a generic sense. It is also the object of synchronization used by the
* connection object to make sure only one thread is accessing the underlying
* transaction and context.
*
- * <P>TransactionResourceImpl not only serves as a transaction "context", it
- * also takes care of: <OL>
+ * <P>
+ * TransactionResourceImpl not only serves as a transaction "context", it
+ * also takes care of:
+ * </P>
+ * <OL>
* <LI>context management: the pushing and popping of the context manager in
* and out of the global context service</LI>
* <LI>transaction demarcation: all calls to commit/abort/prepare/close a
@@ -67,11 +71,13 @@ import java.sql.SQLException;
* case of a XATransaction). A nested connection must be a ProxyConnection.
* A proxyConnection is not detachable and can itself be a XA connection -
* although an XATransaction may start nested local (proxy) connections.
+ * </P>
*
* <P> this is an example of how all the objects in this package relate to each
* other. In this example, the connection is nested 3 deep.
* DetachableConnection.
- * <P><PRE>
+ * </P>
+ * <PRE>
*
* lcc cm database jdbcDriver
* ^ ^ ^ ^
@@ -107,6 +113,7 @@ import java.sql.SQLException;
* TransactionResource at all times. A detachable connection can be without a
* TransactionResource, and a TransactionResource for an XATransaction
* (called XATransactionResource) can be without a connection.
+ * </P>
*
*
*/
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/mbeans/JDBCMBean.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/mbeans/JDBCMBean.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/mbeans/JDBCMBean.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/mbeans/JDBCMBean.java Thu Jun 14 23:29:38 2018
@@ -36,6 +36,8 @@ public interface JDBCMBean {
/**
* Get the JDBC driver's implementation level
+ *
+ * @return the driver level
*/
public String getDriverLevel();
@@ -64,6 +66,7 @@ public interface JDBCMBean {
* Does the driver accept the passed in JDBC URL
* @param url JDBC URL to check.
* @return True if it supports it, false otherwise.
+ * @throws SQLException on error
* @see java.sql.Driver#acceptsURL(String)
*/
public boolean acceptsURL(String url) throws SQLException;
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/AwareVTI.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/AwareVTI.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/AwareVTI.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/AwareVTI.java Thu Jun 14 23:29:38 2018
@@ -35,10 +35,18 @@ public interface AwareVTI
//
/////////////////////////////////////////////////////////////////
- /** Get the table function context */
+ /**
+ * Get the table function context
+ *
+ * @return the table function context
+ */
public VTIContext getContext();
- /** Set the table function context */
+ /**
+ * Set the table function context
+ *
+ * @param context The table function context
+ */
public void setContext( VTIContext context );
}
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/ForeignTableVTI.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/ForeignTableVTI.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/ForeignTableVTI.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/ForeignTableVTI.java Thu Jun 14 23:29:38 2018
@@ -160,6 +160,10 @@ public class ForeignTableVTI extends F
* <p>
* Construct from the foreign schema and table name and a foreign connection.
* </p>
+ *
+ * @param foreignSchemaName Name of the foreign schema
+ * @param foreignTableName Name of the foreign table
+ * @param foreignConnection Connection to the foreign database
*/
public ForeignTableVTI
(
@@ -199,6 +203,8 @@ public class ForeignTableVTI extends F
* @param foreignSchemaName Case-sensitive name of foreign schema
* @param foreignTableName Case-sensitive name of foreign table
* @param connectionURL URL for connecting to foreign database via DriverManager.getConnection()
+ *
+ * @return a VTI which reads the foreign table
*/
public static ForeignTableVTI readForeignTable
(
@@ -221,6 +227,8 @@ public class ForeignTableVTI extends F
* Remove the cached connection to the foreign database. This method is called
* by ForeignDBViews.unloadTool().
* </p>
+ *
+ * @param connectionURL URL for connecting to foreign database via DriverManager.getConnection()
*/
public static void dropConnection( String connectionURL )
{
@@ -232,6 +240,8 @@ public class ForeignTableVTI extends F
* This function is useful for verifying that the connection to the foreign
* database was dropped when the foreignViews tool was unloaded.
* </p>
+ *
+ * @return the number of open connections to foreign databases
*/
public static int countConnections()
{
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/ForwardingVTI.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/ForwardingVTI.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/ForwardingVTI.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/ForwardingVTI.java Thu Jun 14 23:29:38 2018
@@ -85,13 +85,27 @@ public class ForwardingVTI extends VTI
//
////////////////////////////////////////////////////////////////////////
- /** Poke in another ResultSet to which we forward method calls. */
+ /**
+ * Poke in another ResultSet to which we forward method calls.
+ *
+ * @param wrappedResultSet ResultSet to which to forward method calls
+ */
public final void wrapResultSet( ResultSet wrappedResultSet ) { _wrappedResultSet = wrappedResultSet; }
- /** Get the wrapped ResultSet. */
+ /**
+ * Get the wrapped ResultSet.
+ *
+ * @return the wrapped ResultSet
+ */
public final ResultSet getWrappedResultSet() { return _wrappedResultSet; }
- /** This overridable method maps the ForwardVTI's column numbers to those of the wrapped ResultSet */
+ /**
+ * This overridable method maps the ForwardVTI's column numbers to those of the wrapped ResultSet
+ *
+ * @param ourColumnNumber Number of column in this VTI
+ *
+ * @return the corresponding number of the column in the wrapped ResultSet
+ */
protected int mapColumnNumber( int ourColumnNumber ) { return ourColumnNumber; }
////////////////////////////////////////////////////////////////////////
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/IFastPath.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/IFastPath.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/IFastPath.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/IFastPath.java Thu Jun 14 23:29:38 2018
@@ -55,6 +55,10 @@ public interface IFastPath {
by nextRow().
Returns false if the engine must call the VTI's PreparedStatement.executeQuery()
method to execute as a regular ResultSet VTI.
+
+ @return true if the VTI starts out as a fast path query
+ @throws StandardException on error
+ @throws SQLException on error
*/
public boolean executeAsFastPath()
throws StandardException, SQLException;
@@ -66,6 +70,12 @@ public interface IFastPath {
Returns NEED_RS if the rest of the query must be handled as a regular ResultSet VTI by
the engine calling the VTI's PreparedStatement.executeQuery()
+ @param row The next row
+
+ @return GOT_ROW, SCAN_COMPLETED, or NEED_RS
+ @throws StandardException on error
+ @throws SQLException on error
+
*/
public int nextRow(DataValueDescriptor[] row)
throws StandardException, SQLException;
@@ -75,6 +85,11 @@ public interface IFastPath {
A call from the VTI execution layer back into the supplied VTI.
Presents the row just processed as an array of DataValueDescriptors.
This only called when the VTI is being executed as a regular ResultSet VTI
+
+ @param rs A ResultSet
+ @param row The row which was just processed
+ @throws StandardException on error
+ @throws SQLException on error
*/
public void currentRow(ResultSet rs, DataValueDescriptor[] row)
throws StandardException, SQLException;
@@ -83,6 +98,9 @@ public interface IFastPath {
/**
Called once the ResultSet returned by executeQuery() has emptied all of its
rows (next() has returned false).
+
+ @throws StandardException on error
+ @throws SQLException on error
*/
public void rowsDone() throws StandardException, SQLException;
}
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/IQualifyable.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/IQualifyable.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/IQualifyable.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/IQualifyable.java Thu Jun 14 23:29:38 2018
@@ -32,7 +32,16 @@ public interface IQualifyable {
Called at runtime before each scan of the VTI.
The passed in qualifiers are only valid for the single
execution that follows.
+
+ @param vtiEnvironment VTI context
+ @param qualifiers Store qualifiers
+
+ @throws SQLException on error
*/
- public void setQualifiers(VTIEnvironment vtiEnvironment, org.apache.derby.iapi.store.access.Qualifier[][] qualifiers)
+ public void setQualifiers
+ (
+ VTIEnvironment vtiEnvironment,
+ org.apache.derby.iapi.store.access.Qualifier[][] qualifiers
+ )
throws SQLException;
}
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/Pushable.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/Pushable.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/Pushable.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/Pushable.java Thu Jun 14 23:29:38 2018
@@ -64,6 +64,9 @@ public interface Pushable {
The JDBC column numbering scheme (1 based) ise used for projectedColumns.
+ @param vtiEnvironment The VTI context
+ @param projectedColumns Columns being projected out
+ @return a boolean value
@exception SQLException Error processing the request.
*/
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/RestrictedVTI.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/RestrictedVTI.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/RestrictedVTI.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/RestrictedVTI.java Thu Jun 14 23:29:38 2018
@@ -56,12 +56,14 @@ public interface RestrictedVTI
* ResultSet method is called. This method performs two tasks:
* </p>
*
+ * <ul>
* <li><b>Column names</b> - Tells the ResultSet which columns need to be fetched.</li>
* <li><b>Limits</b> - Gives the ResultSet simple bounds to apply in order
* to limit which rows are returned. Note that the ResultSet does not have
* to enforce all of these bounds. Derby will redundantly enforce these
* limits on all rows returned by the ResultSet. That is, filtering not
* performed inside the ResultSet will still happen outside the ResultSet.</li>
+ * </ul>
*
* <p>
* The <i>columnNames</i> argument is an array of columns which need to be fetched. This
@@ -130,6 +132,11 @@ public interface RestrictedVTI
* Function a hint about how to optimize its performance but the Table
* Function is not required to enforce the entire <i>restriction</i>.
* </p>
+ *
+ * @param columnNames Names of the columns to be fetched
+ * @param restriction Where clause fragment used to filter rows
+ *
+ * @throws SQLException on error
*/
public void initScan( String[] columnNames, Restriction restriction ) throws SQLException;
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/Restriction.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/Restriction.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/Restriction.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/Restriction.java Thu Jun 14 23:29:38 2018
@@ -37,10 +37,17 @@ public abstract class Restriction implem
{
/**
* Turn this Restriction into a string suitable for use in a WHERE clause.
+ *
+ * @return this Restriction as a string suitable for use in a WHERE clause.
*/
public abstract String toSQL();
- /** Utility method to parenthesize an expression */
+ /**
+ * Utility method to parenthesize an expression
+ *
+ * @param raw The original string
+ * @return the original string wrapped in parentheses
+ */
protected String parenthesize( String raw ) { return "( " + raw + " )"; }
/** An AND of two Restrictions */
@@ -52,19 +59,37 @@ public abstract class Restriction implem
private Restriction _leftChild;
private Restriction _rightChild;
- /** AND together two other Restrictions */
+ /**
+ * AND together two other Restrictions
+ *
+ * @param leftChild The first conjunct
+ * @param rightChild The second conjunct
+ */
public AND( Restriction leftChild, Restriction rightChild )
{
_leftChild = leftChild;
_rightChild = rightChild;
}
- /** Get the left Restriction */
+ /**
+ * Get the left Restriction
+ *
+ * @return the first conjunct
+ */
public Restriction getLeftChild() { return _leftChild; }
- /** Get the right Restriction */
+ /**
+ * Get the right Restriction
+ *
+ * @return the second conjunct
+ */
public Restriction getRightChild() { return _rightChild; }
-
+
+ /**
+ * Turn this Restriction into WHERE clause text.
+ *
+ * @return this Restriction as WHERE clause text
+ */
public String toSQL()
{
return parenthesize( _leftChild.toSQL() ) + " AND " + parenthesize( _rightChild.toSQL() );
@@ -80,19 +105,37 @@ public abstract class Restriction implem
private Restriction _leftChild;
private Restriction _rightChild;
- /** OR together two other Restrictions */
+ /**
+ * OR together two other Restrictions
+ *
+ * @param leftChild The first disjunct
+ * @param rightChild The second disjunct
+ */
public OR( Restriction leftChild, Restriction rightChild )
{
_leftChild = leftChild;
_rightChild = rightChild;
}
- /** Get the left Restriction */
+ /**
+ * Get the left Restriction
+ *
+ * @return the first disjunct
+ */
public Restriction getLeftChild() { return _leftChild; }
- /** Get the right Restriction */
+ /**
+ * Get the right Restriction
+ *
+ * @return the second disjunct
+ */
public Restriction getRightChild() { return _rightChild; }
+ /**
+ * Turn this Restriction into WHERE clause text.
+ *
+ * @return this Restriction as WHERE clause text
+ */
public String toSQL()
{
return parenthesize( _leftChild.toSQL() ) + " OR " + parenthesize( _rightChild.toSQL() );
@@ -207,6 +250,8 @@ public abstract class Restriction implem
* <p>
* The name of the column being compared.
* </p>
+ *
+ * @return the name of the column being compared
*/
public String getColumnName() { return _columnName; }
@@ -215,6 +260,8 @@ public abstract class Restriction implem
* The type of comparison to perform. This is one of the ORDER_OP constants
* defined above.
* </p>
+ *
+ * @return an ORDER_OP representing the type of comparison to perform
*/
public int getComparisonOperator() { return _comparisonOperator; }
@@ -229,9 +276,16 @@ public abstract class Restriction implem
* maps to java.lang.String, etc.. This object will be null if the
* comparison operator is ORDER_OP_ISNULL or ORDER_OP_ISNOTNULL.
* </p>
+ *
+ * @return the constant with which the column is being compared
*/
public Object getConstantOperand() { return _constantOperand; }
+ /**
+ * Turn this Restriction into WHERE clause text.
+ *
+ * @return this Restriction as WHERE clause text
+ */
public String toSQL()
{
StringBuffer buffer = new StringBuffer();
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/StringColumnVTI.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/StringColumnVTI.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/StringColumnVTI.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/StringColumnVTI.java Thu Jun 14 23:29:38 2018
@@ -87,6 +87,10 @@ public abstract class StringColumn
* <p>
* Get the string value of the column in the current row identified by the 1-based columnNumber.
* </p>
+ *
+ * @param columnNumber The 1-based column index to lookup
+ * @return the string value of the corresponding column
+ * @throws SQLException on error
*/
protected abstract String getRawColumn( int columnNumber ) throws SQLException;
@@ -100,6 +104,8 @@ public abstract class StringColumn
* <p>
* Build a StringColumnVTI with the given column names
* </p>
+ *
+ * @param columnNames The names of the VTI's columns
*/
public StringColumnVTI( String[] columnNames )
{
@@ -121,6 +127,9 @@ public abstract class StringColumn
* which need to figure out their column names after analyzing their execution
* context. Throws an exception if the column names have already been set.
* </p>
+ *
+ * @param columnNames The names of the columns to be returned by this VTI
+ * @throws SQLException on error
*/
public void setColumnNames( String[] columnNames )
throws SQLException
@@ -135,6 +144,8 @@ public abstract class StringColumn
* <p>
* Get the number of columns.
* </p>
+ *
+ * @return the number of columns in the VTI
*/
public int getColumnCount() { return _columnNames.length; }
@@ -142,6 +153,9 @@ public abstract class StringColumn
* <p>
* Get name of a column (1-based indexing).
* </p>
+ *
+ * @param columnNumber 1-based position of column whose name is needed
+ * @return the name of the corresponding column
*/
public String getColumnName( int columnNumber ) { return _columnNames[ columnNumber - 1 ]; }
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIContext.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIContext.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIContext.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIContext.java Thu Jun 14 23:29:38 2018
@@ -77,13 +77,25 @@ public class VTIContext
//
/////////////////////////////////////////////////////////////////
- /** Return the name of the schema holding the table function */
+ /**
+ * Return the name of the schema holding the table function
+ *
+ * @return the name of the schema holding this table function
+ */
public String vtiSchema() { return _vtiSchema; }
- /** Return the unqualified table function name */
+ /**
+ * Return the unqualified table function name
+ *
+ * @return the (unqualified) name of this table function
+ */
public String vtiTable() { return _vtiTable; }
- /** Return the text of the statement which invoked the table function */
+ /**
+ * Return the text of the statement which invoked the table function
+ *
+ * @return the text of the statement which invoked this table function
+ */
public String statementText() { return _statementText; }
}
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIEnvironment.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIEnvironment.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIEnvironment.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIEnvironment.java Thu Jun 14 23:29:38 2018
@@ -39,17 +39,23 @@ public interface VTIEnvironment
/**
Return true if this instance of the Table Function has been created for compilation,
false if it is for runtime execution.
+
+ @return true if this instance of the Table Function has been created for compilation
*/
public boolean isCompileTime();
/**
Return the SQL text of the original SQL statement.
+
+ @return the SQL text of the original SQL statement
*/
public String getOriginalSQL();
/**
Get the specific JDBC isolation of the statement. If it returns Connection.TRANSACTION_NONE
then no isolation was specified and the connection's isolation level is implied.
+
+ @return the specific JDBC isolation of the statement
*/
public int getStatementIsolationLevel();
@@ -59,11 +65,17 @@ public interface VTIEnvironment
Any previous value associated with the key is discarded.
Any saved object can be seen by any JDBC Connection that has a Statement object
that references the same statement plan.
+
+ @param key Key into a cache of context variables
+ @param value Value to associate with the key
*/
public void setSharedState(String key, java.io.Serializable value);
/**
Get an object associated with a key from set of objects maintained with the statement plan.
+
+ @param key Key into a cache of context variables
+ @return the value associated with the key
*/
public Object getSharedState(String key);
}
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIMetaDataTemplate.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIMetaDataTemplate.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIMetaDataTemplate.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTIMetaDataTemplate.java Thu Jun 14 23:29:38 2018
@@ -297,6 +297,9 @@ public abstract class VTIMetaDataTemplat
* <p>
* Create a SQLException saying that the calling method is not implemented.
* </p>
+ *
+ * @param methodName The name of the unimplemented method
+ * @return a SQLFeatureNotSupportedException
*/
protected SQLException notImplemented( String methodName )
{
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTITemplate.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTITemplate.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTITemplate.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/VTITemplate.java Thu Jun 14 23:29:38 2018
@@ -301,6 +301,10 @@ public abstract class VTITemplate impl
* <p>
* Create a SQLException saying that the calling method is not implemented.
* </p>
+ *
+ * @param methodName Name of method
+ *
+ * @return a SQLFeatureNotSupportedException
*/
protected SQLException notImplemented( String methodName )
{
@@ -312,6 +316,11 @@ public abstract class VTITemplate impl
* Get an array of descriptors for the return table shape declared for this
* AwareVTI by its CREATE FUNCTION statement.
* </p>
+ *
+ * @param currentConnection The current connection to Derby
+ *
+ * @return an array of descriptors of the columns returned by this VTI.
+ * @throws SQLException on error
*/
public ColumnDescriptor[] getReturnTableSignature( Connection currentConnection )
throws SQLException
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/XmlVTI.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/XmlVTI.java?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/XmlVTI.java (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/XmlVTI.java Thu Jun 14 23:29:38 2018
@@ -225,21 +225,49 @@ public class XmlVTI extends StringCo
//
///////////////////////////////////////////////////////////////////////////////////
- /** This is the static method for creating functions from a file name and child tags */
+ /**
+ * This is the static method for creating functions from a file name and child tags
+ *
+ * @param fileName The file containing the XML text
+ * @param rowTag The tag on the outermost element defining the row
+ * @param childTags The nested attributes and elements corresponding to columns in the row
+ *
+ * @return a VTI to turn the XML text into rows
+ * @throws Exception on error
+ */
public static XmlVTI xmlVTI( String fileName, String rowTag, String... childTags )
throws Exception
{
return xmlVTI( fileName, rowTag, null, asList( childTags ) );
}
- /** This is the static method for creating functions from an url and child tags */
+ /**
+ * This is the static method for creating functions from an url and child tags
+ *
+ * @param urlString An URL which locates the XML text
+ * @param rowTag The tag on the outermost element defining the row
+ * @param childTags The nested attributes and elements corresponding to columns in the row
+ *
+ * @return a VTI to turn the XML text into rows
+ * @throws Exception on error
+ */
public static XmlVTI xmlVTIFromURL( String urlString, String rowTag, String... childTags )
throws Exception
{
return xmlVTIFromURL( urlString, rowTag, null, asList( childTags ) );
}
- /** This is the static method for creating functions from a file name and both parent and child tags */
+ /**
+ * This is the static method for creating functions from a file name and both parent and child tags
+ *
+ * @param fileName Name of file which holds the XML text
+ * @param rowTag The base element for the row
+ * @param parentTags The names of parent tags
+ * @param childTags The names of child tags
+ *
+ * @return a VTI to turn the XML text into rows
+ * @throws Exception on error
+ */
public static XmlVTI xmlVTI
( final String fileName, String rowTag, ArrayList<String> parentTags, ArrayList<String> childTags )
throws Exception
@@ -260,7 +288,17 @@ public class XmlVTI extends StringCo
return xmlVTI( fis, rowTag, parentTags, childTags );
}
- /** This is the static method for creating functions from an URL and both parent and child tags */
+ /**
+ * This is the static method for creating functions from an URL and both parent and child tags
+ *
+ * @param urlString An URL which locates the XML text
+ * @param rowTag The base element for the row
+ * @param parentTags The names of parent tags
+ * @param childTags The names of child tags
+ *
+ * @return a VTI to turn the XML text into rows
+ * @throws Exception on error
+ */
public static XmlVTI xmlVTIFromURL
( final String urlString, String rowTag, ArrayList<String> parentTags, ArrayList<String> childTags )
throws Exception
@@ -281,7 +319,17 @@ public class XmlVTI extends StringCo
return xmlVTI( is, rowTag, parentTags, childTags );
}
- /** This is the static method for creating functions from an URL and both parent and child tags */
+ /**
+ * This is the static method for creating functions from an URL and both parent and child tags
+ *
+ * @param xmlResource The XML text as a stream
+ * @param rowTag The base element for the row
+ * @param parentTags The names of parent tags
+ * @param childTags The names of child tags
+ *
+ * @return a VTI to turn the XML text into rows
+ * @throws Exception on error
+ */
private static XmlVTI xmlVTI
( InputStream xmlResource, String rowTag, ArrayList<String> parentTags, ArrayList<String> childTags )
throws Exception
@@ -297,7 +345,13 @@ public class XmlVTI extends StringCo
return new XmlVTI( xmlResource, rowTag, parentTags.size(), allTags );
}
- /** Factory method to create an ArrayList<String> */
+ /**
+ * Factory method to create an ArrayList<String>
+ *
+ * @param cells The items to put on the list
+ *
+ * @return a list containing those items
+ */
public static ArrayList<String> asList( String... cells )
{
ArrayList<String> retval = new ArrayList<String>();
@@ -316,6 +370,11 @@ public class XmlVTI extends StringCo
* <p>
* Get the string value of the column in the current row identified by the 1-based columnNumber.
* </p>
+ *
+ * @param columnNumber The 1-based column index in the row
+ *
+ * @return the column value as a string
+ * @throws SQLException on error
*/
protected String getRawColumn( int columnNumber ) throws SQLException
{
Modified: db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/package.html
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/package.html?rev=1833569&r1=1833568&r2=1833569&view=diff
==============================================================================
--- db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/package.html (original)
+++ db/derby/code/trunk/java/org.apache.derby.engine/org/apache/derby/vti/package.html Thu Jun 14 23:29:38 2018
@@ -47,7 +47,7 @@ or they could be non-relational data fee
Here is an example of how to declare and invoke a Table Function:
</P>
-<BLOCKQUOTE><PRE><FONT color="blue" size="+1"><B>
+<BLOCKQUOTE><PRE style="color:blue; fontsize:125%;"><B>
CREATE FUNCTION externalEmployees
()
RETURNS TABLE
@@ -66,7 +66,7 @@ EXTERNAL NAME 'com.acme.hrSchema.Employe
INSERT INTO employees
SELECT s.*
FROM TABLE (externalEmployees() ) s;
-</B></FONT></PRE></BLOCKQUOTE>
+</B></PRE></BLOCKQUOTE>
<P>
The Derby optimizer makes some assumptions about these Table Functions: