/dev/null

On a Train

I saw your face
A beautiful reflection in a window
Eternal youth and grace
My gaze, transfixed, thus nudged you
From your listless sleep
I turned to see your eyes
And the grey came out of your hair
Like foam comes out of a wave
As the color faded from your face.

public interface BinaryStore
    {
    /**
    * Return the value associated with the specified key, or null if the
    * key does not have an associated value in the underlying store.
    *
    * @param binKey  key whose associated value is to be returned
    *
    * @return the value associated with the specified key, or
    *         null if no value is available for that key
    */
    public Binary load(Binary binKey);

    /**
    * Store the specified value under the specific key in the underlying
    * store. This method is intended to support both key/value creation
    * and value update for a specific key.
    *
    * @param binKey    key to store the value under
    * @param binValue  value to be stored
    *
    * @throws UnsupportedOperationException  if this implementation or the
    *         underlying store is read-only
    */
    public void store(Binary binKey, Binary binValue);

    /**
    * Remove the specified key from the underlying store if present.
    *
    * @param binKey key whose mapping is to be removed from the map
    *
    * @throws UnsupportedOperationException  if this implementation or the
    *         underlying store is read-only
    */
    public void erase(Binary binKey);

    /**
    * Remove all data from the underlying store.
    *
    * @throws UnsupportedOperationException  if this implementation or the
    *         underlying store is read-only
    */
    public void eraseAll();

    /**
    * Iterate all keys in the underlying store.
    *
    * @return a read-only iterator of the keys in the underlying store
    *
    * @throws UnsupportedOperationException  if the underlying store is not
    *         iterable
    */
    public Iterator keys();

    /**
    * If a BinaryStore is aware of the number of keys that it stores, then it
    * should implement this optional interface in order to allow that
    * information to be efficiently communicated to an intelligent consumer of
    * the BinaryStore interface.
    * 
    * @since Coherence 3.7
    */
    public interface SizeAware
            extends BinaryStore
        {
        /**
        * Determine the number of keys in the BinaryStore.
        *
        * @return the number of keys in the BinaryStore
        *
        * @since Coherence 3.7
        */
        public int size();
        }
    }

/**
* {@inheritDoc}
*/
public Object get(Object oKey)
    {
    Object  oValue   = null;
    long    ldtStart = getSafeTimeMillis();
    Binary  binValue = getBinaryStore().load(toBinary(oKey));
    if (binValue == null)
        {
        m_stats.registerMiss(ldtStart);
        }
    else
        {
        oValue = fromBinary(binValue);
        m_stats.registerHit(ldtStart);
        }
    return oValue;
    }

An AsyncBinaryStore is a BinaryStore wrapper that performs the "O" (output) portion of its I/O asynchronously on a daemon thread. The output portion consists of store and erase processing.

Since the "O" portion is passed along to the wrapped BinaryStore on a separate thread, only read operations are blocking, thus the BinaryStore operations on a whole appear much faster. As such, it is somewhat analogous to a write-behind cache.

If an operation fails on the daemon thread, all further operations will occur synchronously, so that exceptions will propagate successfully up. It is assumed that once one exception occurs, the underlying BinaryStore is in a state that will cause more exceptions to occur. Even when an exception occurs on the daemon thread, that write-behind data will not be "lost" because it will still be available in the internal data structures that keeps track of pending writes.

/**
* The Serializer interface provides the capability of reading and writing a
* Java object from and to an in-memory buffer.
* <p/>
* Serializer implementations should implement the ClassLoaderAware interface
* if they need access to a ClassLoader. However, to support hot-deploying
* containers, it is important that a Serializer <b>not</b> hold any strong
* references to that ClassLoader, or to any Class objects obtained from that
* ClassLoader.
*  
* @author cp/jh  2007.07.21
*
* @see ReadBuffer
* @see WriteBuffer
*
* @since Coherence 3.2
*/
public interface Serializer
    {
    /**
    * Serialize an object to a WriteBuffer by writing its state using the
    * specified BufferOutput object.
    *
    * @param out  the BufferOutput with which to write the object's state
    * @param o    the object to serialize
    *
    * @exception IOException  if an I/O error occurs
    */
    public void serialize(WriteBuffer.BufferOutput out, Object o)
            throws IOException;

    /**
    * Deserialize an object from a ReadBuffer by reading its state using the
    * specified BufferInput object.
    *
    * @param in  the BufferInput with which to read the object's state
    *
    * @return the deserialized user type instance
    *
    * @exception IOException  if an I/O error occurs
    */
    public Object deserialize(ReadBuffer.BufferInput in)
            throws IOException;
    }

