com.goldencode.p2j.persist

Class SortCriterion

java.lang.Object

com.goldencode.p2j.persist.SortCriterion

public final class SortCriterion
extends java.lang.Object

An individual sort criterion, consisting of a property name, sort direction, DMO implementation class associated with an alias qualifier, getter method for the property, and a flag indicating whether case is ignored when sorting a character property. Provides static convenience methods to parse sort criteria and to produce an HQL-compliant order by clause.

Two forms of the property name are stored: the name and the orginalName. For non-indexed properties, these will be the same. For indexed properties, name is the expanded name after considering the ANSI join needed to support the sort criterion; originalName is the name as originally given before parsing. For instance, the sort criterion person.schedule[0] asc would have the following name:

    person_composite5.schedule
 

and the following originalName:

    person.schedule[0]
 

The from clause would be augmented with

    ...join person.composite5 as person_composite5...
 

and the where clause in this case would be augmented with

    ...[and/where] index(person_composite5) = 0...
 

Thus, given a DMO with a schedule field of extent 5, a basic HQL statement of

    from Person as person order by person.schedule[0] asc
 

would be expanded to

    from PersonImpl as person
    join person.composite5 as person_composite5
    where (index(person_composite5) = 0)
    order by person.empNum asc,
             upper(rtrim(person_composite5.schedule)) asc
 

(assuming schedule is a case-insensitive character field of extent 5).

Note that this class does not actually refactor the full HQL statement; it provides the sort criteria helper methods that allow the various query implementations to do so.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	SortCriterion.CacheKey Key for cached criterion lists.

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	alias DMO alias qualifier, if any
private boolean	ascending true if sort is ascending, else it is descending
private static ExpiryCache<SortCriterion.CacheKey,java.util.List<SortCriterion>>	cache Shared cache of immutable SortCriterion lists
private static java.lang.Object	cacheLock Lock for cache
private java.lang.String	computedColumnPrefix Computed column prefix for property name (optional)
private Dialect	dialect SQL dialect which used this sort criterion; used for rtrim calls on character properties
private java.lang.Class<? extends Record>	dmoClass DMO implementation class containing the sort property
private boolean	ignoreCase Is case ignored (for character property only)?
private boolean	isCharacter Is property of type character?
private java.lang.reflect.Method	method Getter method associated with sort property
private java.lang.String	name Sort property name, usually qualified
private java.lang.String	originalName Sort property name, including subscript if any, usually qualified
private java.lang.String	propertyName Unqualified property name
private int	subscript Subscript value, if any
private java.lang.String	unqualifiedName Cache the unqualified name.
private static boolean	WHERE_WITH_NULLS Flag indicating if the 'withNulls' is activated in toWhereExpression(boolean, boolean).

Constructor Summary

Constructors

Constructor and Description
SortCriterion(Dialect dialect, java.lang.String text, DmoMeta dmoInfo) Constructor which parses original sort component text, deriving the property name, sort direction, getter method for the property, case sensitivity of the property (character type only), and possibly a subscript value (for extent fields) and a composite alias name (for extent fields which are converted to use composite inner classes within the DMO).
SortCriterion(Dialect dialect, java.lang.String text, DmoMeta dmoInfo, boolean internStrings) Constructor which parses original sort component text, deriving the property name, sort direction, getter method for the property, case sensitivity of the property (character type only), and possibly a subscript value (for extent fields) and a composite alias name (for extent fields which are converted to use composite inner classes within the DMO).
SortCriterion(RecordBuffer buffer, java.lang.String text) Constructor which parses original sort component text, deriving the property name, sort direction, getter method for the property, case sensitivity of the property (character type only), and possibly a subscript value (for extent fields) and a composite alias name (for extent fields which are converted to use composite inner classes within the DMO).
SortCriterion(SortCriterion other, java.lang.String alias) Specialized constructor which takes an existing SortCriterion and create a duplicate of it but with changed alias.

Method Summary

