Module org.firebirdsql.jaybird
Package org.firebirdsql.gds.ng.fields

# Class RowDescriptorBuilder

java.lang.Object
org.firebirdsql.gds.ng.fields.RowDescriptorBuilder

public final class RowDescriptorBuilder extends Object
Builder to construct an immutable `RowDescriptor`.

The row descriptor is constructed by defining the fields, and using `addField()` to add the current field definition to the row. The field data is then reset (as if `resetField()` was called, to prepare for the next field to add.

This class can also be used to construct individual `FieldDescriptor` objects.

Since:
  3.0
Author:
  Mark Rotteveel

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RowDescriptorBuilder(int size, DatatypeCoder datatypeCoder)`
  Constructs an instance of RowDescriptorBuilder for `size` fields.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `RowDescriptorBuilder`
  `addField()`
  Adds the current field data to the row and prepares this builder for the next field by resetting all values.
  `RowDescriptorBuilder`
  `addField(FieldDescriptor fieldDescriptor)`
  Adds the `FieldDescriptor` on the current fieldIndex as the next in the row, and increments the current field index by 1.
  `RowDescriptorBuilder`
  `at(int index)`
  Convenience shortcut for `setFieldIndex(int)`.
  `RowDescriptorBuilder`
  `copyFieldFrom(FieldDescriptor sourceFieldDescriptor)`
  Set this builder with the values of the source `FieldDescriptor` for further modification through this builder.
  `int`
  `getCurrentFieldIndex()`
  `int`
  `getFirstUnprocessedIndex()`
  `int`
  `getSize()`
  `boolean`
  `isComplete()`
  `RowDescriptorBuilder`
  `resetField()`
  Resets the fields of this builder to the Java defaults.
  `RowDescriptorBuilder`
  `setFieldIndex(int index)`
  Sets the field index for the current field under construction.
  `RowDescriptorBuilder`
  `setFieldName(String fieldName)`
  Sets the (aliased) field name.
  `RowDescriptorBuilder`
  `setLength(int length)`
  Set the defined length of the field.
  `RowDescriptorBuilder`
  `setOriginalName(String originalName)`
  Sets the original field name.
  `RowDescriptorBuilder`
  `setOriginalTableName(String originalTableName)`
  Sets the original name of the underlying table.
  `RowDescriptorBuilder`
  `setOwnerName(String ownerName)`
  Sets the owner (database username) of the field.
  `RowDescriptorBuilder`
  `setScale(int scale)`
  Set the scale of the field.
  `RowDescriptorBuilder`
  `setSubType(int subType)`
  Set the Firebird subtype of the field.
  `RowDescriptorBuilder`
  `setTableAlias(String tableAlias)`
  Sets the alias of the underlying table.
  `RowDescriptorBuilder`
  `setType(int type)`
  Set the Firebird data type of the field.
  `RowDescriptorBuilder`
  `simple(int type, int length, String originalName, String originalTableName)`
  Convenience method to populate the basic field information used in metadata result sets (e.g.
  `FieldDescriptor`
  `toFieldDescriptor()`
  Creates a `FieldDescriptor` based on the current field data of this RowDescriptorBuilder.
  `RowDescriptor`
  `toRowDescriptor()`
  Constructs the `RowDescriptor` with the current content.

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

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

- ## Constructor Details

  - ### RowDescriptorBuilder

    public RowDescriptorBuilder(int size, DatatypeCoder datatypeCoder)
    Constructs an instance of RowDescriptorBuilder for `size` fields.
    Parameters:
      `size` - Number of fields
      `datatypeCoder` - DatatypeCoder for decoding field data

- ## Method Details

  - ### getSize

    public int getSize()
    Returns:
      Number of fields the row will hold.

  - ### setType

    public RowDescriptorBuilder setType(int type)
    Set the Firebird data type of the field.
    Parameters:
      `type` - Data type
    Returns:
      this builder

  - ### setSubType

    public RowDescriptorBuilder setSubType(int subType)
    Set the Firebird subtype of the field.
    Parameters:
      `subType` - Subtype
    Returns:
      this builder
    See Also:
      - `setType(int)`

  - ### setScale

    public RowDescriptorBuilder setScale(int scale)
    Set the scale of the field.
    Parameters:
      `scale` - Scale
    Returns:
      this builder
    See Also:
      - `setType(int)`

  - ### setLength

    public RowDescriptorBuilder setLength(int length)
    Set the defined length of the field.
    Parameters:
      `length` - Defined (maximum) length of the field
    Returns:
      this builder

  - ### setFieldName

    public RowDescriptorBuilder setFieldName(String fieldName)
    Sets the (aliased) field name.
    Parameters:
      `fieldName` - The field name
    Returns:
      this builder
    See Also:
      - `setOriginalName(String)`

  - ### setTableAlias

    public RowDescriptorBuilder setTableAlias(String tableAlias)
    Sets the alias of the underlying table.
    Parameters:
      `tableAlias` - The table alias
    Returns:
      this builder
    See Also:
      - `setOriginalTableName(String)`

  - ### setOriginalName

    public RowDescriptorBuilder setOriginalName(String originalName)
    Sets the original field name.
    Parameters:
      `originalName` - The original field name
    Returns:
      this builder
    See Also:
      - `setFieldName(String)`

  - ### setOriginalTableName

    public RowDescriptorBuilder setOriginalTableName(String originalTableName)
    Sets the original name of the underlying table.
    Parameters:
      `originalTableName` - The table name
    Returns:
      this builder
    See Also:
      - `setTableAlias(String)`

  - ### setFieldIndex

    public RowDescriptorBuilder setFieldIndex(int index)
    Sets the field index for the current field under construction.

    Even though `addField()` increments the current field index, it is advisable to always explicitly set the index using this method or `at(int)` as it improves readability.

    Parameters:
      `index` - Index of the field
    Returns:
      this builder
    Throws:
      `IndexOutOfBoundsException` - When `index` is not between 0 (inclusive) and `getSize()` (exclusive)
      `IllegalStateException` - When a `FieldDescriptor` is already defined on the specified `index`

  - ### at

    public RowDescriptorBuilder at(int index)
    Convenience shortcut for `setFieldIndex(int)`.
    Parameters:
      `index` - Index of the field
    Returns:
      this builder
    See Also:
      - `setFieldIndex(int)`

  - ### getCurrentFieldIndex

    public int getCurrentFieldIndex()
    Returns:
      The index for the current field

  - ### setOwnerName

    public RowDescriptorBuilder setOwnerName(String ownerName)
    Sets the owner (database username) of the field.
    Parameters:
      `ownerName` - Name of the owner
    Returns:
      this builder

  - ### simple

    public RowDescriptorBuilder simple(int type, int length, String originalName, String originalTableName)
    Convenience method to populate the basic field information used in metadata result sets (e.g. for use in `FBDatabaseMetaData`).
    Parameters:
      `type` - Firebird data type
      `length` - Defined (maximum) length of the field
      `originalName` - The original field name
      `originalTableName` - The table name
    Returns:
      this builder
    See Also:
      - `setType(int)`
      - `setLength(int)`
      - `setOriginalTableName(String)`
      - `setOriginalName(String)`

  - ### toFieldDescriptor

    public FieldDescriptor toFieldDescriptor()
    Creates a `FieldDescriptor` based on the current field data of this RowDescriptorBuilder.
    Returns:
      FieldDescriptor

  - ### resetField

    public RowDescriptorBuilder resetField()
    Resets the fields of this builder to the Java defaults.

  - ### copyFieldFrom

    public RowDescriptorBuilder copyFieldFrom(FieldDescriptor sourceFieldDescriptor)
    Set this builder with the values of the source `FieldDescriptor` for further modification through this builder.
    Parameters:
      `sourceFieldDescriptor` - Source for the initial values
    Returns:
      this builder

  - ### addField

    public RowDescriptorBuilder addField()
    Adds the current field data to the row and prepares this builder for the next field by resetting all values.
    Returns:
      this builder
    See Also:
      - `resetField()`

  - ### addField

    public RowDescriptorBuilder addField(FieldDescriptor fieldDescriptor)
    Adds the `FieldDescriptor` on the current fieldIndex as the next in the row, and increments the current field index by 1.

    This method does not call `resetField()`, so a partial definition of a field can exist inside this builder after calling this method.

    Parameters:
      `fieldDescriptor` - FieldDescriptor to add
    Returns:
      this builder

  - ### toRowDescriptor

    public RowDescriptor toRowDescriptor()
    Constructs the `RowDescriptor` with the current content.

    This method can also return a partially filled `RowDescriptor`. Caller can check for completeness by calling `isComplete()`.

    Returns:
      RowDescriptor instance.
    See Also:
      - `isComplete()`

  - ### isComplete

    public boolean isComplete()
    Returns:
      `true` when all `FieldDescriptor` entries have been defined

  - ### getFirstUnprocessedIndex

    public int getFirstUnprocessedIndex()
    Returns:
      Returns the index of the first unprocessed FieldDescriptor, or `getSize()` if all fields have been set.