Package org.firebirdsql.gds.ng.fields

## Class RowDescriptorBuilder

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

-     public final class RowDescriptorBuilder
      extends java.lang.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

    All Methods Instance Methods Concrete Methods
    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​(java.lang.String fieldName)` | Sets the (aliased) field name.
    `RowDescriptorBuilder` | `setLength​(int length)` | Set the defined length of the field.
    `RowDescriptorBuilder` | `setOriginalName​(java.lang.String originalName)` | Sets the original field name.
    `RowDescriptorBuilder` | `setOriginalTableName​(java.lang.String originalTableName)` | Sets the original name of the underlying table.
    `RowDescriptorBuilder` | `setOwnerName​(java.lang.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 sub type of the field.
    `RowDescriptorBuilder` | `setTableAlias​(java.lang.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, java.lang.String originalName, java.lang.String originalTableName)` | Convenience method to populate the basic field information used in metadata result sets (eg for use in `FBDatabaseMetaData`).
    `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 Detail

    - #### 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 Detail

    - #### 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 sub type of the field.
      Parameters:
        `subType` - Sub type
      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​(java.lang.String fieldName)

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

    - #### setTableAlias

          public RowDescriptorBuilder setTableAlias​(java.lang.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​(java.lang.String originalName)

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

    - #### setOriginalTableName

          public RowDescriptorBuilder setOriginalTableName​(java.lang.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:
        `java.lang.IndexOutOfBoundsException` - When `index` is not between 0 (inclusive) and `getSize()` (exclusive)
        `java.lang.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​(java.lang.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,
                                             java.lang.String originalName,
                                             java.lang.String originalTableName)

      Convenience method to populate the basic field information used in metadata result sets (eg 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.