/**
* The ReadBuffer interface represents an in-memory block of binary data,
* such as that represented by a byte[], a Binary object, or an NIO buffer.
*
* @author cp  2005.01.18
*/
public interface ReadBuffer
        extends ByteSequence, Cloneable
    {
    /**
    * Determine the length of the buffer.
    *
    * @return the number of bytes of data represented by this ReadBuffer
    */
    public int length();

    /**
    * Returns the byte at the specified offset. An offset ranges
    * from <code>0</code> to <code>length() - 1</code>. The first byte
    * of the sequence is at offset <code>0</code>, the next at offset
    * <code>1</code>, and so on, as for array indexing.
    *
    * @param of  the offset (index) of the byte
    *
    * @return the byte at the specified offset in this ReadBuffer
    *
    * @exception  IndexOutOfBoundsException  if the <code>of</code>
    *             argument is negative or not less than the length of this
    *             ReadBuffer
    */
    public byte byteAt(int of);

    /**
    * Copies bytes from this ReadBuffer into the destination byte array.
    * <p>
    * The first byte to be copied is at offset <code>ofBegin</code>;
    * the last byte to be copied is at offset <code>ofEnd-1</code>
    * (thus the total number of bytes to be copied is <code>ofEnd -
    * ofBegin</code>). The bytes are copied into the subarray of
    * <code>abDest</code> starting at offset <code>ofDest</code>
    * and ending at index:
    * <p><blockquote><pre>
    *     ofDest + (ofEnd - ofBegin) - 1
    * </pre></blockquote>
    * <p>
    * This method is the ReadBuffer equivalent of
    * {@link String#getChars(int, int, char[], int)}. It allows the caller
    * to extract a chunk of bytes into the caller's own array.
    *
    * @param ofBegin  offset of the first byte in the ReadBuffer to copy
    * @param ofEnd    offset after the last byte in the ReadBuffer to copy
    * @param abDest   the destination byte array
    * @param ofDest   the offset in the destination byte array to copy the
    *                 first byte to
    *
    * @exception IndexOutOfBoundsException  Thrown if any of the following
    *            is true:
    *   <ul>
    *   <li><code>ofBegin</code> is negative;
    *   <li><code>ofBegin</code> is greater than <code>ofEnd</code>
    *   <li><code>ofEnd</code> is greater than the length of this
    *       ReadBuffer;
    *   <li><code>ofDest</code> is negative
    *   <li><code>ofDest + (ofEnd - ofBegin)</code> is larger than
    *       <code>abDest.length</code>
    *   </ul>
    * @exception NullPointerException if <code>abDest</code> is
    *   <code>null</code>
    */
    public void copyBytes(int ofBegin, int ofEnd, byte abDest[], int ofDest);

    /**
    * Get a BufferInput object to read data from this buffer. Note that each
    * call to this method will return a new BufferInput object, with the
    * possible exception being that a zero-length ReadBuffer could always
    * return the same instance (since there is nothing to read).
    *
    * @return a BufferInput that is reading from this buffer starting at
    *         offset zero
    */
    public BufferInput getBufferInput();

    /**
    * Obtain a ReadBuffer for a portion of this ReadBuffer.
    *
    * @param of  the beginning index, inclusive
    * @param cb  the number of bytes to include in the resulting ReadBuffer
    *
    * @return a ReadBuffer that represents a portion of this ReadBuffer
    *
    * @exception  IndexOutOfBoundsException  if <code>of</code> or
    *             <code>cb</code> is negative, or <code>of + cb</code> is
    *             larger than the length of this <code>ReadBuffer</code>
    *             object
    */
    public ReadBuffer getReadBuffer(int of, int cb);

    /**
    * Get the contents of the ReadBuffer as a byte array.
    * <p>
    * This is the equivalent of <code>toByteArray(0, length())</code>.
    *
    * @return a byte[] with the contents of this ReadBuffer object
    */
    public byte[] toByteArray();

    /**
    * Get a portion of the contents of the ReadBuffer as a byte array.
    * <p>
    * This is the equivalent of
    * <code>getReadBuffer(of, cb).toByteArray()</code>.
    *
    * @param of  the beginning index, inclusive
    * @param cb  the number of bytes to include in the resulting byte[]
    *
    * @return  a byte[] containing the specified portion of this ReadBuffer
    *
    * @exception  IndexOutOfBoundsException  if <code>of</code> or
    *             <code>cb</code> is negative, or <code>of + cb</code> is
    *             larger than the length of this <code>ReadBuffer</code>
    *             object
    */
    public byte[] toByteArray(int of, int cb);

    /**
    * Returns a new Binary object that holds the complete contents of this
    * ReadBuffer.
    * <p>
    * This is the equivalent of <code>toBinary(0, length())</code>.
    *
    * @return  the contents of this ReadBuffer as a Binary object
    */
    public Binary toBinary();

    /**
    * Returns a Binary object that holds the specified portion of this
    * ReadBuffer.
    * <p>
    * This is the equivalent of
    * <code>getReadBuffer(of, cb).toBinary()</code>.
    *
    * @param of  the beginning index, inclusive
    * @param cb  the number of bytes to include in the Binary object
    *
    * @return  a Binary object containing the specified portion of this
    *          ReadBuffer
    *
    * @exception  IndexOutOfBoundsException  if <code>of</code> or
    *             <code>cb</code> is negative, or <code>of + cb</code> is
    *             larger than the length of this <code>ReadBuffer</code>
    *             object
    */
    public Binary toBinary(int of, int cb);

    /**
    * {@inheritDoc}
    * 
    * @since Coherence 3.7
    */
    public ByteSequence subSequence(int ofStart, int ofEnd);
    

    // ----- Object methods -------------------------------------------------

    /**
    * Compare two ReadBuffer objects for equality.
    *
    * @param o  a ReadBuffer object
    *
    * @return true iff the other ReadBuffer is identical to this
    */
    public boolean equals(Object o);

    /**
    * Create a clone of this ReadBuffer object.
    *
    * @return a ReadBuffer object with the same contents as this
    *         ReadBuffer object
    */
    public Object clone();


    // ----- inner interface: BufferInput -----------------------------------

    /**
    * The BufferInput interface represents a DataInputStream on top of a
    * ReadBuffer.
    *
    * @author cp  2005.01.18
    */
    public interface BufferInput
            extends InputStreaming, DataInput
        {
        // ----- InputStreaming methods ---------------------------------

        /**
        * Returns the number of bytes that can be read (or skipped over) from
        * this input stream without causing a blocking I/O condition to
        * occur. This method reflects the assumed implementation of various
        * buffering InputStreams, which can guarantee non-blocking reads up
        * to the extent of their buffers, but beyond that the read operations
        * will have to read from some underlying (and potentially blocking)
        * source.
        * <p>
        * BufferInput implementations must implement this method to return
        * the extent of the buffer that has not yet been read; in other
        * words, the entire un-read portion of the buffer <b>must</b> be
        * available.
        *
        * @return  the number of bytes that can be read from this InputStream
        *          without blocking
        *
        * @exception IOException  if an I/O error occurs
        */
        public int available()
                throws IOException;

        /**
        * Close the InputStream and release any system resources associated
        * with it.
        * <p>
        * BufferInput implementations do not pass this call down onto an
        * underlying stream, if any.
        *
        * @exception IOException  if an I/O error occurs
        */
        public void close()
                throws IOException;

        /**
        * Marks the current read position in the InputStream in order to
        * support the stream to be later "rewound" (using the {@link #reset}
        * method) to the current position. The caller passes in the maximum
        * number of bytes that it expects to read before calling the
        * {@link #reset} method, thus indicating the upper bounds of the
        * responsibility of the stream to be able to buffer what it has read
        * in order to support this functionality.
        * <p>
        * BufferInput implementations ignore the <code>cbReadLimit</code>;
        * they must support an unlimited read limit, since they appear to the
        * user as an input stream on top of a fully realized read buffer.
        *
        * @param cbReadLimit  the maximum number of bytes that caller expects
        *                     the InputStream to be able to read before the
        *                     mark position becomes invalid
        */
        public void mark(int cbReadLimit);

        /**
        * Determine if this InputStream supports the {@link #mark} and
        * {@link #reset} methods.
        * <p>
        * BufferInput implementations <b>must</b> support the {@link #mark}
        * and {@link #reset} methods, so this method always returns
        * <code>true</code>.
        *
        * @return  <code>true</code> if this InputStream supports the mark
        *          and reset method; <code>false</code> otherwise
        */
        public boolean markSupported();


        // ----- DataInput methods --------------------------------------

        /**
        * Read <code>ab.length</code> bytes and store them in
        * <code>ab</code>.
        * <p>
        * This method blocks until input data is available, the end of the
        * stream is detected, or an exception is thrown.
        *
        * @param ab  the array to store the bytes which are read from the
        *            stream
        *
        * @exception NullPointerException  if the passed array is null
        * @exception java.io.EOFException  if the stream is exhausted before the
        *            number
        *            of bytes indicated by the array length could be read
        * @exception IOException  if an I/O error occurs
        */
        public void readFully(byte ab[])
                throws IOException;

        /**
        * Read <code>cb</code> bytes and store them in <code>ab</code>
        * starting at offset <code>of</code>.
        * <p>
        * This method blocks until input data is available, the end of the
        * stream is detected, or an exception is thrown.
        *
        * @param ab  the array to store the bytes which are read from the
        *            stream
        * @param of  the offset into the array that the read bytes will be
        *            stored
        * @param cb  the maximum number of bytes to read
        *
        * @exception NullPointerException  if the passed array is null
        * @exception IndexOutOfBoundsException  if <code>of</code> or
        *            <code>cb</code> is negative, or <code>of+cb</code> is
        *            greater than the length of the <code>ab</code>
        * @exception java.io.EOFException  if the stream is exhausted before the
        *            number of bytes indicated by the array length could be
        *            read
        * @exception IOException  if an I/O error occurs
        */
        public void readFully(byte ab[], int of, int cb)
                throws IOException;

        /**
        * Skips over up to the specified number of bytes of data. The number
        * of bytes actually skipped over may be fewer than the number
        * specified to skip, and may even be zero; this can be caused by an
        * end-of-file condition, but can also occur even when there is data
        * remaining to be read. As a result, the caller should check the
        * return value from this method, which indicates the actual number of
        * bytes skipped.
        *
        * @param cb  the maximum number of bytes to skip over
        *
        * @return  the actual number of bytes that were skipped over
        *
        * @exception IOException  if an I/O error occurs
        */
        public int skipBytes(int cb)
                throws IOException;

        /**
        * Read a boolean value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeBoolean} method.
        *
        * @return either <code>true</code> or <code>false</code>
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public boolean readBoolean()
                throws IOException;

        /**
        * Read a byte value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeByte} method.
        *
        * @return a <code>byte</code> value
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public byte readByte()
                throws IOException;

        /**
        * Read an unsigned byte value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeByte} method when it is used with
        * unsigned 8-bit values.
        *
        * @return an <code>int</code> value in the range 0x00 to 0xFF
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public int readUnsignedByte()
                throws IOException;

        /**
        * Read a short value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeShort} method.
        *
        * @return a <code>short</code> value
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public short readShort()
                throws IOException;

        /**
        * Read an unsigned short value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeShort} method when it is used with
        * unsigned 16-bit values.
        *
        * @return an <code>int</code> value in the range of 0x0000 to 0xFFFF
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public int readUnsignedShort()
                throws IOException;

        /**
        * Read a char value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeChar} method.
        *
        * @return a <code>char</code> value
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public char readChar()
                throws IOException;

        /**
        * Read an int value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeInt} method.
        *
        * @return an <code>int</code> value
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public int readInt()
                throws IOException;

        /**
        * Read a long value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeLong} method.
        *
        * @return a <code>long</code> value
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public long readLong()
                throws IOException;

        /**
        * Read a float value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeFloat} method.
        *
        * @return a <code>float</code> value
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public float readFloat()
                throws IOException;

        /**
        * Read a double value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeDouble} method.
        *
        * @return a <code>double</code> value
        *
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public double readDouble()
                throws IOException;

        /**
        * Reads the next "line" of text.
        * <p>
        * This method does not have a counterpart in the
        * {@link java.io.DataOutput} interface. Furthermore, this method is
        * defined as operating on bytes and not on characters, and thus it
        * should be selected for use only after careful consideration, as if
        * it were deprecated (which it has been in java.io.DataInputStream).
        *
        * @return a line of text as a String
        * @exception  IOException  if an I/O error occurs.
        */
        public String readLine()
                throws IOException;

        /**
        * Reads a String value.
        * <p>
        * This method is the counterpart for the
        * {@link java.io.DataOutput#writeUTF} method.
        *
        * @return a String value
        *
        * @exception java.io.UTFDataFormatException  if the bytes that were
        *            read were not
        *            a valid UTF-8 encoded string
        * @exception EOFException  if the value could not be read because no
        *            more data remains to be read
        * @exception IOException  if an I/O error occurs
        */
        public String readUTF()
                throws IOException;

        // ----- BufferInput methods ------------------------------------

        /**
        * Get the ReadBuffer object that this BufferInput is reading from.
        *
        * @return the underlying ReadBuffer object
        */
        public ReadBuffer getBuffer();

        /**
        * Read a variable-length encoded UTF packed String. The major
        * differences between this implementation and DataInput is that this
        * supports null String values and is not limited to 64KB UTF-encoded
        * values.
        *
        * @return a String value; may be null
        *
        * @exception IOException  if an I/O error occurs
        */
        public String readSafeUTF()
                throws IOException;

        /**
        * Read an int value using a variable-length storage format as described
        * by {@link WriteBuffer.BufferOutput#writePackedInt(int)}.
        *
        * @return  an int value
        *
        * @exception IOException  if an I/O error occurs
        */
        public int readPackedInt()
                throws IOException;

        /**
        * Read a long value using a variable-length storage format as described
        * by {@link WriteBuffer.BufferOutput#writePackedLong(long)}.
        *
        * @return  a long value
        *
        * @exception IOException  if an I/O error occurs
        */
        public long readPackedLong()
                throws IOException;

        /**
        * Read <code>cb</code> bytes and return them as a ReadBuffer object.
        *
        * @param cb  the number of bytes to read
        *
        * @return a ReadBuffer object composed of <code>cb</code> bytes read
        *         from the BufferInput
        *
        * @exception EOFException  if the stream is exhausted before
        *            the number of bytes indicated could be read
        * @exception IOException  if an I/O error occurs
        */
        public ReadBuffer readBuffer(int cb)
                throws IOException;

        /**
        * Determine the current offset of this BufferInput within the
        * underlying ReadBuffer.
        *
        * @return the offset of the next byte to read from the ReadBuffer
        */
        public int getOffset();

        /**
        * Specify the offset of the next byte to read from the underlying
        * ReadBuffer.
        *
        * @param of  the offset of the next byte to read from the ReadBuffer
        *
        * @exception  IndexOutOfBoundsException  if <code>of < 0</code> or
        *             <code>of > getBuffer().length()</code>
        */
        public void setOffset(int of);
        }
    }

