oracle.sql

## Class CHAR

- java.lang.Object
- - oracle.sql.Datum
  - - oracle.sql.CHAR

All Implemented Interfaces:
  Serializable

    public class CHAR
    extends Datum

The Oracle specific representation of characters. The class extends oracle.sql.Datum and interprets the bytes according to one of the Oracle supported character sets. Each object of type oracle.sql.CHAR contains an indication of what character set to use in interpreting the bytes so one class can be used for all the variations, such as National Character Set, Client, Database, etc.

For conversions that are not supported directly by CHAR (e.g. "best effort" conversions from String), if the programer wants a "best attempt" even when the conversion looses information, the "withReplacement" methods of oracle.sql.CharacterSet can be used directly.

See Also:
  `CharacterSet`, Serialized Form

### Field Summary

Fields
`static CharacterSet` `DEFAULT_CHARSET`

### Fields inherited from class oracle.sql.Datum

`ojiOracleDatumWithConnection, targetDatum`

### Constructor Summary

Constructors
`protected` `CHAR()`
`` `CHAR(Object obj, CharacterSet charSet)` Construct a CHAR from an Object.
`` `CHAR(String str, CharacterSet charSet)` Constructor for CHAR.
`` `CHAR(String str, CharacterSet charSet, int len)` Constructor for CHAR.

### Method Summary

All Methods Instance Methods Concrete Methods
`InputStream` `asciiStreamValue()` Convert to an ascii stream representation of the datum object
`BigDecimal` `bigDecimalValue()` Convert this data object into a BigDecimal.
`InputStream` `binaryStreamValue()` Convert to a binary stream representation of the datum object
`boolean` `booleanValue()` Convert to a boolean representation of the datum object
`byte` `byteValue()` Convert to a byte representation of the datum object
`Reader` `characterStreamValue()` Convert to a character stream representation of the datum object
`Date` `dateValue()` Convert to a Date representation of the datum object
`double` `doubleValue()` Convert to a double representation of the datum object
`float` `floatValue()` Convert to a float representation of the datum object
`protected oracle.jdbc.internal.OracleConnection` `getConnectionDuringExceptionHandling()`
`String` `getString()` Converts the sequence of characters represented by this to a String.
`int` `intValue()` Convert to a integer representation of the datum object
`boolean` `isConvertibleTo(Class<?> jClass)` Test whether this data object can be converted to the specified Java data type.
`boolean` `isVariableLength()` Determines if this instance represents a variable or fixed length character sequence.
`long` `longValue()` Convert to a long representation of the datum object
`int` `oracleId()` The integer that identifies the character set.
`void` `setVariableLength(boolean variableLength)` Sets a flag to indicate if this instance represents a fixed or variable length character sequence.
`String` `stringValue()` Convert this data object into a String.
`Timestamp` `timestampValue()` Convert to a Timestamp representation of the datum object
`Time` `timeValue()` Convert to a Time representation of the datum object
`Object` `toJdbc()` Convert this data object into its default Java object type.
`String` `toString()` Converts the characters to a String.

### Methods inherited from class oracle.sql.Datum

`bytesEqual, bytesHashCode, compareBytes, getBytes, getLength, getStream, isNull, setBytes, setShareBytes, shareBytes, stringValue, timestampValue, timeValue, toClass`

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

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

### Field Detail

#### DEFAULT_CHARSET

    public static final CharacterSet DEFAULT_CHARSET

### Constructor Detail

#### CHAR

    protected CHAR()

#### CHAR

    public CHAR(String str,
                CharacterSet charSet,
                int len)
         throws SQLException

Constructor for CHAR.
Similar to CHAR(String str, CharacterSet charSet) Added parameter len. This CHAR constructor will space pad the CHAR object up to the length specificed by len.

Parameters:
  `str` - the sequence of characters (represented in Unicode).
  `charSet` - the CharacterSet to which the string should be converted.

  if charSet is null, default charset will be used. The default charset choose we8iso8859p1 as Oracle Utiliites charset.

  `len` - the length that the CHAR object will be space padded up to
Throws:
  `SQLException` - if the attempt to convert str to charSet throws an exception.

#### CHAR

    public CHAR(String str,
                CharacterSet charSet)
         throws SQLException

Constructor for CHAR.
The String is first converted to the indicated character set. No provision is made for loss if the CharacterSet cannot represent all Unicode characters. Although perhaps some time in the future it may throw an exception in that case.

Parameters:
  `str` - the sequence of characters (represented in Unicode).
  `charSet` - the CharacterSet to which the string should be converted.

  if charSet is null, default charset will be used. The default charset choose we8iso8859p1 as Oracle Utiliites charset.

Throws:
  `SQLException` - if the attempt to convert str to charSet throws an exception.

#### CHAR

    public CHAR(Object obj,
                CharacterSet charSet)
         throws SQLException

Construct a CHAR from an Object.

Parameters:
  `obj` - input data from which this class instance is constructed. This constructor calls obj.toString() to obtain the input string.
  `charSet` - character set of the CHAR to be created.
Throws:
  `SQLException` - if the input argument 'obj' is an instance of an unsupported class, or if the input object cannot be converted into a CHAR.

### Method Detail

#### oracleId

    public int oracleId()

The integer that identifies the character set.

Returns:
  Oracle character set ID

#### getString

    public String getString()
                     throws SQLException

Converts the sequence of characters represented by this to a String.

Returns:
  a String containing the Unicode characters represented in this.
Throws:
  `SQLException` - if conversion from this.oracleId to UTF is not supported
  `SQLException` - if the particular cannot characters cannot be converted without loss to Unicode.

