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 and Description
`RowDescriptorBuilder(int size, DatatypeCoder datatypeCoder)` Constructs an instance of RowDescriptorBuilder for `size` fields.

### Method Summary

All Methods Instance Methods Concrete Methods
`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.