/**
* The WriteBuffer interface represents an in-memory block of binary data
* that is being accumulated (written to). It is analogous to the byte[]
* inside a Java ByteArrayOutputStream.
*
* @author cp  2005.01.18 created
* @author cp  2005.03.21 defining
*/
public interface WriteBuffer
    {
    // ----- buffer write operations ----------------------------------------

    /**
    * Store the specified byte at the specified offset within the buffer.
    * <p>
    * For purposes of side-effects and potential exceptions, this method is
    * functionally equivalent to the following code:
    * <pre><code>
    * byte[] abSrc = new byte[1];
    * abSrc[0] = b;
    * write(ofDest, abSrc, 0, abSrc.length);
    * </code></pre>
    *
    * @param ofDest  the offset within this buffer to store the passed data
    * @param b       the byte to store in this buffer
    */
    public void write(int ofDest, byte b);

    /**
    * Store the specified bytes at the specified offset within the buffer.
    * <p>
    * For purposes of side-effects and potential exceptions, this method is
    * functionally equivalent to the following code:
    * <pre><code>
    * write(ofDest, abSrc, 0, abSrc.length);
    * </code></pre>
    *
    * @param ofDest  the offset within this buffer to store the passed data
    * @param abSrc   the array of bytes to store in this buffer
    *
    * @exception NullPointerException  if <code>abSrc</code> is
    *            <code>null</code>
    * @exception IndexOutOfBoundsException  if <tt>ofDest</tt> is negative,
    *            or if <tt>ofDest + abSrc.length</tt> is
    *            greater than <tt>{@link #getMaximumCapacity()}</tt>
    */
    public void write(int ofDest, byte[] abSrc);

    /**
    * Store the specified number of bytes from the specified location within
    * the passed byte array at the specified offset within this buffer.
    * <p>
    * As a result of this method, the buffer length as reported by the
    * <tt>{@link #length()}</tt> method will become
    * <tt>Math.max({@link #length()}, ofDest + cbSrc)</tt>.
    * <p>
    * As a result of this method, the buffer capacity as reported by the
    * <tt>{@link #getCapacity()}</tt> method will not change if the new value
    * returned by <tt>{@link #length()}</tt> would not exceed the old value
    * returned by <tt>{@link #getCapacity()}</tt>; otherwise, the capacity
    * will be increased such that
    * <tt>{@link #getCapacity()} >= {@link #length()}</tt>. Regardless, it is
    * always true that <tt>{@link #getCapacity()} >= {@link #length()}</tt>
    * and <tt>{@link #getMaximumCapacity()} >= {@link #getCapacity()}</tt>.
    * If the buffer capacity cannot be increased due to resource constraints,
    * an undesignated Error or RuntimeException will be thrown, such as
    * OutOfMemoryError.
    *
    * @param ofDest  the offset within this buffer to store the passed data
    * @param abSrc   the array containing the bytes to store in this buffer
    * @param ofSrc   the offset within the passed byte array to copy from
    * @param cbSrc   the number of bytes to copy from the passed byte array
    *
    * @exception NullPointerException  if <code>abSrc</code> is
    *            <code>null</code>
    * @exception IndexOutOfBoundsException  if <tt>ofDest</tt>,
    *            <tt>ofSrc</tt> or <tt>cbSrc</tt> is negative, if
    *            <tt>ofSrc + cbSrc</tt> is greater than
    *            <tt>abSrc.length</tt>, or if <tt>ofDest + cbSrc</tt> is
    *            greater than <tt>{@link #getMaximumCapacity()}</tt>
    */
    public void write(int ofDest, byte[] abSrc, int ofSrc, int cbSrc);

    /**
    * Store the contents of the specified ReadBuffer at the specified offset
    * within this buffer.
    * <p>
    * For purposes of side-effects and potential exceptions, this method is
    * functionally equivalent to the following code:
    * <pre><code>
    * byte[] abSrc = bufSrc.toByteArray();
    * write(ofDest, abSrc, 0, abSrc.length);
    * </code></pre>
    *
    * @param ofDest  the offset within this buffer to store the passed data
    * @param bufSrc  the array of bytes to store in this buffer
    *
    * @exception NullPointerException  if <code>bufSrc</code> is
    *            <code>null</code>
    * @exception IndexOutOfBoundsException  if <tt>ofDest</tt> is negative,
    *            or if <tt>ofDest + bufSrc.length()</tt> is
    *            greater than <tt>{@link #getMaximumCapacity()}</tt>
    */
    public void write(int ofDest, ReadBuffer bufSrc);

    /**
    * Store the specified portion of the contents of the specified ReadBuffer
    * at the specified offset within this buffer.
    * <p>
    * For purposes of side-effects and potential exceptions, this method is
    * functionally equivalent to the following code:
    * <pre><code>
    * byte[] abSrc = bufSrc.toByteArray(ofSrc, cbSrc);
    * write(ofDest, abSrc, 0, abSrc.length);
    * </code></pre>
    *
    * @param ofDest  the offset within this buffer to store the passed data
    * @param bufSrc  the array of bytes to store in this buffer
    * @param ofSrc   the offset within the passed ReadBuffer to copy from
    * @param cbSrc   the number of bytes to copy from the passed ReadBuffer
    *
    * @exception NullPointerException  if <code>bufSrc</code> is
    *            <code>null</code>
    * @exception IndexOutOfBoundsException  if <tt>ofDest</tt>,
    *            <tt>ofSrc</tt> or <tt>cbSrc</tt> is negative, if
    *            <tt>ofSrc + cbSrc</tt> is greater than
    *            <tt>bufSrc.length()</tt>, or if <tt>ofDest + cbSrc</tt> is
    *            greater than <tt>{@link #getMaximumCapacity()}</tt>
    */
    public void write(int ofDest, ReadBuffer bufSrc, int ofSrc, int cbSrc);

    /**
    * Store the remaining contents of the specified InputStreaming object at
    * the specified offset within this buffer.
    * <p>
    * For purposes of side-effects and potential exceptions, this method is
    * functionally <i>similar</i> to the following code:
    * <pre><code>
    * ByteArrayOutputStream streamOut = new ByteArrayOutputStream();
    * int b;
    * while ((b = stream.read()) >= 0)
    *     {
    *     streamOut.write(b);
    *     }
    * byte[] abSrc = streamOut.toByteArray();
    * write(ofDest, abSrc, 0, abSrc.length);
    * </code></pre>
    *
    * @param ofDest  the offset within this buffer to store the passed data
    * @param stream  the stream of bytes to read and store in this buffer
    *
    * @exception IOException  if an IOException occurs reading from the
    *            passed stream
    */
    public void write(int ofDest, InputStreaming stream)
            throws IOException;

    /**
    * Store the specified number of bytes from the specified InputStreaming
    * object at the specified offset within this buffer.
    * <p>
    * For purposes of side-effects and potential exceptions, this method is
    * functionally <i>similar</i> to the following code:
    * <pre><code>
    * DataInputStream streamData = new DataInputStream(
    *         new WrapperInputStream(stream));
    * byte[] abSrc = new byte[cbSrc];
    * streamData.readFully(abSrc);
    * write(ofDest, abSrc, 0, abSrc.length);
    * </code></pre>
    *
    * @param ofDest  the offset within this buffer to store the passed data
    * @param stream  the stream of bytes to read and store in this buffer
    * @param cbSrc   the exact number of bytes to read from the stream and
    *                put in this buffer
    *
    * @exception IOException  if an IOException occurs reading from the
    *            passed stream
    */
    public void write(int ofDest, InputStreaming stream, int cbSrc)
            throws IOException;


    // ----- buffer maintenance ----------------------------------------------

    /**
    * Determine the length of the data that is in the buffer. This is the
    * actual number of bytes of data that have been written to the buffer,
    * not the capacity of the buffer.
    *
    * @return the number of bytes of data represented by this WriteBuffer
    */
    public int length();

    /**
    * Starting with the byte at offset <tt>of</tt>, retain the remainder
    * of this WriteBuffer, such that the byte at offset <tt>of</tt> is
    * shifted to offset 0, the byte at offset <tt>of + 1</tt> is shifted to
    * offset 1, and so on up to the byte at offset
    * <tt>{@link #length()} - 1</tt>, which is shifted to offset
    * <tt>{@link #length()} - of - 1</tt>. After this method, the length of
    * of the buffer as indicated by the {@link #length()} method will be
    * equal to <tt>{@link #length()} - of</tt>.
    * <p>
    * This method is functionally equivalent to the following code:
    * <pre><code>
    * retain(of, length() - of);
    * </code></pre>
    *
    * @param of  the offset of the first byte within the WriteBuffer that
    *            will be retained
    *
    * @exception IndexOutOfBoundsException  if <tt>of</tt> is negative or if
    *            <tt>of</tt> is greater than <tt>{@link #length()}</tt>
    */
    public void retain(int of);

    /**
    * Starting with the byte at offset <tt>of</tt>, retain <tt>cb</tt> bytes
    * in this WriteBuffer, such that the byte at offset <tt>of</tt> is
    * shifted to offset 0, the byte at offset <tt>of + 1</tt> is shifted to
    * offset 1, and so on up to the byte at offset <tt>of + cb - 1</tt>,
    * which is shifted to offset <tt>cb - 1</tt>. After this method, the
    * length of the buffer as indicated by the {@link #length()} method will
    * be equal to <tt>cb</tt>.
    * <p>
    * Legal values for the offset of the first byte to retain <tt>of</tt> are
    * <tt>(of >= 0 && of <= {@link #length()})</tt>. Legal values for the
    * number of bytes to retain <tt>cb</tt> are
    * <tt>(cb >= 0 && cb <= {@link #length()})</tt>, such that
    * <tt>(of + cb <= {@link #length()})</tt>.
    * <p>
    * If <tt>cb</tt> is zero, then this method will have the same effect as
    * clear. If <tt>of</tt> is zero, then this method will have the effect
    * of truncating the data in the buffer, but no bytes will be shifted
    * within the buffer.
    * <p>
    * The effect on the capacity of the buffer is implementation-specific;
    * some implementations are expected to retain the same capacity while
    * others are expected to shrink accordingly.
    *
    * @param of  the offset of the first byte within the WriteBuffer that
    *            will be retained
    * @param cb  the number of bytes to retain
    *
    * @exception IndexOutOfBoundsException  if <tt>of</tt> or <tt>cb</tt> is
    *            negative of if <tt>of + cb</tt> is greater than
    *            <tt>{@link #length()}</tt>
    */
    public void retain(int of, int cb);

    /**
    * Set the length of the buffer as indicated by the {@link #length()}
    * method to zero.
    * <p>
    * The effect on the capacity of the buffer is implementation-specific;
    * some implementations are expected to retain the same capacity while
    * others are expected to shrink accordingly.
    */
    public void clear();

    /**
    * Determine the number of bytes that the buffer can hold without resizing
    * itself. In other words, a WriteBuffer has <tt>getCapacity() -
    * {@link #length()}</tt> bytes that can be written to it without
    * overflowing the current underlying buffer allocation. Since the buffer
    * is an abstract concept, the actual mechanism for the underlying buffer
    * is not known, but it could be a Java NIO buffer, or a byte array, etc.
    * <p>
    * Note that if the maximum size returned by {@link #getMaximumCapacity()}
    * is greater than the current size returned by this method, then the
    * WriteBuffer will automatically resize itself to allocate more space
    * when the amount of data written to it passes the current size.
    *
    * @return the number of bytes of data that this WriteBuffer can hold
    *         without resizing its underlying buffer
    */
    public int getCapacity();

    /**
    * Determine the maximum number of bytes that the buffer can hold. If the
    * maximum size is greater than the current size, then the buffer is
    * expected to resize itself as necessary up to the maximum size in order
    * to contain the data given to it.
    *
    * @return the maximum number of bytes of data that the WriteBuffer can
    *         hold
    */
    public int getMaximumCapacity();


    // ----- obtaining different "write views" to the buffer ----------------

    /**
    * Obtain a WriteBuffer starting at a particular offset within this
    * WriteBuffer.
    * <p>
    * This is functionally equivalent to:
    * <code><pre>
    * return getWriteBuffer(of, getMaximumCapacity() - of);
    * </pre></code>
    *
    * @param of  the beginning index, inclusive
    *
    * @return a WriteBuffer that represents a portion of this WriteBuffer
    *
    * @exception  IndexOutOfBoundsException  if <tt>of</tt> is
    *             negative, or <tt>of</tt> is larger than the
    *             <tt>{@link #getMaximumCapacity()}</tt> of this
    *             <tt>WriteBuffer</tt> object
    */
    public WriteBuffer getWriteBuffer(int of);

    /**
    * Obtain a WriteBuffer for a portion of this WriteBuffer.
    * <p>
    * Use of the resulting buffer will correspond to using this buffer
    * directly but with the offset being passed to the buffer methods
    * automatically having <tt>of</tt> added. As a result, the length of this
    * buffer can be modified by writing to the new buffer; however, changes
    * made directly to this buffer will not affect the length of the new
    * buffer.
    * <p>
    * Note that the resulting WriteBuffer is limited in the number of bytes
    * that can be written to it; in other words, its
    * <tt>{@link #getMaximumCapacity()}</tt> must return the same value as
    * was passed in <tt>cb</tt>.
    *
    * @param of  the offset of the first byte within this WriteBuffer
    *            to map to offset 0 of the new WriteBuffer
    * @param cb  the number of bytes to cover in the resulting WriteBuffer
    *
    * @return a WriteBuffer that represents a portion of this WriteBuffer
    *
    * @exception  IndexOutOfBoundsException  if <tt>of</tt> or <tt>cb</tt>
    *             is negative, or <tt>of + cb</tt> is larger than
    *             the <tt>{@link #getMaximumCapacity()}</tt> of this
    *             <tt>WriteBuffer</tt> object
    */
    public WriteBuffer getWriteBuffer(int of, int cb);

    /**
    * Get a BufferOutput object to write data to this buffer, starting at
    * the beginning of the WriteBuffer.
    * <p>
    * This is functionally equivalent to:
    * <code><pre>
    * return getBufferOutput(0);
    * </pre></code>
    *
    * @return a BufferOutput that is writing to this buffer starting at
    *         offset zero
    */
    public BufferOutput getBufferOutput();

    /**
    * Get a BufferOutput object to write data to this buffer starting at a
    * particular offset.
    * <p>
    * Note that each call to this method will return a new BufferOutput
    * object, with the possible exception being that a zero-length
    * non-resizing WriteBuffer could always return the same instance (since
    * it is not writable).
    * <p>
    * This is functionally equivalent to:
    * <pre><code>
    * BufferOutput bufout = getBufferOutput();
    * bufout.setOffset(of);
    * return bufout;
    * </code></pre>
    *
    * @param of  the offset of the first byte of this buffer that the
    *            BufferOutput will write to
    *
    * @return a BufferOutput that will write to this buffer
    */
    public BufferOutput getBufferOutput(int of);

    /**
    * Get a BufferOutput object to write data to this buffer. The
    * BufferOutput object returned by this method is set to append to the
    * WriteBuffer, meaning that its offset is pre-set to the
    * {@link #length()} of this buffer.
    * <p>
    * This is functionally equivalent to:
    * <pre><code>
    * return getBufferOutput(length());
    * </code></pre>
    *
    * @return a BufferOutput configured to append to this buffer
    */
    public BufferOutput getAppendingBufferOutput();


    // ----- accessing the buffered data ------------------------------------

    /**
    * Get a ReadBuffer object that is a snapshot of this WriteBuffer's data.
    * <p>
    * This method is functionally equivalent to the following code:
    * <pre><code>
    * ReadBuffer buf = getUnsafeReadBuffer();
    * byte[] ab = buf.toByteArray();
    * return new ByteArrayReadBuffer(ab);
    * </code></pre>
    *
    * @return a ReadBuffer that reflects the point-in-time contents of this
    *         WriteBuffer
    */
    public ReadBuffer getReadBuffer();

    /**
    * Get a ReadBuffer object to read data from this buffer. This method is
    * not guaranteed to return a snapshot of this buffer's data, nor is it
    * guaranteed to return a live view of this buffer, which means that
    * subsequent changes to this WriteBuffer may or may not affect the
    * contents and / or the length of the returned ReadBuffer.
    * <p>
    * To get a snapshot, use the {@link #getReadBuffer()} method.
    *
    * @return a ReadBuffer that reflects the contents of this WriteBuffer
    *         but whose behavior is undefined if the WriteBuffer is modified
    */
    public ReadBuffer getUnsafeReadBuffer();

    /**
    * Returns a new byte array that holds the complete contents of this
    * WriteBuffer.
    * <p>
    * This method is functionally equivalent to the following code:
    * <pre><code>
    * return getUnsafeReadBuffer().toByteArray();
    * </code></pre>
    *
    * @return  the contents of this WriteBuffer as a byte[]
    */
    public byte[] toByteArray();

    /**
    * Returns a new Binary object that holds the complete contents of this
    * WriteBuffer.
    * <p>
    * This method is functionally equivalent to the following code:
    * <pre><code>
    * return getUnsafeReadBuffer().toBinary();
    * </code></pre>
    *
    * @return  the contents of this WriteBuffer as a Binary object
    */
    public Binary toBinary();


    // ----- Object methods -------------------------------------------------

    /**
    * Create a clone of this WriteBuffer object. Changes to the clone will
    * not affect the original, and vice-versa.
    *
    * @return a WriteBuffer object with the same contents as this
    *         WriteBuffer object
    */
    public Object clone();


    // ----- inner interface: BufferOutput ----------------------------------

    /**
    * The BufferOutput interface represents a DataOutputStream on top of a
    * WriteBuffer.
    *
    * @author cp  2005.01.18
    */
    public interface BufferOutput
            extends OutputStreaming, DataOutput
        {
        // ----- OutputStreaming methods --------------------------------

        /**
        * Close the OutputStream and release any system resources associated
        * with it.
        * <p>
        * BufferOutput implementations do not pass this call down onto an
        * underlying stream, if any.
        *
        * @exception IOException  if an I/O error occurs
        */
        public void close()
                throws IOException;

        // ----- DataOutput methods -------------------------------------

        /**
        * Writes the boolean value <tt>f</tt>.
        *
        * @param f  the boolean to be written
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeBoolean(boolean f)
                throws IOException;

        /**
        * Writes the eight low-order bits of the argument <tt>b</tt>. The 24
        * high-order bits of <tt>b</tt> are ignored.
        *
        * @param b  the byte to write (passed as an integer)
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeByte(int b)
                throws IOException;

        /**
        * Writes a short value, comprised of the 16 low-order bits of the
        * argument <tt>n</tt>; the 16 high-order bits of <tt>n</tt> are
        * ignored.
        *
        * @param n  the short to write (passed as an integer)
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeShort(int n)
                throws IOException;

        /**
        * Writes a char value, comprised of the 16 low-order bits of the
        * argument <tt>ch</tt>; the 16 high-order bits of <tt>ch</tt> are
        * ignored.
        *
        * @param ch  the char to write (passed as an integer)
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeChar(int ch)
                throws IOException;

        /**
        * Writes an int value.
        *
        * @param n  the int to write
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeInt(int n)
                throws IOException;

        /**
        * Writes a long value.
        *
        * @param l  the long to write
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeLong(long l)
                throws IOException;

        /**
        * Writes a float value.
        *
        * @param fl  the float to write
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeFloat(float fl)
                throws IOException;

        /**
        * Writes a double value.
        *
        * @param dfl  the double to write
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeDouble(double dfl)
                throws IOException;

        /**
        * Writes the String <tt>s</tt>, but only the low-order byte from each
        * character of the String is written.
        *
        * @param s  the String to write
        *
        * @exception IOException  if an I/O error occurs
        * @exception NullPointerException  if <tt>s</tt> is <tt>null</tt>
        */
        public void writeBytes(String s)
                throws IOException;

        /**
        * Writes the String <tt>s</tt> as a sequence of characters.
        *
        * @param s  the String to write
        *
        * @exception IOException  if an I/O error occurs
        * @exception NullPointerException  if <tt>s</tt> is <tt>null</tt>
        */
        public void writeChars(String s)
                throws IOException;

        /**
        * Writes the String <tt>s</tt> as a sequence of characters, but using
        * UTF-8 encoding for the characters, and including the String length
        * data so that the corresponding {@link java.io.DataInput#readUTF}
        * method can reconstitute a String from the written data.
        *
        * @param s  the String to write
        *
        * @exception IOException  if an I/O error occurs
        * @exception NullPointerException  if <tt>s</tt> is <tt>null</tt>
        */
        public void writeUTF(String s)
                throws IOException;

        // ----- BufferOutput methods -----------------------------------

        /**
        * Get the WriteBuffer object that this BufferOutput is writing to.
        *
        * @return the underlying WriteBuffer object
        */
        public WriteBuffer getBuffer();

        /**
        * Write a variable-length encoded UTF packed String. The major
        * differences between this implementation and DataOutput is that this
        * implementation supports null values and is not limited to 64KB
        * UTF-encoded values.
        * <p>
        * The binary format for a Safe UTF value is a "packed int" for the
        * binary length followed by the UTF-encoded byte stream. The length
        * is either -1 (indicating a null String) or in the range
        * <tt>0 .. Integer.MAX_VALUE</tt> (inclusive). The UTF-encoded
        * portion uses a format identical to DataOutput.
        *
        * @param s  a String value to write; may be null
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeSafeUTF(String s)
                throws IOException;

        /**
        * Write an int value using a variable-length storage-format.
        * <p>
        * The format differs from DataOutput in that DataOutput always uses
        * a fixed-length 4-byte Big Endian binary format for int values.
        * The "packed" format includes a sign bit (0x40) and a continuation
        * bit (0x80) in the first byte, followed by the least 6 significant
        * bits of the int value. Subsequent bytes (each appearing only if
        * the previous byte had its continuation bit set) include a
        * continuation bit (0x80) and the next least 7 significant bits of
        * the int value. In this way, a 32-bit value is encoded into 1-5
        * bytes, depending on the magnitude of the int value being encoded.
        *
        * @param n  an int value to write
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writePackedInt(int n)
                throws IOException;

        /**
        * Write a long value using a variable-length storage-format.
        * <p>
        * The format differs from DataOutput in that DataOutput always uses
        * a fixed-length 8-byte Big Endian binary format for long values.
        * The "packed" format includes a sign bit (0x40) and a continuation
        * bit (0x80) in the first byte, followed by the least 6 significant
        * bits of the long value. Subsequent bytes (each appearing only if
        * the previous byte had its continuation bit set) include a
        * continuation bit (0x80) and the next least 7 significant bits of
        * the long value. In this way, a 64-bit value is encoded into 1-10
        * bytes, depending on the magnitude of the long value being encoded.
        *
        * @param l  a long value to write
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writePackedLong(long l)
                throws IOException;

        /**
        * Write all the bytes from the passed ReadBuffer object.
        * <p>
        * This is functionally equivalent to the following code:
        * <code><pre>
        * getBuffer().write(getOffset(), buf);
        * </pre></code>
        *
        * @param buf  a ReadBuffer object
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeBuffer(ReadBuffer buf)
                throws IOException;

        /**
        * Write <code>cb</code> bytes from the passed ReadBuffer object
        * starting at offset <code>of</code> within the passed ReadBuffer.
        * <p>
        * This is functionally equivalent to the following code:
        * <code><pre>
        * getBuffer().write(getOffset(), buf, of, cb);
        * </pre></code>
        *
        * @param buf  a ReadBuffer object
        * @param of   the offset within the ReadBuffer of the first byte to
        *             write to this BufferOutput
        * @param cb   the number of bytes to write
        *
        * @exception IOException  if an I/O error occurs
        */
        public void writeBuffer(ReadBuffer buf, int of, int cb)
                throws IOException;

        /**
        * Write the remaining contents of the specified InputStreaming
        * object.
        * <p>
        * This is functionally equivalent to the following code:
        * <code><pre>
        * getBuffer().write(getOffset(), stream);
        * </pre></code>
        *
        * @param stream  the stream of bytes to write to this BufferOutput
        *
        * @exception IOException  if an I/O error occurs, specifically if an
        *            IOException occurs reading from the passed stream
        */
        public void writeStream(InputStreaming stream)
                throws IOException;

        /**
        * Write the specified number of bytes of the specified InputStreaming
        * object.
        * <p>
        * This is functionally equivalent to the following code:
        * <code><pre>
        * getBuffer().write(getOffset(), stream, cb);
        * </pre></code>
        *
        * @param stream  the stream of bytes to write to this BufferOutput
        * @param cb      the exact number of bytes to read from the stream
        *                and write to this BufferOutput
        *
        * @exception EOFException  if the stream is exhausted before
        *            the number of bytes indicated could be read
        * @exception IOException  if an I/O error occurs, specifically if an
        *            IOException occurs reading from the passed stream
        */
        public void writeStream(InputStreaming stream, int cb)
                throws IOException;

        /**
        * Determine the current offset of this BufferOutput within the
        * underlying WriteBuffer.
        *
        * @return the offset of the next byte to write to the WriteBuffer
        */
        public int getOffset();

        /**
        * Specify the offset of the next byte to write to the underlying
        * WriteBuffer.
        *
        * @param of  the offset of the next byte to write to the
        *            WriteBuffer
        *
        * @exception  IndexOutOfBoundsException  if <code>of < 0</code> or
        *             <code>of > getBuffer().getMaximumCapacity()</code>
        */
        public void setOffset(int of);

        // ----- constants ------------------------------------------------------

        /**
        * Maximum encoding length for a packed int value.
        */
        public static final int MAX_PACKED_INT_SIZE = 5;

        /**
        * Maximum encoding length for a packed long value.
        */
        public static final int MAX_PACKED_LONG_SIZE = 10;
        }
    }