#### toString

    public String toString()

Converts the characters to a String. Attempts to use getString, but if that throws an exception presents a hex representation of the individual bytes.

Overrides:
  `toString` in class `Object`

#### toJdbc

    public Object toJdbc()
                  throws SQLException

Convert this data object into its default Java object type.

Specified by:
  `toJdbc` in class `Datum`
Returns:
  the data value as a (fill in the blank) object.
Throws:
  `SQLException` - if any of the lower layer code throws an exception.

#### isConvertibleTo

    public boolean isConvertibleTo(Class<?> jClass)

Test whether this data object can be converted to the specified Java data type.

Specified by:
  `isConvertibleTo` in class `Datum`
Parameters:
  `jClass` - specifies the Java data type to test against.
Returns:
  true if this data object is convertible to the specified Java class, and a corresponding xxxValue() method is available; otherwise, a false is returned.

#### stringValue

    public String stringValue()

Convert this data object into a String.

Overrides:
  `stringValue` in class `Datum`
Returns:
  the data value in String representation.

#### booleanValue

    public boolean booleanValue()
                         throws SQLException

Convert to a boolean representation of the datum object

Overrides:
  `booleanValue` in class `Datum`
Returns:
  boolean representation of the datum object
Throws:
  `SQLException,` - if no boolean representation exists
  `SQLException`

#### intValue

    public int intValue()
                 throws SQLException

Convert to a integer representation of the datum object

Overrides:
  `intValue` in class `Datum`
Returns:
  integer representation of the datum object
Throws:
  `SQLException,` - if no integer representation exists
  `SQLException`

#### longValue

    public long longValue()
                   throws SQLException

Convert to a long representation of the datum object

Overrides:
  `longValue` in class `Datum`
Returns:
  long representation of the datum object
Throws:
  `SQLException,` - if no long representation exists
  `SQLException`

#### floatValue

    public float floatValue()
                     throws SQLException

Convert to a float representation of the datum object

Overrides:
  `floatValue` in class `Datum`
Returns:
  float representation of the datum object
Throws:
  `SQLException,` - if no float representation exists
  `SQLException`

#### doubleValue

    public double doubleValue()
                       throws SQLException

Convert to a double representation of the datum object

Overrides:
  `doubleValue` in class `Datum`
Returns:
  double representation of the datum object
Throws:
  `SQLException,` - if no double representation exists
  `SQLException`

#### byteValue

    public byte byteValue()
                   throws SQLException

Convert to a byte representation of the datum object

Overrides:
  `byteValue` in class `Datum`
Returns:
  byte representation of the datum object
Throws:
  `SQLException,` - if no byte representation exists
  `SQLException`

#### dateValue

    public Date dateValue()
                   throws SQLException

Convert to a Date representation of the datum object

Overrides:
  `dateValue` in class `Datum`
Returns:
  java.sql.Date representation of the datum object
Throws:
  `SQLException,` - if no Date representation exists
  `SQLException`

#### timeValue

    public Time timeValue()
                   throws SQLException

Convert to a Time representation of the datum object

Overrides:
  `timeValue` in class `Datum`
Returns:
  java.sql.Time representation of the datum object
Throws:
  `SQLException,` - if no Time representation exists
  `SQLException`

#### timestampValue

    public Timestamp timestampValue()
                             throws SQLException

Convert to a Timestamp representation of the datum object

Overrides:
  `timestampValue` in class `Datum`
Returns:
  java.sql.Timestamp representation of the datum object
Throws:
  `SQLException,` - if no Timestamp representation exists
  `SQLException`

#### bigDecimalValue

    public BigDecimal bigDecimalValue()
                               throws SQLException

Convert this data object into a BigDecimal.

Overrides:
  `bigDecimalValue` in class `Datum`
Returns:
  the data value in BigDecimal representation.
Throws:
  `SQLException`

#### characterStreamValue

    public Reader characterStreamValue()
                                throws SQLException

Convert to a character stream representation of the datum object

Overrides:
  `characterStreamValue` in class `Datum`
Returns:
  character stream representation of the datum object
Throws:
  `SQLException,` - if no character stream representation exists
  `SQLException`

#### asciiStreamValue

    public InputStream asciiStreamValue()
                                 throws SQLException

Convert to an ascii stream representation of the datum object

Overrides:
  `asciiStreamValue` in class `Datum`
Returns:
  ascii stream representation of the datum object
Throws:
  `SQLException,` - if no ascii stream representation exists
  `SQLException`

#### binaryStreamValue

    public InputStream binaryStreamValue()
                                  throws SQLException

Convert to a binary stream representation of the datum object

Overrides:
  `binaryStreamValue` in class `Datum`
Returns:
  binary stream representation of the datum object
Throws:
  `SQLException,` - if no binary stream representation exists
  `SQLException`

#### getConnectionDuringExceptionHandling

    protected oracle.jdbc.internal.OracleConnection getConnectionDuringExceptionHandling()

Overrides:
  `getConnectionDuringExceptionHandling` in class `Datum`

#### setVariableLength

    public void setVariableLength(boolean variableLength)

Sets a flag to indicate if this instance represents a fixed or variable length character sequence.

Parameters:
  `variableLength` - True for variable length or false for fixed length.

#### isVariableLength

    public boolean isVariableLength()

Determines if this instance represents a variable or fixed length character sequence.

Returns:
  True if variable length or false if fixed length.

Copyright © 2008, 2020, Oracle and/or its affiliates. All rights reserved.