oracle.i18n.text

Class OraCollator

java.lang.Object

oracle.i18n.text.OraCollator

All Implemented Interfaces:

Cloneable, Comparator

public class OraCollator
extends Object
implements Cloneable, Comparator

The OraCollator class performs locale-sensitive string comparisons, including linguistic collation and binary sorting.

Since:

Oracle 10.1.0.2

Field Summary

Fields

Modifier and Type	Field and Description
static int	CANONICAL_COMPOSITION The OraCollator class composition level value.
static int	EQUAL The result of the comparison that the OraCollator object returns if the two strings are equal.
static int	GREATER The result of the comparison that the OraCollator object returns if the first string is greater than the second string.
static int	LESS The result of the comparison that the OraCollator object returns if the first string is less than the second string.
static int	NO_COMPOSITION The OraCollator class composition level value.
static int	PRIMARY The OraCollator class strength value.
static int	SECONDARY The OraCollator class strength value.
static int	TERTIARY The OraCollator class strength value.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	OraCollator() The constructor is here only for completeness.

Method Summary

Modifier and Type	Method and Description
Object	clone() Makes an independent duplicate of the OraCollator object.
int	compare(Object source, Object target) Compares two objects using the current collation rule.
int	compare(String source, String target) Compares two strings using the current collation rule.
String	convertToBaseLetter(String source)
String	convertToCaseFold(String source)
boolean	equals(Object obj) Returns true if this OraCollator object is equal to another.
String	getCharSet() Gets the charSet name of this OraCollator object.
OraCollationKey	getCollationKey(String source) Gets the OraCollationKey object for a given source string.
int	getComposition() Gets the composition level used for comparison.
static OraCollator	getInstance() Deprecated. As of Oracle Database 10g Release 2 (10.2), replaced by OraCollator.getInstance(Locale)
static OraCollator	getInstance(Locale locale) Constructs an Oracle collation object from the Java locale.
static OraCollator	getInstance(Locale locale, String sortRule, String charSet) Constructs an OraCollator instance from the specified sortRule value and locale.
static OraCollator	getInstance(OraLocaleInfo oraLocale) Constructs an Oracle collation object from an OraLocaleInfo object.
static OraCollator	getInstance(String sortRule) Constructs an OraCollator instance from the specified sortRule value.
static OraCollator	getInstance(String sortRule, String charSet) Constructs an OraCollator instance from the specified sortRule value.
String	getName() Gets the sorting rule name of this OraCollator object.
int	getStrength() Gets the strength used in comparisons.
int	hashCode() Creates a hash code for this OraCollator object based on sort rule, strength, and decomposition level.
int[]	matchFirst(String source, String pattern) This method searches pattern string from the beginning of source string.
int[]	matchLast(String source, String pattern) This method searches pattern string from the end of source string.
void	setComposition(int compositionMode) Sets the composition level used for comparison.
void	setStrength(int newStrength) Sets the strength used in comparisons.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Comparator

comparing, comparing, comparingDouble, comparingInt, comparingLong, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Field Detail

PRIMARY

public static final int PRIMARY

The OraCollator class strength value. When set, only primary differences are considered significant during comparison. The assignment of strengths to language features is locale dependant. For example, different base letters ("a" vs. "b") are considered a primary difference. For monolingual and binary sort, a primary setting means accent insensitive.

See Also:

OraCollator.setStrength(int), OraCollator.getStrength(), Constant Field Values

SECONDARY

public static final int SECONDARY

The OraCollator class strength value. When set, only secondary and higher-order differences are considered significant during comparison. The assignment of strengths to language features is locale dependant. For example, different accented forms of the same base letter ("a" vs. "â") are considered a secondary difference. For monolingual and binary sort, a secondary setting means case insensitive .

See Also:

OraCollator.setStrength(int), OraCollator.getStrength(), Constant Field Values

TERTIARY

public static final int TERTIARY

The OraCollator class strength value. When set, only tertiary and higher-order differences are considered significant during comparison. The assignment of strengths to language features is locale dependant. For example, case differences ("a" vs. "A") are considered a tertiary difference.