BufferInput in = bin.getBufferInput();
String s = in.readSafeUTF();
int n = in.readInt();
Binary bin2 = in.readBuffer(n).toBinary(); // no byte[] alloc or copy!

A well-known scientist (some say it was Bertrand Russell) once gave a public lecture on astronomy. He described how the earth orbits around the sun and how the sun, in turn, orbits around the center of a vast collection of stars called our galaxy. At the end of the lecture, a little old lady at the back of the room got up and said: "What you have told us is rubbish. The world is really a flat plate supported on the back of a giant tortoise." The scientist gave a superior smile before replying, "What is the tortoise standing on?" "You're very clever, young man, very clever", said the old lady. "But it's turtles all the way down!"

protected Set> instantiateEntrySet()

/**
* Create an iterator over the keys in this Map. The Iterator must
* support remove() if the Map supports removal.
*
* @return a new instance of an Iterator over the keys in this Map
*/
protected abstract Iterator<K> iterateKeys();

/**
* Returns the value to which this map maps the specified key.
*
* @param oKey  the key object
*
* @return the value to which this map maps the specified key,
*         or null if the map contains no mapping for this key
*/
public abstract V get(Object oKey);

/**
* Associates the specified value with the specified key in this map.
*
* @param oKey    key with which the specified value is to be associated
* @param oValue  value to be associated with the specified key
*
* @return previous value associated with specified key, or <tt>null</tt>
*         if there was no mapping for key
*/
public V put(K oKey, V oValue)
    {
    throw new UnsupportedOperationException();
    }