Modifier and Type	Method and Description
(package private) static java.lang.String	assembleHQLNoPreamble(java.util.List<SortCriterion> sortCriteria, boolean invert) Assemble an HQL "order by" clause, sans the "order by" preamble, from the given list of sort criteria, optionally inverting the sort direction of the sort criteria.
(package private) java.lang.String	getAlias() Get the DMO alias.
(package private) java.lang.Class<? extends Record>	getDMOClass() Get the DMO implementation class containing the sort property for this criterion.
(package private) java.lang.reflect.Method	getMethod() Get the getter method associated with the property behind this component.
(package private) java.lang.String	getName() Get the name of the property behind this component.
(package private) java.lang.String	getOriginalName() Get the name of the property behind this component.
java.lang.String	getUnqualifiedName() Get the unqualified name of the property backing this component.
static void	initializeCache() Initializes the cache using CacheManager.
(package private) boolean	isAscending() Indicate whether component sorts in ascending order.
static boolean	isCompatible(java.lang.String sort, java.lang.String dmoAlias) Check if this sort clause contains a property of a specific DMO.
(package private) boolean	isPrimaryKey() Indicate whether this sort criterion represents the DMO's primary key.
static java.util.List<SortCriterion>	parse(Dialect dialect, java.lang.String sort, java.lang.String dmoAlias, DmoMeta dmoInfo, boolean makeUnique) Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects.
static java.util.List<SortCriterion>	parse(Dialect dialect, java.lang.String sort, java.lang.String dmoAlias, DmoMeta dmoInfo, boolean makeUnique, boolean forceUniqueAsc) Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects.
static java.util.List<SortCriterion>	parse(java.lang.String sort, RecordBuffer buffer) Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects.
(package private) static java.util.List<SortCriterion>	parse(java.lang.String sort, RecordBuffer buffer, boolean makeUnique) Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects.
(package private) static java.util.List<SortCriterion>	parse(java.lang.String sort, RecordBuffer buffer, boolean makeUnique, boolean forceUniqueAsc) Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects.
(package private) static java.lang.String	toRawSortPhrase(java.util.List<SortCriterion> sortCriteria) Generate a raw sort phrase from the given list of criteria, in the simple form:
(package private) java.lang.String	toSortExpression(boolean invert) Get a normalized string representation of the sort component.
(package private) java.lang.String	toSortExpression(boolean invert, boolean useTableAlias, boolean uniqueAlias, boolean doSpecificProcessing) Get a normalized string representation of the sort component.
java.lang.String	toString() Get a normalized string representation of the sort component.
(package private) FQLExpression	toWhereExpression(boolean rangeMatch, boolean invert) Get a string representation of this sort component which is suitable to append to a base where clause when augmenting that where clause to make it more specific.

Methods inherited from class java.lang.Object

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

Field Detail

WHERE_WITH_NULLS

private static final boolean WHERE_WITH_NULLS

Flag indicating if the 'withNulls' is activated in toWhereExpression(boolean, boolean).

cacheLock

private static final java.lang.Object cacheLock

Lock for cache

cache

private static ExpiryCache<SortCriterion.CacheKey,java.util.List<SortCriterion>> cache

Shared cache of immutable SortCriterion lists

ascending

private final boolean ascending

true if sort is ascending, else it is descending

dmoClass

private final java.lang.Class<? extends Record> dmoClass

DMO implementation class containing the sort property

method

private final java.lang.reflect.Method method

Getter method associated with sort property

isCharacter

private final boolean isCharacter

Is property of type character?

ignoreCase

private final boolean ignoreCase

Is case ignored (for character property only)?

computedColumnPrefix

private final java.lang.String computedColumnPrefix

Computed column prefix for property name (optional)

alias

private final java.lang.String alias

DMO alias qualifier, if any

propertyName

private final java.lang.String propertyName

Unqualified property name

originalName

private final java.lang.String originalName

Sort property name, including subscript if any, usually qualified

name

private final java.lang.String name

Sort property name, usually qualified

subscript

private final int subscript

Subscript value, if any

unqualifiedName

private final java.lang.String unqualifiedName