See Also:

OraCollator.setStrength(int), OraCollator.getStrength(), Constant Field Values

NO_COMPOSITION

public static final int NO_COMPOSITION

The OraCollator class composition level value. When the composition level set to NO_COMPOSITION, canonical equivalence is not considered.

See Also:

OraCollator.setComposition(int), OraCollator.getComposition(), Constant Field Values

CANONICAL_COMPOSITION

public static final int CANONICAL_COMPOSITION

The OraCollator class composition level value. When the composition level set to CANONICAL_COMPOSITION, canonical equivalence is considered as the same.

See Also:

OraCollator.setComposition(int), OraCollator.getComposition(), Constant Field Values

EQUAL

public static final int EQUAL

The result of the comparison that the OraCollator object returns if the two strings are equal.

See Also:

Constant Field Values

LESS

public static final int LESS

The result of the comparison that the OraCollator object returns if the first string is less than the second string.

See Also:

Constant Field Values

GREATER

public static final int GREATER

The result of the comparison that the OraCollator object returns if the first string is greater than the second string.

See Also:

Constant Field Values

Constructor Detail

OraCollator

protected OraCollator()

The constructor is here only for completeness. The getInstance method should be used instead to create new OraCollator objects.

Method Detail

getInstance

public static OraCollator getInstance()

Deprecated. As of Oracle Database 10g Release 2 (10.2), replaced by OraCollator.getInstance(Locale)

Constructs an Oracle collation object from the default Java locale. Converts the default Java locale to the OraLocaleInfo object using the default sorting rule.

Returns:

OraCollator instance

getInstance

public static OraCollator getInstance(Locale locale)

Constructs an Oracle collation object from the Java locale. It converts the Java locale to Oracle locale and uses the result to get the OraCollator object.

Parameters:

locale - Java Locale object

Returns:

OraCollator instance

getInstance

public static OraCollator getInstance(OraLocaleInfo oraLocale)

Constructs an Oracle collation object from an OraLocaleInfo object. Retrieves the default collator associated with the OraLocaleInfo object.

Parameters:

oraLocale - OraLocaleInfo object

Returns:

OraCollator instance

getInstance

public static OraCollator getInstance(String sortRule)

Constructs an OraCollator instance from the specified sortRule value. The sortRule values are the same as NLSRTL's NLS_SORT names; for example, xgerman, GENERIC_M, unicode_binary, binary, etc. ai or ci can be attached to sort rules to specify the comparison level.

Parameters:

sortRule - Oracle sort rule name

Returns:

OraCollator instance

Throws:

IllegalArgumentException - if an invalid sort rule name is specified

getInstance

public static OraCollator getInstance(String sortRule,
                                      String charSet)

Constructs an OraCollator instance from the specified sortRule value. This method will take both Oracle sorting rule and "binary" as sortRule value. If using Oracle sorting rule, the charSet values will be ignored. If using binary sorting rule, the charSet value could be specified by a valid character set on the database server. ai or ci can be attached to "binary" for specifying the comparison level.

Parameters:

sortRule - Oracle sort rule name

charSet - Oracle database character set, could be null. The default is UTF16

Returns:

OraCollator instance

Throws:

IllegalArgumentException - if an invalid sort rule name is specified

getInstance

public static OraCollator getInstance(Locale locale,
                                      String sortRule,
                                      String charSet)

Constructs an OraCollator instance from the specified sortRule value and locale. This method will take both Oracle sorting rule and "binary" as sortRule value. If using Oracle sorting rule, the charSet values will be ignored. If using binary sorting rule, the charSet value could be specified by a valid character set on the database server. ai or ci can be attached to "binary" for specifying the comparison level. It also records the locale information in the instance.

Parameters:

locale - Java Locale object

sortRule - Oracle sort rule name

charSet - Oracle database character set, could be null. The default is UTF16

Returns:

OraCollator instance

getName

public String getName()