/**
* Removes the mapping for this key from this map if present.
*
* @param oKey key whose mapping is to be removed from the map
*
* @return previous value associated with specified key, or <tt>null</tt>
*         if there was no mapping for key.  A <tt>null</tt> return can
*         also indicate that the map previously associated <tt>null</tt>
*         with the specified key, if the implementation supports
*         <tt>null</tt> values.
*/
public V remove(Object oKey)
    {
    throw new UnsupportedOperationException();
    }

/**
* Returns the number of key-value mappings in this map.
*
* @return the number of key-value mappings in this map
*/
public int size()
    {
    // this begs for sub-class optimization
    int c = 0;
    for (Iterator iter = iterateKeys(); iter.hasNext(); )
        {
        iter.next();
        ++c;
        }
    return c;
    }

/**
* Returns <tt>true</tt> if this map contains a mapping for the specified
* key.
*
* @return <tt>true</tt> if this map contains a mapping for the specified
*         key, <tt>false</tt> otherwise.
*/
public boolean containsKey(Object oKey)
    {
    // this begs for sub-class optimization
    for (Iterator iter = iterateKeys(); iter.hasNext(); )
        {
        if (equals(oKey, iter.next()))
            {
            return true;
            }
        }
    return false;
    }

/**
* Clear all key/value mappings.
*/
public void clear()
    {
    // this begs for sub-class optimization
    for (Iterator iter = iterateKeys(); iter.hasNext(); )
        {
        iter.next();
        iter.remove();
        }
    }

