db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From krist...@apache.org
Subject svn commit: r537831 - in /db/derby/code/trunk/java: engine/org/apache/derby/impl/jdbc/ testing/org/apache/derbyTesting/functionTests/tests/jdbcapi/
Date Mon, 14 May 2007 13:35:05 GMT
Author: kristwaa
Date: Mon May 14 06:35:04 2007
New Revision: 537831

URL: http://svn.apache.org/viewvc?view=rev&rev=537831
Log:
DERBY-2346: JavaDoc updates/fixes.
Patch file: derby-2346-4a_javadoc.diff

Modified:
    db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobAsciiStream.java
    db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobStreamControl.java
    db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUpdateableReader.java
    db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUtf8Writer.java
    db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedClob.java
    db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBInputStream.java
    db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBStreamControl.java
    db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/UTF8Reader.java
    db/derby/code/trunk/java/testing/org/apache/derbyTesting/functionTests/tests/jdbcapi/ClobUpdateableReaderTest.java

Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobAsciiStream.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobAsciiStream.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobAsciiStream.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobAsciiStream.java Mon May
14 06:35:04 2007
@@ -27,6 +27,7 @@
 import java.io.Writer;
 
 final class ClobAsciiStream extends OutputStream {
+
     private Writer writer;
     
     ClobAsciiStream (Writer writer){
@@ -34,11 +35,12 @@
     }
 
     /**
-     * Writes the specified byte to this output stream. The general 
-     * contract for <code>write</code> is that one byte is written 
-     * to the output stream. The byte to be written is the eight 
-     * low-order bits of the argument <code>b</code>. The 24 
-     * high-order bits of <code>b</code> are ignored.
+     * Writes the specified byte to this output stream.
+     * <p>
+     * The general contract for <code>write</code> is that one byte is written
+     * to the output stream. The byte to be written is the eight low-order bits
+     * of the argument <code>b</code>. The 24 high-order bits of <code>b</code>
+     * are ignored.
      * <p>
      * Subclasses of <code>OutputStream</code> must provide an 
      * implementation for this method. 
@@ -55,6 +57,7 @@
     /**
      * Writes <code>len</code> bytes from the specified byte array 
      * starting at offset <code>off</code> to this output stream. 
+     * <p>
      * The general contract for <code>write(b, off, len)</code> is that 
      * some of the bytes in the array <code>b</code> are written to the 
      * output stream in order; element <code>b[off]</code> is the first 

Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobStreamControl.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobStreamControl.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobStreamControl.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobStreamControl.java Mon
May 14 06:35:04 2007
@@ -37,10 +37,13 @@
 final class ClobStreamControl extends LOBStreamControl {
     
     private ConnectionChild conChild;
+
     /**
-     * Constructs ClobStreamControl
-     * @param dbName 
-     * @param conChild
+     * Constructs a <code>ClobStreamControl</code> object used to perform
+     * operations on a CLOB value.
+     *
+     * @param dbName name of the database the CLOB value belongs to
+     * @param conChild connection object used to obtain synchronization object
      */
     ClobStreamControl (String dbName, ConnectionChild conChild) {
         super (dbName);
@@ -48,11 +51,12 @@
     }        
     
     /**
-     * Finds the positon in bytes for a utf8 char postion starting 
-     * from startPos (bytes).
-     * @param startPos in bytes
-     * @param charPos in chars
-     * @return stream position for the given char position
+     * Finds the corresponding byte position for the given UTF-8 character
+     * position, starting from the byte position <code>startPos</code>.
+     *
+     * @param startPos start position in number of bytes
+     * @param charPos character position
+     * @return Stream position in bytes for the given character position.
      * @throws IOException
      */
     synchronized long getStreamPosition (long startPos, long charPos) throws IOException
{
@@ -93,10 +97,12 @@
     }
     
     /**
-     * constructs and returns a writer.
-     * @param pos 
-     * @return Writer
-     * @throws IOException, SQLException
+     * Constructs and returns a <code>Writer</code> for the CLOB value.
+     *
+     * @param pos the initial position in bytes for the <code>Writer</code>
+     * @return A <code>Writer</code> to write to the CLOB value.
+     * @throws IOException
+     * @throws SQLException if the specified position is invalid
      */
     synchronized Writer getWriter (long pos) throws IOException, SQLException {
         long charPos = getStreamPosition (0, pos);
@@ -107,13 +113,13 @@
     }
     
     /**
-     * Construct and return a <code>Reader</code>.
+     * Constructs and returns a <code>Reader</code>.
      * @param pos initial position of the returned <code>Reader</code> in
      *      number of characters
      * @return A <code>Reader</code> with the underlying <code>CLOB</code>
      *      value as source.
      * @throws IOException
-     * @throws SQLException
+     * @throws SQLException if the specified position is invalid
      */
     Reader getReader (long pos) throws IOException, SQLException {
         Reader isr = new ClobUpdateableReader (

Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUpdateableReader.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUpdateableReader.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUpdateableReader.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUpdateableReader.java Mon
May 14 06:35:04 2007
@@ -26,22 +26,30 @@
 import java.io.Reader;
 
 /**
- * ClobUpdateableReader is used to create Reader over InputStream. This class is
- * aware that underlying stream can be modified and reinitializes itsef if it 
- * detects any change in stream hence invalidating the cache so the changes are 
- * reflected immidiatly.
+ * <code>ClobUpdateableReader</code> is used to create a <code>Reader</code>
+ * over a <code>LOBInputStream</code>.
+ * <p>
+ * This class is aware that the underlying stream can be modified and
+ * reinitializes itself if it detects any change in the stream. This
+ * invalidates the cache so the changes are reflected immediately.
+ *
+ * @see LOBInputStream
  */
-
 final class ClobUpdateableReader extends Reader {
     
+    /** Reader accessing the Clob data and doing the work. */
     private Reader streamReader;
+    /** Character position of this reader. */
     private long pos;
+    /** Underlying stream of byte data. */
     private LOBInputStream stream;
+    /** Connection object used to obtain synchronization-object. */
     private ConnectionChild conChild;
     
     /**
-     * Constructs a Reader over a LOBInputStream.
-     * @param stream 
+     * Constructs a <code>Reader</code> over a <code>LOBInputStream</code>.
+     * @param stream underlying stream of byte data
+     * @param conChild a connection object used to obtain synchronization-object
      * @throws IOException
      */
     ClobUpdateableReader (LOBInputStream stream, ConnectionChild conChild)
@@ -82,8 +90,8 @@
     
     /**
      * Initializes the streamReader and skips to the given position.
-     * @param skip 
-     * @throws IOException
+     * @param skip number of characters to skip to reach initial position
+     * @throws IOException if a streaming error occurs
      */
     private void init(long skip) throws IOException {
         streamReader = new UTF8Reader (stream, 0, stream.length (), 

Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUtf8Writer.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUtf8Writer.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUtf8Writer.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/ClobUtf8Writer.java Mon May
14 06:35:04 2007
@@ -31,7 +31,7 @@
 import org.apache.derby.iapi.services.i18n.MessageService;
 
 /**
- * Writer implementation for Clob.
+ * Writer implementation for <code>Clob</code>.
  */
 final class ClobUtf8Writer extends Writer {
     private ClobStreamControl control;    
@@ -40,8 +40,9 @@
     
     /**
      * Constructor.
-     * @param control 
-     * @param pos 
+     *
+     * @param control worker object for the CLOB value
+     * @param pos initial <b>byte</b> position in the CLOB value
      */
     ClobUtf8Writer(ClobStreamControl control, long pos) {
         this.control = control;
@@ -50,31 +51,31 @@
     }    
 
     /**
-     * Flushes the stream.  If the stream has saved any characters from the
-     * various write() methods in a buffer, write them immediately to their
-     * intended destination.  Then, if that destination is another character or
-     * byte stream, flush it.  Thus one flush() invocation will flush all the
-     * buffers in a chain of Writers and OutputStreams.
-     * 
-     * <p> If the intended destination of this stream is an abstraction provided
-     * by the underlying operating system, for example a file, then flushing the
-     * stream guarantees only that bytes previously written to the stream are
-     * passed to the operating system for writing; it does not guarantee that
-     * they are actually written to a physical device such as a disk drive.
-     * 
-     * @throws IOException
-     *          If an I/O error occurs
+     * Flushes the stream.
+     * <p>
+     * Flushing the stream after {@link #close} has been called will cause an
+     * exception to be thrown.
+     * <p>
+     * <i>Implementation note:</i> In the current implementation, this is a
+     * no-op. Flushing is left to the underlying stream(s). Note that when
+     * programming against/with this class, always follow good practice and call
+     * <code>flush</code>.
+     *
+     * @throws IOException if the stream has been closed
      */
     public void flush() throws IOException {
         if (closed)
             throw new IOException (
                 MessageService.getTextMessage (SQLState.LANG_STREAM_CLOSED));
-        //no op
+        // A no-op.
+        // Flushing is currently the responsibility of the underlying stream(s).
     }
 
     /**
-     * Closes the stream, flushing it first. Once the stream has been closed,
-     * further write() or flush() invocations will cause an IOException to be
+     * Closes the stream.
+     * <p>
+     * Once the stream has been closed, further <code>write</code> or 
+     * {@link #flush} invocations will cause an <code>IOException</code> to be
      * thrown. Closing a previously closed stream has no effect.
      */
     public void close() {
@@ -82,16 +83,13 @@
     }
 
     /**
-     * Writes a portion of an array of characters.
+     * Writes a portion of an array of characters to the CLOB value.
      * 
-     * @param cbuf
-     *         Array of characters
-     * @param off
-     *         Offset from which to start writing characters
-     * @param len
-     *         Number of characters to write
-     * @throws IOException
-     *          If an I/O error occurs
+     * @param cbuf array of characters
+     * @param off offset into <code>cbuf</code> from which to start writing
+     *      characters
+     * @param len number of characters to write
+     * @throws IOException if an I/O error occurs
      */
     public void write(char[] cbuf, int off, int len) throws IOException {
         if (closed)

Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedClob.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedClob.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedClob.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/EmbedClob.java Mon May 14 06:35:04
2007
@@ -48,10 +48,10 @@
     If its data is small (less than 1 page) it is a byte array taken from
     the SQLChar class. If it is large (more than 1 page) it is a long column
     in the database. The long column is accessed as a stream, and is implemented
-    in store as an OverflowInputStream.  The Resetable interface allows sending
+    in store as an OverflowInputStream. The Resetable interface allows sending
     messages to that stream to initialize itself (reopen its container and
     lock the corresponding row) and to reset itself to the beginning.
-
+    <p>
     NOTE: In the case that the data is large, it is represented as a stream.
     This stream can be returned to the user in the getAsciiStream() method.
     This means that we have limited control over the state of the stream,
@@ -106,7 +106,8 @@
     }
     
     /**
-     * This constructor should only be called by EmbedResultSet.getClob
+     * This constructor should only be called by {@link EmbedResultSet#getClob}.
+     *
      * @param dvd 
      * @param con 
      * @throws StandardException

Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBInputStream.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBInputStream.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBInputStream.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBInputStream.java Mon May
14 06:35:04 2007
@@ -30,8 +30,9 @@
 import org.apache.derby.shared.common.error.ExceptionUtil;
 
 /**
- * This input stream is built on top of LOBStreamControl. All the read methods
- * are routed to LOBStreamControl.
+ * This input stream is built on top of {@link LOBStreamControl}.
+ * <p>
+ * All the read methods are routed to {@link LOBStreamControl}.
  */
 
 public class LOBInputStream extends InputStream {

Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBStreamControl.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBStreamControl.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBStreamControl.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/LOBStreamControl.java Mon May
14 06:35:04 2007
@@ -377,14 +377,18 @@
     }
     
     /**
-     * Replaces bytes in the middle of the lob.The new byte array may not be 
-     * be of same length as the original bytes, so it may result in resizing 
-     * the total length.
+     * Replaces a block of bytes in the middle of the LOB with a another block
+     * of bytes, which may be of a different size.
+     * <p>
+     * The new byte array may not be be of same length as the original,
+     * thus it may result in resizing the total lob.
+     *
      * @param buf byte array which will be written inplace of old block
-     * @param stPos starting pisition of old block
-     * @param endPos end position of old block
-     * @return newposition new write position 
-     * @throws IOExcepton, SQLException
+     * @param stPos inclusive starting position of current block
+     * @param endPos exclusive end position of current block
+     * @return Current position after write.
+     * @throws IOExcepton if writing to temporary file fails
+     * @throws SQLException
      */
     synchronized long replaceBytes (byte [] buf, long stPos, long endPos) 
                                             throws IOException, SQLException {
@@ -445,7 +449,8 @@
     /**
      * Returns the running secquence number to check if the lob is updated since
      * last access.
-     * @return newcount
+     *
+     * @return The current update sequence number.
      */
     long getUpdateCount() {
         return updateCount;

Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/UTF8Reader.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/UTF8Reader.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/UTF8Reader.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/jdbc/UTF8Reader.java Mon May 14
06:35:04 2007
@@ -67,32 +67,33 @@
 			this.utfLen = readUnsignedShort();
 		}
 	}
-        
+
     /**
-     * Constructs a UTF8Reader using a stream. This consturctor accepts 
-     * the stream size as paramater and doesn't attempts to read the lenght 
-     * from the stream.
-     * @param in InputStream
-     * @param maxFieldSize 
-     * @param streamSize size of the stream
-     * @param parent connectionChild this stream is associated with
+     * Constructs a <code>UTF8Reader</code> using a stream.
+     * <p>
+     * This consturctor accepts the stream size as parameter and doesn't
+     * attempt to read the length from the stream.
+     *
+     * @param in the underlying stream
+     * @param maxFieldSize the maximum allowed length for the associated column
+     * @param streamSize size of the underlying stream in bytes
+     * @param parent the connection child this stream is associated with
      * @param synchronization object to synchronize on
-     * @throws IOException
      */
-        public UTF8Reader(
+    public UTF8Reader(
                 InputStream in,
                 long maxFieldSize,
                 long streamSize,
-                ConnectionChild      parent,                
+                ConnectionChild parent,
                 Object synchronization)
                 throws IOException {
-            super(synchronization);
-            
-            this.in     = new BufferedInputStream (in);
-            this.maxFieldSize = maxFieldSize;
-            this.parent = parent;
-            this.utfLen = streamSize;
-        }
+        super(synchronization);
+
+        this.in = new BufferedInputStream(in);
+        this.maxFieldSize = maxFieldSize;
+        this.parent = parent;
+        this.utfLen = streamSize;
+    }
 
 	/*
 	** Reader implemention.

Modified: db/derby/code/trunk/java/testing/org/apache/derbyTesting/functionTests/tests/jdbcapi/ClobUpdateableReaderTest.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/testing/org/apache/derbyTesting/functionTests/tests/jdbcapi/ClobUpdateableReaderTest.java?view=diff&rev=537831&r1=537830&r2=537831
==============================================================================
--- db/derby/code/trunk/java/testing/org/apache/derbyTesting/functionTests/tests/jdbcapi/ClobUpdateableReaderTest.java
(original)
+++ db/derby/code/trunk/java/testing/org/apache/derbyTesting/functionTests/tests/jdbcapi/ClobUpdateableReaderTest.java
Mon May 14 06:35:04 2007
@@ -1,6 +1,6 @@
 /*
  *
- * Derby - Class ClobUpdateableReaderTest
+ * Derby - Class org.apache.derbyTesting.functionTests.tests.jdbcapi.ClobUpdateableReaderTest
  *
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
@@ -33,7 +33,8 @@
 import org.apache.derbyTesting.junit.TestConfiguration;
 
 /**
- * Test class to test Updateable Reader for Clob in embedder driver.
+ * Test class to test <code>UpdateableReader</code> for <code>Clob</code>
in
+ * embedded driver.
  */
 public class ClobUpdateableReaderTest extends BaseJDBCTestCase {
     
@@ -124,6 +125,11 @@
         }
     }   
     
+    /**
+     * Generates a (static) string containing various Unicode characters.
+     *
+     * @return a string with ASCII and non-ASCII characters
+     */
     private String getUnicodeString () {
         char[] fill = new char[4];
         fill[0] = 'd';          // 1 byte UTF8 character (ASCII)
@@ -139,7 +145,8 @@
     
     /**
      * Setup the test.
-     * @throws a SQLException.
+     *
+     * @throws SQLException if database access fails
      */
     public void setUp() throws Exception {
         Connection con = getConnection ();
@@ -156,6 +163,9 @@
                     ClobUpdateableReaderTest.class);
     }        
 
+    /**
+     * Cleans up the database.
+     */
     protected void tearDown() throws java.lang.Exception {
         Connection con = getConnection ();
         Statement stmt = con.createStatement ();



Mime
View raw message