Gets the sorting rule name of this OraCollator object.

Returns:

sorting rule name

getCharSet

public String getCharSet()

Gets the charSet name of this OraCollator object.

Returns:

database character set

setStrength

public void setStrength(int newStrength)

Sets the strength used in comparisons. Strength could have the values of PRIMARY, SECONDARY, or TERTIARY.

Parameters:

newStrength - the new strength to be set, options are PRIMARY, SECONDARY or TERTIARY

Throws:

IllegalArgumentException - if an invalid strength is specified

See Also:

OraCollator.PRIMARY, OraCollator.SECONDARY, OraCollator.TERTIARY

getStrength

public int getStrength()

Gets the strength used in comparisons. Strength could have the values of PRIMARY, SECONDARY, or TERTIARY.

Returns:

the current strength

See Also:

OraCollator.PRIMARY, OraCollator.SECONDARY, OraCollator.TERTIARY

setComposition

public void setComposition(int compositionMode)

Sets the composition level used for comparison. Composition level could be either CANONICAL_COMPOSITION or NO_COMPOSITION.

Parameters:

compositionMode - the composition level to be set, options are either CANONICAL_COMPOSITION or NO_COMPOSITION

Throws:

IllegalArgumentException - if an invalid composition mode is specified

See Also:

OraCollator.NO_COMPOSITION, OraCollator.CANONICAL_COMPOSITION

getComposition

public int getComposition()

Gets the composition level used for comparison. Composition level could be either CANONICAL_COMPOSITION or NO_COMPOSITION.

Returns:

the current composition level

See Also:

OraCollator.NO_COMPOSITION, OraCollator.CANONICAL_COMPOSITION

clone

public Object clone()

Makes an independent duplicate of the OraCollator object.

Overrides:

clone in class Object

Returns:

OraCollator object

hashCode

public int hashCode()

Creates a hash code for this OraCollator object based on sort rule, strength, and decomposition level.

Overrides:

hashCode in class Object

Returns:

a hash code

equals

public boolean equals(Object obj)

Returns true if this OraCollator object is equal to another.

Specified by:

equals in interface Comparator

Overrides:

equals in class Object

Parameters:

obj - a target object with which to be compared

Returns:

true if equal or false if not

compare

public int compare(Object source,
                   Object target)

Compares two objects using the current collation rule. The comparison result depends on the sorting rule and the setting of comparison level.

This implementation merely returns compare((String)o1, (String)o2).

Specified by:

compare in interface Comparator

Parameters:

source - first Object to be compared

target - second Object to be compared

Returns:

OraCollator.GREATER, OraCollator.EQUAL, or OraCollator.LESS

compare

public int compare(String source,
                   String target)

Compares two strings using the current collation rule. The comparison result depends on the sorting rule and the setting of comparison level.

Parameters:

source - first String to be compared

target - second String to be compared

Returns:

OraCollator.GREATER, OraCollator.EQUAL, or OraCollator.LESS

getCollationKey

public OraCollationKey getCollationKey(String source)

Gets the OraCollationKey object for a given source string.

Parameters:

source - source string to get Oracle collation key

Returns:

OraCollationKey object

convertToBaseLetter

public String convertToBaseLetter(String source)

convertToCaseFold

public String convertToCaseFold(String source)

matchFirst

public int[] matchFirst(String source,
                        String pattern)

This method searches pattern string from the beginning of source string.

Parameters:

source - source string as the target. pattern as pattern string.

Returns:

If match found, return the first index(position) of source string to int[0] and the index of the last character matched plus one to int[1]. The returning index range is from 0 to n for the source string length of n. Return -1 to int[0] and int[1] if no match.

matchLast

public int[] matchLast(String source,
                       String pattern)

This method searches pattern string from the end of source string.

Parameters:

source - source string as the target. pattern as pattern string.

Returns:

If match found, return the index(position) of source string to int[0] and the index of the last character matched plus one to int[1]. The returning index range is from 0 to n for the source string length of n. Return -1 to int[0] and int[1] if no match.