Cache the unqualified name.

dialect

private final Dialect dialect

SQL dialect which used this sort criterion; used for rtrim calls on character properties

Constructor Detail

SortCriterion

SortCriterion(RecordBuffer buffer,
              java.lang.String text)
       throws PersistenceException

Constructor which parses original sort component text, deriving the property name, sort direction, getter method for the property, case sensitivity of the property (character type only), and possibly a subscript value (for extent fields) and a composite alias name (for extent fields which are converted to use composite inner classes within the DMO).

This constructor should be used only for short-lived instances of this class. It does not intern the numerous string fields (an expensive operation), so instances created by this constructor should not be cached in memory, because the contents of these strings will be duplicated many times.

Parameters:

buffer - Record buffer.

text - Text representation of sort component, as provided by query.

Throws:

PersistenceException - if there is any error with the text representation of the sort component provided by the caller.

SortCriterion

SortCriterion(Dialect dialect,
              java.lang.String text,
              DmoMeta dmoInfo)
       throws PersistenceException

Constructor which parses original sort component text, deriving the property name, sort direction, getter method for the property, case sensitivity of the property (character type only), and possibly a subscript value (for extent fields) and a composite alias name (for extent fields which are converted to use composite inner classes within the DMO).

This constructor should be used only for long-lived instances of this class. It interns the numerous string fields (an expensive operation), so instances created by this constructor can be cached in memory, without duplicating the contents of these strings.

Parameters:

dialect - Database dialect.

text - Text representation of sort component, as provided by query.

dmoInfo - Metadata for the table.

Throws:

PersistenceException - if there is any error with the text representation of the sort component provided by the caller.

SortCriterion

SortCriterion(Dialect dialect,
              java.lang.String text,
              DmoMeta dmoInfo,
              boolean internStrings)
       throws PersistenceException

Constructor which parses original sort component text, deriving the property name, sort direction, getter method for the property, case sensitivity of the property (character type only), and possibly a subscript value (for extent fields) and a composite alias name (for extent fields which are converted to use composite inner classes within the DMO).

Parameters:

dialect - Database dialect.

text - Text representation of sort component, as provided by query.

dmoInfo - Metadata for the table.

internStrings - true to intern string fields, else false.

Throws:

PersistenceException - if there is any error with the text representation of the sort component provided by the caller.

SortCriterion

public SortCriterion(SortCriterion other,
                     java.lang.String alias)

Specialized constructor which takes an existing SortCriterion and create a duplicate of it but with changed alias. This is used when the buffer is bound (see BIND mode for table parameters) under a different local variable name.

Parameters:

other - The source SortCriterion to copy.

alias - The new alias to be used.

Method Detail

isCompatible

public static boolean isCompatible(java.lang.String sort,
                                   java.lang.String dmoAlias)
                            throws PersistenceException

Check if this sort clause contains a property of a specific DMO. The quantified table should have the same name as the normalized legacy table.

Parameters:

sort - An atomic sort clause containing a quantified property and optionally a sorting direction.

dmoAlias - The alias of the DMO against which the compatibility should be checked.

Returns:

true if the provided sort clause related to the DMO.

Throws:

PersistenceException - This is thrown when the formating itself is wrong. If the name is not quantified, it doesn't mean it is not compatible, but that the sort clause reached an illegal state.

initializeCache

public static void initializeCache()

Initializes the cache using CacheManager. Only one cache is used, so there is no need for a discriminator. The default value of the cache is used when there is no size available from the configuration.

parse

public static java.util.List<SortCriterion> parse(Dialect dialect,
                                                  java.lang.String sort,
                                                  java.lang.String dmoAlias,
                                                  DmoMeta dmoInfo,
                                                  boolean makeUnique)
                                           throws PersistenceException

Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects. All components are recommended to be properties of the same DMO. Otherwise, the alias of each sort component is checked.

Parameters:

dialect - Database dialect.

sort - Sort phrase.

dmoAlias - Alias qualifier which represents DMO in sort phrase.

dmoInfo - Metadata for the table.

