IfxBSONObject
Date: 2015-03-03

com.informix.jdbc

## Class IfxBSONObject

- java.lang.Object
- - com.informix.jdbc.IfxObject
  - - com.informix.jdbc.IfxBSONObject

- All Implemented Interfaces:
    java.sql.SQLData, BSONObject

      public class IfxBSONObject
      extends com.informix.jdbc.IfxObject
      implements java.sql.SQLData, BSONObject

  The IfxBSONObject is a hybrid of both the `SQLData` interface necessary to read and write BSON data with the Informix JDBC driver and the `BSONObject` interface necessary to work with BSON objects that returned by or sent to Informix.

  Note: This class is not thread safe.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `IfxBSONObject()` A no-arg constructor is required for SQLData to work.
    `IfxBSONObject(BSONObject bsonObject)` Constructs a new object from the specified `BSONObject`.
    `IfxBSONObject(byte[] bytes)` Constructs a new object from the specified BSON-encoded byte array.
    `IfxBSONObject(byte[] bytes, boolean copyBytes)` Constructs a new object from the specified BSON-encoded byte array.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()` Clear the instance states
    `boolean` | `containsField(java.lang.String s)` Checks if this object contains a field with the given name.
    `boolean` | `containsKey(java.lang.String s)` Deprecated.
    `static IfxBSONObject` | `ensureIfxBSONObject(java.lang.Object o)` Ensures that the specified object is an `IfxBSONObject`.
    `boolean` | `equals(java.lang.Object o)` Find out whether two objects are equal.
    `void` | `fromBytes(byte[] b)`
    `void` | `fromIfx(byte[] b)`
    `void` | `fromIfx(byte[] b, int offset, int blength)`
    `void` | `fromInputStream(java.io.InputStream x, int length)`
    `void` | `fromObject(java.lang.Object data)` Initialize IfxObject with the value in obj.
    `java.lang.Object` | `get(java.lang.String key)` Gets a field from this object by a given name.
    `byte[]` | `getBytes()`
    `java.lang.String` | `getSQLTypeName()`
    `int` | `hashCode()`
    `java.util.Set<java.lang.String>` | `keySet()` Returns this object's fields' names
    `java.lang.Object` | `put(java.lang.String key, java.lang.Object v)` Sets a name/value pair in this object.
    `void` | `putAll(BSONObject o)` Sets all key/value pairs from an object into this object
    `void` | `putAll(java.util.Map<java.lang.String,java.lang.Object> m)` Sets all key/value pairs from a map into this object
    `void` | `readSQL(java.sql.SQLInput stream, java.lang.String typeName)`
    `java.lang.Object` | `removeField(java.lang.String key)` Removes a field with a given name from this object.
    `void` | `setBSONObject(BSONObject bsonObject)` Assigns the BSONObject this object represents.
    `void` | `setBytes(byte[] bytes)` Assigns the BSON-encoded byte array representation of a document.
    `void` | `setConnection(com.informix.jdbc.IfxConnection conn)` GENERIC
    `java.io.InputStream` | `toBinaryStream()`
    `byte[]` | `toBytes()`
    `byte[]` | `toIfx()`
    `byte[]` | `toIfxTuple()`
    `java.util.Map<java.lang.String,java.lang.Object>` | `toMap()` Returns a map representing this BSONObject.
    `java.lang.Object` | `toObject()`
    `java.lang.Object` | `toObject(boolean fromComplexType)` This version of toObject has a parameter that indicates if we are doing a toObject for a complex type.
    `java.lang.String` | `toString()` Convert to string.
    `void` | `writeSQL(java.sql.SQLOutput stream)`

    - ### Methods inherited from class com.informix.jdbc.IfxObject

      `clearWarning, fromAsciiStream, fromAsciiStream, fromBinaryStream, fromBinaryStream, fromBlob, fromBoolean, fromBoolean, fromByte, fromByte, fromCharacterStream, fromCharacterStream, fromClob, fromDate, fromDecimal, fromDecimal, fromDouble, fromDouble, fromFloat, fromFloat, fromIfx, fromIfx, fromIfx, fromIfx, fromInputStream, fromInt, fromInt, fromIntervalDF, fromIntervalYM, fromLong, fromLong, fromObject, fromObject, fromShort, fromShort, fromString, fromString, fromTime, fromTimestamp, get_used_in_update, getEncodedLength, getWarning, isNull, nullify, set_used_in_update, setExtendedTypeName, setIfxType, setTypeMap, toAsciiStream, toBlob, toBoolean, toByte, toCharacterStream, toClob, toDate, toDecimal, toDouble, toFloat, toIfxBSONObject, toInputStream, toInt, toInterval, toIntervalDF, toIntervalYM, toLong, toShort, toTime, toTimestamp, toUnloadString, unnullify`

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

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### IfxBSONObject

          public IfxBSONObject()

      A no-arg constructor is required for SQLData to work. Broadly speaking, this constructor should not be called.

    - #### IfxBSONObject

          public IfxBSONObject(byte[] bytes)

      Constructs a new object from the specified BSON-encoded byte array.
      Parameters:
        `bytes` - the BSON-encoded document

    - #### IfxBSONObject

          public IfxBSONObject(byte[] bytes,
                       boolean copyBytes)

      Constructs a new object from the specified BSON-encoded byte array. Optionally, copies the input byte array to a new byte array.
      Parameters:
        `bytes` - the BSON-encoded document
        `copyBytes` - if `true` the byte array is copied

    - #### IfxBSONObject

          public IfxBSONObject(BSONObject bsonObject)

      Constructs a new object from the specified `BSONObject`. It is generally preferable to use the method `ensureIfxBSONObject(Object)` as it inspects the object to see if it is already of type `IfxBSONObject`.
      Parameters:
        `bsonObject` -

  - ### Method Detail

    - #### getSQLTypeName

          public java.lang.String getSQLTypeName()
                                          throws java.sql.SQLException

      Specified by:
        `getSQLTypeName` in interface `java.sql.SQLData`
      Throws:
        `java.sql.SQLException`

    - #### readSQL

          public void readSQL(java.sql.SQLInput stream,
                     java.lang.String typeName)
                       throws java.sql.SQLException

      Specified by:
        `readSQL` in interface `java.sql.SQLData`
      Throws:
        `java.sql.SQLException`

    - #### writeSQL

          public void writeSQL(java.sql.SQLOutput stream)
                        throws java.sql.SQLException

      Specified by:
        `writeSQL` in interface `java.sql.SQLData`
      Throws:
        `java.sql.SQLException`

    - #### getBytes

          public byte[] getBytes()

    - #### setBytes

          public void setBytes(byte[] bytes)

      Assigns the BSON-encoded byte array representation of a document. The bsonObject representation is assigned the value `null`.
      Parameters:
        `bytes` - the BSON-encoded byte array representation of a document

    - #### setBSONObject

          public void setBSONObject(BSONObject bsonObject)

      Assigns the BSONObject this object represents. The BSON-encoded byte array representation is assigned the value `null`.
      Parameters:
        `bsonObject` - the document
      Throws:
        `java.lang.NullPointerException` - if the bsonObject is null

    - #### ensureIfxBSONObject

          public static IfxBSONObject ensureIfxBSONObject(java.lang.Object o)

      Ensures that the specified object is an `IfxBSONObject`. If the object is already of type `IfxBSONObject`, the object is simply cast and returned. If the object implements the `BSONObject` interface, the appropriate constructor is called and the new object is returned.
      Parameters:
        `o` -
      Returns:
      Throws:
        `java.lang.NullPointerException` - if the specified object is null
        `java.lang.IllegalArgumentException` - if the object is not of type `IfxBSONObject` and does not implement the interface `BSONObject`

    - #### toString

          public java.lang.String toString()

      Description copied from class: `com.informix.jdbc.IfxObject`
      Convert to string.
      Returns:
        the converted String object, or null on error

    - #### put

          public java.lang.Object put(java.lang.String key,
                             java.lang.Object v)

      Description copied from interface: `BSONObject`
      Sets a name/value pair in this object.
      Specified by:
        `put` in interface `BSONObject`
      Parameters:
        `key` - Name to set
        `v` - Corresponding value
      Returns:
        `v`

    - #### putAll

          public void putAll(BSONObject o)

      Description copied from interface: `BSONObject`
      Sets all key/value pairs from an object into this object
      Specified by:
        `putAll` in interface `BSONObject`
      Parameters:
        `o` - the object

    - #### putAll

          public void putAll(java.util.Map<java.lang.String,java.lang.Object> m)

      Description copied from interface: `BSONObject`
      Sets all key/value pairs from a map into this object
      Specified by:
        `putAll` in interface `BSONObject`
      Parameters:
        `m` - the map

    - #### get

          public java.lang.Object get(java.lang.String key)

      Description copied from interface: `BSONObject`
      Gets a field from this object by a given name.
      Specified by:
        `get` in interface `BSONObject`
      Parameters:
        `key` - The name of the field fetch
      Returns:
        The field, if found

    - #### toMap

          public java.util.Map<java.lang.String,java.lang.Object> toMap()

      Description copied from interface: `BSONObject`
      Returns a map representing this BSONObject.
      Specified by:
        `toMap` in interface `BSONObject`
      Returns:
        the map

    - #### removeField

          public java.lang.Object removeField(java.lang.String key)

      Description copied from interface: `BSONObject`
      Removes a field with a given name from this object.
      Specified by:
        `removeField` in interface `BSONObject`
      Parameters:
        `key` - The name of the field to remove
      Returns:
        The value removed from this object

    - #### containsKey

          @Deprecated
          public boolean containsKey(java.lang.String s)

      Deprecated.
      Description copied from interface: `BSONObject`
      Deprecated
      Specified by:
        `containsKey` in interface `BSONObject`
      Returns:
        True if the key is present

    - #### containsField

          public boolean containsField(java.lang.String s)

      Description copied from interface: `BSONObject`
      Checks if this object contains a field with the given name.
      Specified by:
        `containsField` in interface `BSONObject`
      Parameters:
        `s` - Field name for which to check
      Returns:
        True if the field is present

    - #### keySet

          public java.util.Set<java.lang.String> keySet()

      Description copied from interface: `BSONObject`
      Returns this object's fields' names
      Specified by:
        `keySet` in interface `BSONObject`
      Returns:
        The names of the fields in this object

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object o)

      Description copied from class: `com.informix.jdbc.IfxObject`
      Find out whether two objects are equal.
      Overrides:
        `equals` in class `com.informix.jdbc.IfxObject`
      Parameters:
        `o` - the other object to compare with
      Returns:
        true if the objects are equal

    - #### fromObject

          public void fromObject(java.lang.Object data)
                          throws java.sql.SQLException

      Description copied from class: `com.informix.jdbc.IfxObject`
      Initialize IfxObject with the value in obj. It does the data conversion automatically from the obj type to IfxObject type. For example: In IfxInteger(), fromObject(Object obj) { if (obj instanceof Short) fromShort((Short) obj); }
      Overrides:
        `fromObject` in class `com.informix.jdbc.IfxObject`
      Parameters:
        `data` - Convert the data value from obj to IfxObject
      Throws:
        `java.sql.SQLException`

    - #### toObject

          public java.lang.Object toObject()
                                    throws java.sql.SQLException

      Overrides:
        `toObject` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### toObject

          public java.lang.Object toObject(boolean fromComplexType)
                                    throws java.sql.SQLException

      This version of toObject has a parameter that indicates if we are doing a toObject for a complex type. If so, don't do the isDirect return udtClass, as elements 2-N need to be instantiated and returned, not just the first one over and over again.
      Overrides:
        `toObject` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### fromBytes

          public void fromBytes(byte[] b)
                         throws java.sql.SQLException

      Overrides:
        `fromBytes` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### toBytes

          public byte[] toBytes()
                         throws java.sql.SQLException

      Overrides:
        `toBytes` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### fromInputStream

          public void fromInputStream(java.io.InputStream x,
                             int length)
                               throws java.sql.SQLException

      Overrides:
        `fromInputStream` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### toBinaryStream

          public java.io.InputStream toBinaryStream()
                                             throws java.sql.SQLException

      Overrides:
        `toBinaryStream` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### clear

          public void clear()

      Description copied from class: `com.informix.jdbc.IfxObject`
      Clear the instance states
      Overrides:
        `clear` in class `com.informix.jdbc.IfxObject`

    - #### setConnection

          public void setConnection(com.informix.jdbc.IfxConnection conn)
                             throws java.sql.SQLException

      Description copied from class: `com.informix.jdbc.IfxObject`
      GENERIC
      Overrides:
        `setConnection` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### fromIfx

          public void fromIfx(byte[] b)
                       throws java.sql.SQLException

      Overrides:
        `fromIfx` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### fromIfx

          public void fromIfx(byte[] b,
                     int offset,
                     int blength)
                       throws java.sql.SQLException

      Overrides:
        `fromIfx` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### toIfx

          public byte[] toIfx()
                       throws java.sql.SQLException

      Overrides:
        `toIfx` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`

    - #### toIfxTuple

          public byte[] toIfxTuple()
                            throws java.sql.SQLException

      Overrides:
        `toIfxTuple` in class `com.informix.jdbc.IfxObject`
      Throws:
        `java.sql.SQLException`