## org.eclipse.datatools.connectivity.oda.spec.result
Class SortSpecification

    java.lang.Object
      org.eclipse.datatools.connectivity.oda.spec.result.SortSpecification

    public class SortSpecification

extends java.lang.Object

Specification of one or more dynamic sort keys of a query result set.
Its application would impact the ordering of data rows retrieved in a result set, in addition to any required sort specification expressed in a query text. This may be extended to define additional ways of expressing a sort mode or key.

Since:
  3.3 (DTP 1.8)

Field Summary
`static int` `NULL_ORDERING_FIRST`
`static int` `NULL_ORDERING_LAST`
`static int` `NULL_ORDERING_NONE` Constants that specify the null ordering specification of a sort key.
`static int` `ORDERING_ASC` The constant that specifies ascending ordering of a sort key.
`static int` `ORDERING_DESC` The constant that specifies descending ordering of a sort key.

Method Summary
`void` `addSortKey(ColumnIdentifier column, int sortDirection)` Adds a dynamic sort key for a specified result set column and sort direction.
`void` `addSortKey(ColumnIdentifier column, int sortDirection, int nullOrdering)` Adds a dynamic sort key for a specified result set column, sort direction and null ordering.
`int` `getNullOrdering(int pos)` Returns the null ordering of the sort key at the specified position.
`ColumnIdentifier` `getSortColumn(int pos)` Returns the result set column identifier of the sort key at the specified position.
`ColumnIdentifier[]` `getSortColumns()` Returns an array of all column identifiers for the sort keys.
`int` `getSortDirection()` Returns the sort direction for the sort keys of a `sortModeSingleOrder` `SortSpecification` object.
`int` `getSortDirection(int pos)` Returns the sort direction of the sort key at the specified position.
`int` `getSortKeyCount()` Returns the number of sort keys associated with this `SortSpecification` object.
`int` `getSortMode()` Returns the sort mode of this `SortSpecification` object.
`java.lang.String` `toString()`
`void` `validate(ValidationContext context)` Validates this expression in the specified context.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### ORDERING_ASC

    public static final int ORDERING_ASC

  The constant that specifies ascending ordering of a sort key.

  See Also:
    Constant Field Values

### ORDERING_DESC

    public static final int ORDERING_DESC

  The constant that specifies descending ordering of a sort key.

  See Also:
    Constant Field Values

### NULL_ORDERING_NONE

    public static final int NULL_ORDERING_NONE

  Constants that specify the null ordering specification of a sort key.

  See Also:
    Constant Field Values

### NULL_ORDERING_FIRST

    public static final int NULL_ORDERING_FIRST

See Also:
  Constant Field Values

### NULL_ORDERING_LAST

    public static final int NULL_ORDERING_LAST

See Also:
  Constant Field Values

Method Detail

### addSortKey

    public void addSortKey(ColumnIdentifier column,
                           int sortDirection)

  Adds a dynamic sort key for a specified result set column and sort direction. See `addSortKey(ColumnIdentifier, int, int)` for more description.

  Parameters:
    `column` - identifier of the result set column to apply dynamic sorting on. The specified column should be one of the columns retrieved in a result set
    `sortDirection` - constant value for the sort direction; must be one of the constant values: `ORDERING_ASC`, `ORDERING_DESC`
  See Also:
    `addSortKey(ColumnIdentifier, int, int)`