makeUnique - Indicates whether the <dmoAlias>.recid criterion should be appended to the returned criteria list.

Returns:

List of SortCriterion objects.

Throws:

PersistenceException - if there is any error parsing the given string.

parse

public static java.util.List<SortCriterion> parse(Dialect dialect,
                                                  java.lang.String sort,
                                                  java.lang.String dmoAlias,
                                                  DmoMeta dmoInfo,
                                                  boolean makeUnique,
                                                  boolean forceUniqueAsc)
                                           throws PersistenceException

Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects. All components are recommended to be properties of the same DMO. Otherwise, the alias of each sort component is checked.

Parameters:

dialect - Database dialect.

sort - Sort phrase.

dmoAlias - Alias qualifier which represents DMO in sort phrase.

dmoInfo - Metadata for the table.

makeUnique - Indicates whether the <dmoAlias>.recid criterion should be appended to the returned criteria list.

forceUniqueAsc - Forces the recid to be asc, and not follow the last component direction, when 'makeUnique'.

Returns:

List of SortCriterion objects.

Throws:

PersistenceException - if there is any error parsing the given string.

parse

public static java.util.List<SortCriterion> parse(java.lang.String sort,
                                                  RecordBuffer buffer)
                                           throws PersistenceException

Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects. All components are recommended to be properties of the same DMO. Otherwise, the alias of each sort component is checked.

Parameters:

sort - Sort phrase.

buffer - Record buffer associated with the sort phrase.

Returns:

List of SortCriterion objects. This list should never be empty; even if sort is null or empty, a single criterion of <dmoAlias>.recid will be created.

Throws:

PersistenceException - if there is any error parsing the given string.

parse

static java.util.List<SortCriterion> parse(java.lang.String sort,
                                           RecordBuffer buffer,
                                           boolean makeUnique)
                                    throws PersistenceException

Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects. All components are recommended to be properties of the same DMO. Otherwise, the alias of each sort component is checked.

Parameters:

sort - Sort phrase.

buffer - Record buffer associated with the sort phrase.

makeUnique - Indicates whether the <dmoAlias>.recid criterion should be appended to the returned criteria list.

Returns:

List of SortCriterion objects.

Throws:

PersistenceException - if there is any error parsing the given string.

parse

static java.util.List<SortCriterion> parse(java.lang.String sort,
                                           RecordBuffer buffer,
                                           boolean makeUnique,
                                           boolean forceUniqueAsc)
                                    throws PersistenceException

Parse a sort phrase (not including the "order by" preamble) into a list of SortCriterion objects. All components are recommended to be properties of the same DMO. Otherwise, the alias of each sort component is checked.

Parameters:

sort - Sort phrase.

buffer - Record buffer associated with the sort phrase.

makeUnique - Indicates whether the <dmoAlias>.recid criterion should be appended to the returned criteria list.

forceUniqueAsc - Forces the recid to be asc, and not follow the last component direction, when 'makeUnique'.

Returns:

List of SortCriterion objects.

Throws:

PersistenceException - if there is any error parsing the given string.

assembleHQLNoPreamble

static java.lang.String assembleHQLNoPreamble(java.util.List<SortCriterion> sortCriteria,
                                              boolean invert)

Assemble an HQL "order by" clause, sans the "order by" preamble, from the given list of sort criteria, optionally inverting the sort direction of the sort criteria.

Parameters:

sortCriteria - List of SortCriterion objects.

invert - true to reverse the sort direction of all sort criteria; false to use the original sort directions of the sort criteria.

Returns:

HQL order by clause, sans preamble.

toRawSortPhrase

static java.lang.String toRawSortPhrase(java.util.List<SortCriterion> sortCriteria)

Generate a raw sort phrase from the given list of criteria, in the simple form:

    {name} {direction} [, {name} {direction}]
 

Character fields are not enclosed in any upper() or rtrim() functions.

Parameters:

sortCriteria - List of sort criteria.

Returns:

Raw sort phrase.

getUnqualifiedName

public java.lang.String getUnqualifiedName()

