Package org.acplt.oncrpc

## Class XdrDecodingStream

- java.lang.Object
- - org.acplt.oncrpc.XdrDecodingStream

- Direct Known Subclasses:
    `XdrBufferDecodingStream`, `XdrHttpDecodingStream`, `XdrTcpDecodingStream`, `XdrUdpDecodingStream`

      public abstract class XdrDecodingStream
      extends java.lang.Object

  Defines the abstract base class for all decoding XDR streams. A decoding XDR stream returns data in the form of Java data types which it reads from a data source (for instance, network or memory buffer) in the platform-independent XDR format.

  Derived classes need to implement the `xdrDecodeInt()`, `xdrDecodeOpaque(int)` and `xdrDecodeOpaque(byte[], int, int)` methods to make this complete mess workable.

  Version:
    $Revision: 1.3 $ $Date: 2003/08/14 13:48:33 $ $State: Exp $ $Locker: $
  Author:
    Harald Albrecht

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `private java.lang.String` | `characterEncoding` | Encoding to use when deserializing strings or `null` if the system's default encoding should be used.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XdrDecodingStream()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract void` | `beginDecoding()` | Initiates decoding of the next XDR record.
    `void` | `close()` | Closes this decoding XDR stream and releases any system resources associated with this stream.
    `void` | `endDecoding()` | End decoding of the current XDR record.
    `java.lang.String` | `getCharacterEncoding()` | Get the character encoding for deserializing strings.
    `abstract java.net.InetAddress` | `getSenderAddress()` | Returns the Internet address of the sender of the current XDR data.
    `abstract int` | `getSenderPort()` | Returns the port number of the sender of the current XDR data.
    `void` | `setCharacterEncoding​(java.lang.String characterEncoding)` | Set the character encoding for deserializing strings.
    `boolean` | `xdrDecodeBoolean()` | Decodes (aka "deserializes") a boolean read from a XDR stream.
    `boolean[]` | `xdrDecodeBooleanFixedVector​(int length)` | Decodes (aka "deserializes") a vector of booleans read from a XDR stream.
    `boolean[]` | `xdrDecodeBooleanVector()` | Decodes (aka "deserializes") a vector of booleans read from a XDR stream.
    `byte` | `xdrDecodeByte()` | Decodes (aka "deserializes") a byte read from this XDR stream.
    `byte[]` | `xdrDecodeByteFixedVector​(int length)` | Decodes (aka "deserializes") a vector of bytes, which is nothing more than a series of octets (or 8 bits wide bytes), each packed into its very own 4 bytes (XDR int).
    `byte[]` | `xdrDecodeByteVector()` | Decodes (aka "deserializes") a vector of bytes, which is nothing more than a series of octets (or 8 bits wide bytes), each packed into its very own 4 bytes (XDR int).
    `double` | `xdrDecodeDouble()` | Decodes (aka "deserializes") a double (which is a 64 bits wide floating point entity) read from a XDR stream.
    `double[]` | `xdrDecodeDoubleFixedVector​(int length)` | Decodes (aka "deserializes") a vector of doubles read from a XDR stream.
    `double[]` | `xdrDecodeDoubleVector()` | Decodes (aka "deserializes") a vector of doubles read from a XDR stream.
    `byte[]` | `xdrDecodeDynamicOpaque()` | Decodes (aka "deserializes") a XDR opaque value, which is represented by a vector of byte values.
    `float` | `xdrDecodeFloat()` | Decodes (aka "deserializes") a float (which is a 32 bits wide floating point entity) read from a XDR stream.
    `float[]` | `xdrDecodeFloatFixedVector​(int length)` | Decodes (aka "deserializes") a vector of floats read from a XDR stream.
    `float[]` | `xdrDecodeFloatVector()` | Decodes (aka "deserializes") a vector of floats read from a XDR stream.
    `abstract int` | `xdrDecodeInt()` | Decodes (aka "deserializes") a "XDR int" value received from a XDR stream.
    `int[]` | `xdrDecodeIntFixedVector​(int length)` | Decodes (aka "deserializes") a vector of ints read from a XDR stream.
    `int[]` | `xdrDecodeIntVector()` | Decodes (aka "deserializes") a vector of ints read from a XDR stream.
    `long` | `xdrDecodeLong()` | Decodes (aka "deserializes") a long (which is called a "hyper" in XDR babble and is 64 bits wide) read from a XDR stream.
    `long[]` | `xdrDecodeLongFixedVector​(int length)` | Decodes (aka "deserializes") a vector of longs read from a XDR stream.
    `long[]` | `xdrDecodeLongVector()` | Decodes (aka "deserializes") a vector of longs read from a XDR stream.
    `void` | `xdrDecodeOpaque​(byte[] opaque)` | Decodes (aka "deserializes") a XDR opaque value, which is represented by a vector of byte values.
    `abstract void` | `xdrDecodeOpaque​(byte[] opaque, int offset, int length)` | Decodes (aka "deserializes") a XDR opaque value, which is represented by a vector of byte values, and starts at `offset` with a length of `length`.
    `abstract byte[]` | `xdrDecodeOpaque​(int length)` | Decodes (aka "deserializes") an opaque value, which is nothing more than a series of octets (or 8 bits wide bytes).
    `short` | `xdrDecodeShort()` | Decodes (aka "deserializes") a short (which is a 16 bit quantity) read from this XDR stream.
    `short[]` | `xdrDecodeShortFixedVector​(int length)` | Decodes (aka "deserializes") a vector of short integers read from a XDR stream.
    `short[]` | `xdrDecodeShortVector()` | Decodes (aka "deserializes") a vector of short integers read from a XDR stream.
    `java.lang.String` | `xdrDecodeString()` | Decodes (aka "deserializes") a string read from a XDR stream.
    `java.lang.String[]` | `xdrDecodeStringFixedVector​(int length)` | Decodes (aka "deserializes") a vector of strings read from a XDR stream.
    `java.lang.String[]` | `xdrDecodeStringVector()` | Decodes (aka "deserializes") a vector of strings read from a XDR stream.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### characterEncoding

          private java.lang.String characterEncoding

      Encoding to use when deserializing strings or `null` if the system's default encoding should be used.

  - ### Constructor Detail

    - #### XdrDecodingStream

          public XdrDecodingStream()

  - ### Method Detail

    - #### getSenderAddress

          public abstract java.net.InetAddress getSenderAddress()

      Returns the Internet address of the sender of the current XDR data. This method should only be called after `beginDecoding()`, otherwise it might return stale information.
      Returns:
        InetAddress of the sender of the current XDR data.

    - #### getSenderPort

          public abstract int getSenderPort()

      Returns the port number of the sender of the current XDR data. This method should only be called after `beginDecoding()`, otherwise it might return stale information.
      Returns:
        Port number of the sender of the current XDR data.

    - #### beginDecoding

          public abstract void beginDecoding()
                                      throws OncRpcException,
                                             java.io.IOException

      Initiates decoding of the next XDR record. This typically involves filling the internal buffer with the next datagram from the network, or reading the next chunk of data from a stream-oriented connection. In case of memory-based communication this might involve waiting for some other process to fill the buffer and signal availability of new XDR data.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### endDecoding

          public void endDecoding()
                           throws OncRpcException,
                                  java.io.IOException

      End decoding of the current XDR record. The general contract of `endDecoding` is that calling it is an indication that the current record is no more interesting to the caller and any allocated data for this record can be freed.

      The `endDecoding` method of `XdrDecodingStream` does nothing.

      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### close

          public void close()
                     throws OncRpcException,
                            java.io.IOException

      Closes this decoding XDR stream and releases any system resources associated with this stream. The general contract of `close` is that it closes the decoding XDR stream. A closed XDR stream cannot perform decoding operations and cannot be reopened.

      The `close` method of `XdrDecodingStream` does nothing.

      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeInt

          public abstract int xdrDecodeInt()
                                    throws OncRpcException,
                                           java.io.IOException

      Decodes (aka "deserializes") a "XDR int" value received from a XDR stream. A XDR int is 32 bits wide -- the same width Java's "int" data type has. This method is one of the basic methods all other methods can rely on. Because it's so basic, derived classes have to implement it.
      Returns:
        The decoded int value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeOpaque

          public abstract byte[] xdrDecodeOpaque​(int length)
                                          throws OncRpcException,
                                                 java.io.IOException

      Decodes (aka "deserializes") an opaque value, which is nothing more than a series of octets (or 8 bits wide bytes). Because the length of the opaque value is given, we don't need to retrieve it from the XDR stream.

      Note that this is a basic abstract method, which needs to be implemented in derived classes.

      Parameters:
        `length` - Length of opaque data to decode.
      Returns:
        Opaque data as a byte vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeOpaque

          public abstract void xdrDecodeOpaque​(byte[] opaque,
                                               int offset,
                                               int length)
                                        throws OncRpcException,
                                               java.io.IOException

      Decodes (aka "deserializes") a XDR opaque value, which is represented by a vector of byte values, and starts at `offset` with a length of `length`. Only the opaque value is decoded, so the caller has to know how long the opaque value will be. The decoded data is always padded to be a multiple of four (because that's what the sender does).

      Derived classes must ensure that the proper semantic is maintained.

      Parameters:
        `opaque` - Byte vector which will receive the decoded opaque value.
        `offset` - Start offset in the byte vector.
        `length` - the number of bytes to decode.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IndexOutOfBoundsException` - if the given `opaque` byte vector isn't large enough to receive the result.

    - #### xdrDecodeOpaque

          public final void xdrDecodeOpaque​(byte[] opaque)
                                     throws OncRpcException,
                                            java.io.IOException

      Decodes (aka "deserializes") a XDR opaque value, which is represented by a vector of byte values. Only the opaque value is decoded, so the caller has to know how long the opaque value will be. The decoded data is always padded to be a multiple of four (because that's what the sender does).
      Parameters:
        `opaque` - Byte vector which will receive the decoded opaque value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeDynamicOpaque

          public final byte[] xdrDecodeDynamicOpaque()
                                              throws OncRpcException,
                                                     java.io.IOException

      Decodes (aka "deserializes") a XDR opaque value, which is represented by a vector of byte values. The length of the opaque value to decode is pulled off of the XDR stream, so the caller does not need to know the exact length in advance. The decoded data is always padded to be a multiple of four (because that's what the sender does).
      Returns:
        The byte vector containing the decoded data.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeByteVector

          public final byte[] xdrDecodeByteVector()
                                           throws OncRpcException,
                                                  java.io.IOException

      Decodes (aka "deserializes") a vector of bytes, which is nothing more than a series of octets (or 8 bits wide bytes), each packed into its very own 4 bytes (XDR int). Byte vectors are decoded together with a preceeding length value. This way the receiver doesn't need to know the length of the vector in advance.
      Returns:
        The byte vector containing the decoded data.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeByteFixedVector

          public final byte[] xdrDecodeByteFixedVector​(int length)
                                                throws OncRpcException,
                                                       java.io.IOException

      Decodes (aka "deserializes") a vector of bytes, which is nothing more than a series of octets (or 8 bits wide bytes), each packed into its very own 4 bytes (XDR int).
      Parameters:
        `length` - of vector to read.
      Returns:
        The byte vector containing the decoded data.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeByte

          public final byte xdrDecodeByte()
                                   throws OncRpcException,
                                          java.io.IOException

      Decodes (aka "deserializes") a byte read from this XDR stream.
      Returns:
        Decoded byte value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeShort

          public final short xdrDecodeShort()
                                     throws OncRpcException,
                                            java.io.IOException

      Decodes (aka "deserializes") a short (which is a 16 bit quantity) read from this XDR stream.
      Returns:
        Decoded short value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeLong

          public final long xdrDecodeLong()
                                   throws OncRpcException,
                                          java.io.IOException

      Decodes (aka "deserializes") a long (which is called a "hyper" in XDR babble and is 64 bits wide) read from a XDR stream.
      Returns:
        Decoded long value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeFloat

          public final float xdrDecodeFloat()
                                     throws OncRpcException,
                                            java.io.IOException

      Decodes (aka "deserializes") a float (which is a 32 bits wide floating point entity) read from a XDR stream.
      Returns:
        Decoded float value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeDouble

          public final double xdrDecodeDouble()
                                       throws OncRpcException,
                                              java.io.IOException

      Decodes (aka "deserializes") a double (which is a 64 bits wide floating point entity) read from a XDR stream.
      Returns:
        Decoded double value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeBoolean

          public final boolean xdrDecodeBoolean()
                                         throws OncRpcException,
                                                java.io.IOException

      Decodes (aka "deserializes") a boolean read from a XDR stream.
      Returns:
        Decoded boolean value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeString

          public final java.lang.String xdrDecodeString()
                                                 throws OncRpcException,
                                                        java.io.IOException

      Decodes (aka "deserializes") a string read from a XDR stream. If a character encoding has been set for this stream, then this will be used for conversion.
      Returns:
        Decoded String value.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeShortVector

          public final short[] xdrDecodeShortVector()
                                             throws OncRpcException,
                                                    java.io.IOException

      Decodes (aka "deserializes") a vector of short integers read from a XDR stream.
      Returns:
        Decoded vector of short integers.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeShortFixedVector

          public final short[] xdrDecodeShortFixedVector​(int length)
                                                  throws OncRpcException,
                                                         java.io.IOException

      Decodes (aka "deserializes") a vector of short integers read from a XDR stream.
      Parameters:
        `length` - of vector to read.
      Returns:
        Decoded vector of short integers.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeIntVector

          public final int[] xdrDecodeIntVector()
                                         throws OncRpcException,
                                                java.io.IOException

      Decodes (aka "deserializes") a vector of ints read from a XDR stream.
      Returns:
        Decoded int vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeIntFixedVector

          public final int[] xdrDecodeIntFixedVector​(int length)
                                              throws OncRpcException,
                                                     java.io.IOException

      Decodes (aka "deserializes") a vector of ints read from a XDR stream.
      Parameters:
        `length` - of vector to read.
      Returns:
        Decoded int vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeLongVector

          public final long[] xdrDecodeLongVector()
                                           throws OncRpcException,
                                                  java.io.IOException

      Decodes (aka "deserializes") a vector of longs read from a XDR stream.
      Returns:
        Decoded long vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeLongFixedVector

          public final long[] xdrDecodeLongFixedVector​(int length)
                                                throws OncRpcException,
                                                       java.io.IOException

      Decodes (aka "deserializes") a vector of longs read from a XDR stream.
      Parameters:
        `length` - of vector to read.
      Returns:
        Decoded long vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeFloatVector

          public final float[] xdrDecodeFloatVector()
                                             throws OncRpcException,
                                                    java.io.IOException

      Decodes (aka "deserializes") a vector of floats read from a XDR stream.
      Returns:
        Decoded float vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeFloatFixedVector

          public final float[] xdrDecodeFloatFixedVector​(int length)
                                                  throws OncRpcException,
                                                         java.io.IOException

      Decodes (aka "deserializes") a vector of floats read from a XDR stream.
      Parameters:
        `length` - of vector to read.
      Returns:
        Decoded float vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeDoubleVector

          public final double[] xdrDecodeDoubleVector()
                                               throws OncRpcException,
                                                      java.io.IOException

      Decodes (aka "deserializes") a vector of doubles read from a XDR stream.
      Returns:
        Decoded double vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeDoubleFixedVector

          public final double[] xdrDecodeDoubleFixedVector​(int length)
                                                    throws OncRpcException,
                                                           java.io.IOException

      Decodes (aka "deserializes") a vector of doubles read from a XDR stream.
      Parameters:
        `length` - of vector to read.
      Returns:
        Decoded double vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeBooleanVector

          public final boolean[] xdrDecodeBooleanVector()
                                                 throws OncRpcException,
                                                        java.io.IOException

      Decodes (aka "deserializes") a vector of booleans read from a XDR stream.
      Returns:
        Decoded boolean vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeBooleanFixedVector

          public final boolean[] xdrDecodeBooleanFixedVector​(int length)
                                                      throws OncRpcException,
                                                             java.io.IOException

      Decodes (aka "deserializes") a vector of booleans read from a XDR stream.
      Parameters:
        `length` - of vector to read.
      Returns:
        Decoded boolean vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeStringVector

          public final java.lang.String[] xdrDecodeStringVector()
                                                         throws OncRpcException,
                                                                java.io.IOException

      Decodes (aka "deserializes") a vector of strings read from a XDR stream.
      Returns:
        Decoded String vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrDecodeStringFixedVector

          public final java.lang.String[] xdrDecodeStringFixedVector​(int length)
                                                              throws OncRpcException,
                                                                     java.io.IOException

      Decodes (aka "deserializes") a vector of strings read from a XDR stream.
      Parameters:
        `length` - of vector to read.
      Returns:
        Decoded String vector.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### setCharacterEncoding

          public void setCharacterEncoding​(java.lang.String characterEncoding)

      Set the character encoding for deserializing strings.
      Parameters:
        `characterEncoding` - the encoding to use for deserializing strings. If `null`, the system's default encoding is to be used.

    - #### getCharacterEncoding

          public java.lang.String getCharacterEncoding()

      Get the character encoding for deserializing strings.
      Returns:
        the encoding currently used for deserializing strings. If `null`, then the system's default encoding is used.