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

java.lang.Object
  extended by 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.