Get the unqualified name of the property backing this component.

Returns:

Property name, sans DMO alias qualifier.

toString

public java.lang.String toString()

Get a normalized string representation of the sort component. Uses the form:

   {name} {direction}
 

For example:

   customer.accountNumber asc
 

If this component represents a case-insensitive sort on a character property, the property name will be enclosed in the upper database function, as in:

   upper(customer.name) asc
 

Overrides:

toString in class java.lang.Object

Returns:

String representation as described above.

isPrimaryKey

boolean isPrimaryKey()

Indicate whether this sort criterion represents the DMO's primary key.

Returns:

true if this sort criterion represents the DMO's primary key, else false.

getOriginalName

java.lang.String getOriginalName()

Get the name of the property behind this component.

This will usually be the same as the name returned by getName(), except in the case of an extent field. In that case, this method will return the name with the original subscripting.

Returns:

Property name, usually qualified by DMO alias.

getAlias

java.lang.String getAlias()

Get the DMO alias.

Returns:

The DMO alias.

getName

java.lang.String getName()

Get the name of the property behind this component.

This will usually be the same as the name returned by getOriginalName(), except in the case of an extent field. In that case, this method will return the expanded name, in the form:

    {alias}_composite{num}_{original_name_sans_subscript}
 

Returns:

Property name, usually qualified by DMO alias.

isAscending

boolean isAscending()

Indicate whether component sorts in ascending order.

Returns:

true if ascending, false if descending.

getDMOClass

java.lang.Class<? extends Record> getDMOClass()

Get the DMO implementation class containing the sort property for this criterion.

Returns:

DMO implementation class.

getMethod

java.lang.reflect.Method getMethod()

Get the getter method associated with the property behind this component.

Returns:

Getter method.

toSortExpression

java.lang.String toSortExpression(boolean invert)

Get a normalized string representation of the sort component. Uses the form:

   {name} {direction}
 

For example:

   customer.accountNumber asc
 

If this component represents a case-insensitive sort on a character property, the property name will be enclosed in the upper database function, as in:

   upper(customer.name) asc
 

If the invert parameter is true, the sort direction will be reversed, as in:

   upper(customer.name) desc
 

Parameters:

invert - true to reverse the sort direction.

Returns:

String representation as described above.

toSortExpression

java.lang.String toSortExpression(boolean invert,
                                  boolean useTableAlias,
                                  boolean uniqueAlias,
                                  boolean doSpecificProcessing)

Get a normalized string representation of the sort component. Uses the form:

   {name} {direction}
 

For example:

   customer.accountNumber asc
 

If this component represents a case-insensitive sort on a character property and doSpecificProcessing is set, the property name will be enclosed in the upper database function, as in:

   upper(customer.name) asc
 

If the invert parameter is true, the sort direction will be reversed, as in:

   upper(customer.name) desc
 

Parameters:

invert - true to reverse the sort direction.

useTableAlias - true to qualify property names with aliases, else false.

uniqueAlias - if true, a unique alias will be generated for use in subselects.

doSpecificProcessing - true to perform dialect-specific processing (adding computed column prefix, string trimming and uppercasing)

Returns:

String representation as described above.

toWhereExpression

FQLExpression toWhereExpression(boolean rangeMatch,
                                boolean invert)

Get a string representation of this sort component which is suitable to append to a base where clause when augmenting that where clause to make it more specific. The string represents an equality or range match between the property name and a substitution parameter. A range match may be inverted to represent the opposite sort direction. For example, the sort component

   customer.accountNumber asc
 

would be represented as:

   customer.accountNumber = ?
 

for an equality match; as:

   customer.accountNumber > ?
 

for a normal range match; and as:

   customer.accountNumber < ?
 

for an inverted range match.

Case-insensitive character properties are wrapped in the upper database function, as in:

   upper(customer.name) = ?
 

Parameters:

rangeMatch - true if a range match expression should be created; false to create an equality match expression.

invert - true to reverse polarity of a range match expression, else false.

Returns:

Where clause match expression as described above.