### addSortKey

    public void addSortKey(ColumnIdentifier column,
                           int sortDirection,
                           int nullOrdering)

  Adds a dynamic sort key for a specified result set column, sort direction and null ordering. The sort criteria are specified by an ODA consumer, using an ordered list of one or more sort keys. The adding sequence of each sortKey corresponds to the major-to-minor ordering. Validation is done against this sortMode if defined in constructor; i.e. this method throws an exception when adding a sort key that does not conform to a defined sortMode of this `SortSpecification`.

  Parameters:
    `column` - identifier of the result set column to apply dynamic sorting on. The specified column should be one of the columns retrieved in a result set
    `sortDirection` - constant value for the sort direction; must be one of the constant values: `ORDERING_ASC`, `ORDERING_DESC`
    `nullOrdering` - constant value for the ordering of null values vs. non-null values in the sort order; must be one of the constant values: `NULL_ORDERING_NONE`, `NULL_ORDERING_FIRST`, `NULL_ORDERING_LAST`
  Throws:
    `java.lang.NullPointerException` - if `column` is null.
    `java.lang.IllegalArgumentException` - if specified column is invalid; or if specified sortDirection or nullOrdering has invalid value.
    `java.lang.IllegalStateException` - if the sortMode of this `SortSpecification` is `IDataSetMetaData.sortModeNone`, or `IDataSetMetaData.sortModeSingleColumn`, and a sort key is already associated; or if the sortMode is `IDataSetMetaData.sortModeSingleOrder` and the sort direction does not match existing directions
  See Also:
    `addSortKey(ColumnIdentifier, int)`

### getSortMode

    public int getSortMode()

  Returns the sort mode of this `SortSpecification` object.

  Returns:
    the sort mode of this `SortSpecification`; one of `IDataSetMetaData.sortModeNone`, `IDataSetMetaData.sortModeSingleOrder`, `IDataSetMetaData.sortModeColumnOrder`, `IDataSetMetaData.sortModeSingleColumn`.

### getSortKeyCount

    public int getSortKeyCount()

  Returns the number of sort keys associated with this `SortSpecification` object.

  Returns:
    the number of sort keys associated with this `SortSpecification` object.

### getSortColumn

    public ColumnIdentifier getSortColumn(int pos)

  Returns the result set column identifier of the sort key at the specified position.

  Parameters:
    `pos` - sequence position of the sort key (1-based).
  Returns:
    the name of the result set column for the specified sort key.
  Throws:
    `java.lang.IndexOutOfBoundsException` - if `pos` is out of range (pos < 1 || pos > getSortKeyCount()).

### getSortDirection

    public int getSortDirection(int pos)

  Returns the sort direction of the sort key at the specified position.

  Parameters:
    `pos` - sequence position of the sort key (1-based)
  Returns:
    constant value of the sort direction for the specified sort key
  Throws:
    `java.lang.IndexOutOfBoundsException` - if `pos` is out of range (pos < 1 || pos > getSortKeyCount()).

### getNullOrdering

    public int getNullOrdering(int pos)

  Returns the null ordering of the sort key at the specified position.

  Parameters:
    `pos` - sequence position of the sort key (1-based)
  Returns:
    constant value of the null ordering type for the specified sort key
  Throws:
    `java.lang.IndexOutOfBoundsException` - if `pos` is out of range (pos < 1 || pos > getSortKeyCount()).

### getSortColumns

    public ColumnIdentifier[] getSortColumns()

  Returns an array of all column identifiers for the sort keys.

  Returns:
    an array of all column identifiers for the sort keys; may be an empty array if no sort keys are associated with this `SortSpecification`

### getSortDirection

    public int getSortDirection()

  Returns the sort direction for the sort keys of a `sortModeSingleOrder` `SortSpecification` object.

  Returns:
    the sort direction for the sort keys of a `sortModeSingleOrder` `SortSpecification` object; the default value, `sortAsc`, if no sort keys are associated with this `SortSpecification`.
  Throws:
    `java.lang.IllegalStateException` - if this `SortSpecification`'s sort mode is not `sortModeSingleOrder`.

### toString

    public java.lang.String toString()

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

### validate

    public void validate(ValidationContext context)
                  throws OdaException

  Validates this expression in the specified context.

  Parameters:
    `context` - context for validation; may be null which would limit the scope of validation
  Throws:
    `OdaException` - if validation failed. The concrete reason is defined by the subclass implementing this method.