/**
* Returns <tt>true</tt> if this map contains no key-value mappings.
*
* @return <tt>true</tt> if this map contains no key-value mappings
*/
public boolean isEmpty()
    {
    return size() == 0;
    }

/**
* Removes the mapping for this key from this map if present. This method
* exists to allow sub-classes to optmiize remove functionalitly for
* situations in which the original value is not required.
*
* @param oKey key whose mapping is to be removed from the map
*
* @return true iff the Map changed as the result of this operation
*/
protected boolean removeBlind(Object oKey)
    {
    if (containsKey(oKey))
        {
        remove(oKey);
        return true;
        }
    else
        {
        return false;
        }
    }

/**
* Obtain a set of keys that are represented by this Map.
* <p/>
* The AbstractKeySetBasedMap only utilizes the internal key set as a
* read-only resource.
*
* @return an internal Set of keys that are contained by this Map
*/
protected abstract Set<K> getInternalKeySet();

/**
* Determine if this Iterator should remove an iterated item by calling
* remove on the internal key Set Iterator, or by calling removeBlind on
* the map itself.
*
* @return true to remove using the internal key Set Iterator or false to
*         use the {@link AbstractKeyBasedMap#removeBlind(Object)} method
*/
protected boolean isInternalKeySetIteratorMutable()
    {
    return false;
    }

