Package org.acplt.oncrpc

## Class XdrEncodingStream

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

- Direct Known Subclasses:
    `XdrBufferEncodingStream`, `XdrTcpEncodingStream`, `XdrUdpEncodingStream`

      public abstract class XdrEncodingStream
      extends java.lang.Object

  Defines the abstract base class for all encoding XDR streams. An encoding XDR stream receives data in the form of Java data types and writes it to a data sink (for instance, network or memory buffer) in the platform-independent XDR format.

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

  Version:
    $Revision: 1.2 $ $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 serializing strings or `null` if the system's default encoding should be used.

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `beginEncoding​(java.net.InetAddress receiverAddress, int receiverPort)` | Begins encoding a new XDR record.
    `void` | `close()` | Closes this encoding XDR stream and releases any system resources associated with this stream.
    `void` | `endEncoding()` | Flushes this encoding XDR stream and forces any buffered output bytes to be written out.
    `java.lang.String` | `getCharacterEncoding()` | Get the character encoding for serializing strings.
    `void` | `setCharacterEncoding​(java.lang.String characterEncoding)` | Set the character encoding for serializing strings.
    `void` | `xdrEncodeBoolean​(boolean value)` | Encodes (aka "serializes") a boolean and writes it down this XDR stream.
    `void` | `xdrEncodeBooleanFixedVector​(boolean[] value, int length)` | Encodes (aka "serializes") a vector of booleans and writes it down this XDR stream.
    `void` | `xdrEncodeBooleanVector​(boolean[] value)` | Encodes (aka "serializes") a vector of booleans and writes it down this XDR stream.
    `void` | `xdrEncodeByte​(byte value)` | Encodes (aka "serializes") a byte and write it down this XDR stream.
    `void` | `xdrEncodeByteFixedVector​(byte[] value, int length)` | Encodes (aka "serializes") 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).
    `void` | `xdrEncodeByteVector​(byte[] value)` | Encodes (aka "serializes") 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).
    `void` | `xdrEncodeDouble​(double value)` | Encodes (aka "serializes") a double (which is a 64 bits wide floating point quantity) and write it down this XDR stream.
    `void` | `xdrEncodeDoubleFixedVector​(double[] value, int length)` | Encodes (aka "serializes") a vector of doubles and writes it down this XDR stream.
    `void` | `xdrEncodeDoubleVector​(double[] value)` | Encodes (aka "serializes") a vector of doubles and writes it down this XDR stream.
    `void` | `xdrEncodeDynamicOpaque​(byte[] value)` | Encodes (aka "serializes") a XDR opaque value, which is represented by a vector of byte values.
    `void` | `xdrEncodeFloat​(float value)` | Encodes (aka "serializes") a float (which is a 32 bits wide floating point quantity) and write it down this XDR stream.
    `void` | `xdrEncodeFloatFixedVector​(float[] value, int length)` | Encodes (aka "serializes") a vector of floats and writes it down this XDR stream.
    `void` | `xdrEncodeFloatVector​(float[] value)` | Encodes (aka "serializes") a vector of floats and writes it down this XDR stream.
    `abstract void` | `xdrEncodeInt​(int value)` | Encodes (aka "serializes") a "XDR int" value and writes it down a XDR stream.
    `void` | `xdrEncodeIntFixedVector​(int[] value, int length)` | Encodes (aka "serializes") a vector of ints and writes it down this XDR stream.
    `void` | `xdrEncodeIntVector​(int[] value)` | Encodes (aka "serializes") a vector of ints and writes it down this XDR stream.
    `void` | `xdrEncodeLong​(long value)` | Encodes (aka "serializes") a long (which is called a "hyper" in XDR babble and is 64 bits wide) and write it down this XDR stream.
    `void` | `xdrEncodeLongFixedVector​(long[] value, int length)` | Encodes (aka "serializes") a vector of long integers and writes it down this XDR stream.
    `void` | `xdrEncodeLongVector​(long[] value)` | Encodes (aka "serializes") a vector of long integers and writes it down this XDR stream.
    `void` | `xdrEncodeOpaque​(byte[] value)` | Encodes (aka "serializes") a XDR opaque value, which is represented by a vector of byte values.
    `void` | `xdrEncodeOpaque​(byte[] value, int length)` | Encodes (aka "serializes") a XDR opaque value, which is represented by a vector of byte values.
    `abstract void` | `xdrEncodeOpaque​(byte[] value, int offset, int length)` | Encodes (aka "serializes") a XDR opaque value, which is represented by a vector of byte values, and starts at `offset` with a length of `length`.
    `void` | `xdrEncodeShort​(short value)` | Encodes (aka "serializes") a short (which is a 16 bits wide quantity) and write it down this XDR stream.
    `void` | `xdrEncodeShortFixedVector​(short[] value, int length)` | Encodes (aka "serializes") a vector of short integers and writes it down this XDR stream.
    `void` | `xdrEncodeShortVector​(short[] value)` | Encodes (aka "serializes") a vector of short integers and writes it down this XDR stream.
    `void` | `xdrEncodeString​(java.lang.String value)` | Encodes (aka "serializes") a string and writes it down this XDR stream.
    `void` | `xdrEncodeStringFixedVector​(java.lang.String[] value, int length)` | Encodes (aka "serializes") a vector of strings and writes it down this XDR stream.
    `void` | `xdrEncodeStringVector​(java.lang.String[] value)` | Encodes (aka "serializes") a vector of strings and writes it down this 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 serializing strings or `null` if the system's default encoding should be used.

  - ### Constructor Detail

    - #### XdrEncodingStream

          public XdrEncodingStream()

  - ### Method Detail

    - #### beginEncoding

          public void beginEncoding​(java.net.InetAddress receiverAddress,
                                    int receiverPort)
                             throws OncRpcException,
                                    java.io.IOException

      Begins encoding a new XDR record. This typically involves resetting this encoding XDR stream back into a known state.
      Parameters:
        `receiverAddress` - Indicates the receiver of the XDR data. This can be `null` for XDR streams connected permanently to a receiver (like in case of TCP/IP based XDR streams).
        `receiverPort` - Port number of the receiver.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### endEncoding

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

      Flushes this encoding XDR stream and forces any buffered output bytes to be written out. The general contract of `endEncoding` is that calling it is an indication that the current record is finished and any bytes previously encoded should immediately be written to their intended destination.

      The `endEncoding` method of `XdrEncodingStream` 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 encoding XDR stream and releases any system resources associated with this stream. The general contract of `close` is that it closes the encoding XDR stream. A closed XDR stream cannot perform encoding operations and cannot be reopened.

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

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

    - #### xdrEncodeInt

          public abstract void xdrEncodeInt​(int value)
                                     throws OncRpcException,
                                            java.io.IOException

      Encodes (aka "serializes") a "XDR int" value and writes it down 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.
      Parameters:
        `value` - The int value to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeOpaque

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

      Encodes (aka "serializes") 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 encoded, but no length indication is preceeding the opaque value, so the receiver has to know how long the opaque value will be. The encoded data is always padded to be a multiple of four. If the given length is not a multiple of four, zero bytes will be used for padding.

      Derived classes must ensure that the proper semantic is maintained.

      Parameters:
        `value` - The opaque value to be encoded in the form of a series of bytes.
        `offset` - Start offset in the data.
        `length` - the number of bytes to encode.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeDynamicOpaque

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

      Encodes (aka "serializes") a XDR opaque value, which is represented by a vector of byte values. The length of the opaque value is written to the XDR stream, so the receiver does not need to know the exact length in advance. The encoded data is always padded to be a multiple of four to maintain XDR alignment.
      Parameters:
        `value` - The opaque value to be encoded in the form of a series of bytes.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeOpaque

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

      Encodes (aka "serializes") a XDR opaque value, which is represented by a vector of byte values. Only the opaque value is encoded, but no length indication is preceeding the opaque value, so the receiver has to know how long the opaque value will be. The encoded data is always padded to be a multiple of four. If the length of the given byte vector is not a multiple of four, zero bytes will be used for padding.
      Parameters:
        `value` - The opaque value to be encoded in the form of a series of bytes.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeOpaque

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

      Encodes (aka "serializes") a XDR opaque value, which is represented by a vector of byte values. Only the opaque value is encoded, but no length indication is preceeding the opaque value, so the receiver has to know how long the opaque value will be. The encoded data is always padded to be a multiple of four. If the length of the given byte vector is not a multiple of four, zero bytes will be used for padding.
      Parameters:
        `value` - The opaque value to be encoded in the form of a series of bytes.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### xdrEncodeByteVector

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

      Encodes (aka "serializes") 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 encoded together with a preceeding length value. This way the receiver doesn't need to know the length of the vector in advance.
      Parameters:
        `value` - Byte vector to encode.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeByteFixedVector

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

      Encodes (aka "serializes") 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:
        `value` - Byte vector to encode.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### xdrEncodeByte

          public final void xdrEncodeByte​(byte value)
                                   throws OncRpcException,
                                          java.io.IOException

      Encodes (aka "serializes") a byte and write it down this XDR stream.
      Parameters:
        `value` - Byte value to encode.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeShort

          public final void xdrEncodeShort​(short value)
                                    throws OncRpcException,
                                           java.io.IOException

      Encodes (aka "serializes") a short (which is a 16 bits wide quantity) and write it down this XDR stream.
      Parameters:
        `value` - Short value to encode.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeLong

          public final void xdrEncodeLong​(long value)
                                   throws OncRpcException,
                                          java.io.IOException

      Encodes (aka "serializes") a long (which is called a "hyper" in XDR babble and is 64 bits wide) and write it down this XDR stream.
      Parameters:
        `value` - Long value to encode.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeFloat

          public final void xdrEncodeFloat​(float value)
                                    throws OncRpcException,
                                           java.io.IOException

      Encodes (aka "serializes") a float (which is a 32 bits wide floating point quantity) and write it down this XDR stream.
      Parameters:
        `value` - Float value to encode.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeDouble

          public final void xdrEncodeDouble​(double value)
                                     throws OncRpcException,
                                            java.io.IOException

      Encodes (aka "serializes") a double (which is a 64 bits wide floating point quantity) and write it down this XDR stream.
      Parameters:
        `value` - Double value to encode.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeBoolean

          public final void xdrEncodeBoolean​(boolean value)
                                      throws OncRpcException,
                                             java.io.IOException

      Encodes (aka "serializes") a boolean and writes it down this XDR stream.
      Parameters:
        `value` - Boolean value to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeString

          public final void xdrEncodeString​(java.lang.String value)
                                     throws OncRpcException,
                                            java.io.IOException

      Encodes (aka "serializes") a string and writes it down this XDR stream.
      Parameters:
        `value` - String value to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeShortVector

          public final void xdrEncodeShortVector​(short[] value)
                                          throws OncRpcException,
                                                 java.io.IOException

      Encodes (aka "serializes") a vector of short integers and writes it down this XDR stream.
      Parameters:
        `value` - short vector to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeShortFixedVector

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

      Encodes (aka "serializes") a vector of short integers and writes it down this XDR stream.
      Parameters:
        `value` - short vector to be encoded.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### xdrEncodeIntVector

          public final void xdrEncodeIntVector​(int[] value)
                                        throws OncRpcException,
                                               java.io.IOException

      Encodes (aka "serializes") a vector of ints and writes it down this XDR stream.
      Parameters:
        `value` - int vector to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeIntFixedVector

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

      Encodes (aka "serializes") a vector of ints and writes it down this XDR stream.
      Parameters:
        `value` - int vector to be encoded.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### xdrEncodeLongVector

          public final void xdrEncodeLongVector​(long[] value)
                                         throws OncRpcException,
                                                java.io.IOException

      Encodes (aka "serializes") a vector of long integers and writes it down this XDR stream.
      Parameters:
        `value` - long vector to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeLongFixedVector

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

      Encodes (aka "serializes") a vector of long integers and writes it down this XDR stream.
      Parameters:
        `value` - long vector to be encoded.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### xdrEncodeFloatVector

          public final void xdrEncodeFloatVector​(float[] value)
                                          throws OncRpcException,
                                                 java.io.IOException

      Encodes (aka "serializes") a vector of floats and writes it down this XDR stream.
      Parameters:
        `value` - float vector to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeFloatFixedVector

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

      Encodes (aka "serializes") a vector of floats and writes it down this XDR stream.
      Parameters:
        `value` - float vector to be encoded.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### xdrEncodeDoubleVector

          public final void xdrEncodeDoubleVector​(double[] value)
                                           throws OncRpcException,
                                                  java.io.IOException

      Encodes (aka "serializes") a vector of doubles and writes it down this XDR stream.
      Parameters:
        `value` - double vector to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeDoubleFixedVector

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

      Encodes (aka "serializes") a vector of doubles and writes it down this XDR stream.
      Parameters:
        `value` - double vector to be encoded.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### xdrEncodeBooleanVector

          public final void xdrEncodeBooleanVector​(boolean[] value)
                                            throws OncRpcException,
                                                   java.io.IOException

      Encodes (aka "serializes") a vector of booleans and writes it down this XDR stream.
      Parameters:
        `value` - long vector to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeBooleanFixedVector

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

      Encodes (aka "serializes") a vector of booleans and writes it down this XDR stream.
      Parameters:
        `value` - long vector to be encoded.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### xdrEncodeStringVector

          public final void xdrEncodeStringVector​(java.lang.String[] value)
                                           throws OncRpcException,
                                                  java.io.IOException

      Encodes (aka "serializes") a vector of strings and writes it down this XDR stream.
      Parameters:
        `value` - String vector to be encoded.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.

    - #### xdrEncodeStringFixedVector

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

      Encodes (aka "serializes") a vector of strings and writes it down this XDR stream.
      Parameters:
        `value` - String vector to be encoded.
        `length` - of vector to write. This parameter is used as a sanity check.
      Throws:
        `OncRpcException` - if an ONC/RPC error occurs.
        `java.io.IOException` - if an I/O error occurs.
        `java.lang.IllegalArgumentException` - if the length of the vector does not match the specified length.

    - #### setCharacterEncoding

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

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

    - #### getCharacterEncoding

          public java.lang.String getCharacterEncoding()

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