/**
* Factory pattern: Create a mutable Iterator over the keys in the Map
*
* @return a new instance of Iterator that iterates over the keys in the
*         Map and supports element removal
*/
protected Iterator instantiateKeyIterator()
    {
    Iterator iter = getInternalKeySet().iterator();
    if (!isInternalKeySetIteratorMutable())
        {
        iter = new KeyIterator(iter);
        }
    return iter;
    }

The part of a typical application that is most difficult to scale is a data layer. Scaling web servers out is trivial -- you simply add more of them behind the load balancer. Because HTTP is naturally a stateless protocol, HTTP requests can be easily balanced across many machines.

The situation is similar with the application servers, but with an important difference -- in order to be able to scale application servers out, we need to make middle tier services stateless. This is not necessarily a bad thing, but it can lead to both performance and scalability problems if done incorrectly.

Unfortunately, very few services are truly stateless in real life. What is usually the case is that they need some data to process, so the common approach is for a service to load data from the data layer, process it, and persist the result back in the data layer. That means that in order to make application services stateless, we need to push all the state (even the transient state, such as HTTP sessions) to the data layer. This puts additional load on the data layer -- the more web and application servers we have, the harder our data layer will have to work to satisfy incoming requests.

The problem is that most applications use RDBMS as a data layer, and relational databases are both difficult and expensive to scale. When you use master-slave replication, clustering or sharding to scale your database, you significantly increase both the complexity and the cost of the system. Even if you use an open source database, such as MySql, you will have additional hardware and administration costs. In the case of sharding, you will also increase development cost quite a bit.

The bottom line is that relational databases were simply not designed for scale out. Even though we have come up with different solutions to scale them, all of them feel like a kludge to a certain extent, and have some fairly significant limitations.

On the other hand, Coherence and other in-memory data grids were designed with scalability as a primary goal. In the case of Coherence specifically, it is trivial to scale the cluster out by adding more machines. Coherence will dynamically repartition the cluster, which will automatically reduce both the data volume and the processing load across the cluster.

The net result is that in-memory data grids allow you to put state back into the application. This can significantly reduce the load on a database -- it is not uncommon to see database load drop 80% or more after Coherence is introduced into the architecture. They also allow you to keep transient data, such as HTTP sessions, only within the grid, reducing the load on a database even further.

Q: What would you call the enemy of innovation?

A: The first is complacency. A lot of people are satisfied with what they have. If you can convince yourself you're satisfied, you'll stop looking for a better solution. The other is an inability to listen and appreciate the complexity of a problem. Everyone wants to believe they have the answer before the question even gets asked. People don't take the time to listen and appreciate the individual complexity of each customer's problem and the nuances of their environments.

"Surely there must be a less primitive way of making big changes in the store than by pushing vast numbers of words back and forth through the von Neumann bottleneck. Not only is this tube a literal bottleneck for the data traffic of a problem, but, more importantly, it is an intellectual bottleneck that has kept us tied to word-at-a-time thinking instead of encouraging us to think in terms of the larger conceptual units of the task at hand. Thus programming is basically planning and detailing the enormous traffic of words through the von Neumann bottleneck, and much of that traffic concerns not significant data itself, but where to find it."