rocks.xmpp.precis

Class PrecisProfile

java.lang.Object

rocks.xmpp.precis.PrecisProfile

All Implemented Interfaces:

Comparator<CharSequence>

public abstract class PrecisProfile
extends Object
implements Comparator<CharSequence>

This is the base class for a PRECIS profile. A profile defines a set of rules (width mapping, additional mapping, case mapping, normalization and directionality) and uses one of two string classes, IdentifierClass or FreeformClass, which define the allowed and disallowed characters.

There are three basic use cases you can do with this class:

• Preparation: entails only ensuring that the characters in an individual string are allowed by the underlying PRECIS string class.
• Enforcement: entails applying all of the rules specified for a particular string class or profile thereof to an individual string, for the purpose of determining if the string can be used in a given protocol slot.
• Comparison: entails applying all of the rules specified for a particular string class or profile thereof to two separate strings, for the purpose of determining if the two strings are equivalent.

See Also:

4. String Classes, 5. Profiles, PrecisProfiles

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PrecisProfile(boolean identifierClass)

Method Summary

Modifier and Type	Method and Description
protected abstract CharSequence	applyAdditionalMappingRule(CharSequence input) The additional mapping rule of a profile specifies whether additional mappings are performed on the characters of a string, such as: Mapping of delimiter characters (such as '@', ':', '/', '+', and '-') Mapping of special characters (e.g., non-ASCII space characters to ASCII space or control characters to nothing).
protected abstract CharSequence	applyCaseMappingRule(CharSequence input) The case mapping rule of a profile specifies whether case mapping (instead of case preservation) is performed on the characters of a string, and how the mapping is applied (e.g., mapping uppercase and titlecase characters to their lowercase equivalents).
protected abstract CharSequence	applyDirectionalityRule(CharSequence input) The directionality rule of a profile specifies how to treat strings containing what are often called "right-to-left" (RTL) characters (see Unicode Standard Annex #9 [UAX9]).
protected abstract CharSequence	applyNormalizationRule(CharSequence input) The normalization rule of a profile specifies which Unicode normalization form (D, KD, C, or KC) is to be applied.
protected abstract CharSequence	applyWidthMappingRule(CharSequence input) The width mapping rule of a profile specifies whether width mapping is performed on the characters of a string, and how the mapping is done.
protected static CharSequence	caseFold(CharSequence input) Applies the default case folding to a string.
protected static void	checkBidiRule(CharSequence label) Checks the Bidi Rule.
int	compare(CharSequence o1, CharSequence o2) Compares two strings with each other.
String	enforce(CharSequence input) Enforcement entails applying all of the rules specified for a particular string class or profile thereof to an individual string, for the purpose of determining if the string can be used in a given protocol slot.
String	prepare(CharSequence input) Preparation entails only ensuring that the characters in an individual string are allowed by the underlying PRECIS string class.
protected static CharSequence	widthMap(CharSequence s) Maps full-width and half-width characters to their decomposition mappings.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Comparator

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

Constructor Detail

PrecisProfile

protected PrecisProfile(boolean identifierClass)

Parameters:

identifierClass - True, if the base class for this profile is the "IdentifierClass"; false if it's the "FreeFormClass".

Method Detail

widthMap

protected static CharSequence widthMap(CharSequence s)

Maps full-width and half-width characters to their decomposition mappings.

See Also:

Halfwidth and Fullwidth Forms

caseFold

protected static CharSequence caseFold(CharSequence input)

Applies the default case folding to a string.

Parameters:

input - The input string.

Returns:

The case folded string.

checkBidiRule

protected static void checkBidiRule(CharSequence label)

Checks the Bidi Rule.

Parameters:

label - The label to check.

Throws:

InvalidDirectionalityException - If the label violates the Bidi Rule.

prepare

public String prepare(CharSequence input)

Preparation entails only ensuring that the characters in an individual string are allowed by the underlying PRECIS string class.

Parameters:

input - The input string.

Returns:

For convenience, returns the same string as the input string.

Throws:

InvalidCodePointException - If the input contains invalid code points (which are disallowed by the underlying Precis String class).

enforce

public String enforce(CharSequence input)

Enforcement entails applying all of the rules specified for a particular string class or profile thereof to an individual string, for the purpose of determining if the string can be used in a given protocol slot.

This base method first applies the profile rules, then the behavioral rules as per RFC 7564 §7.

Parameters:

input - The input string.

Returns:

The output string.

Throws:

InvalidCodePointException - If the input contains invalid code points (which are disallowed by the underlying Precis String class).

See Also:

7. Order of Operations

compare

public int compare(CharSequence o1,
                   CharSequence o2)

Compares two strings with each other. The default comparison method enforces the rules of a profile to each string and then compares them. However, there are exceptions to this approach, like in the Nickname profile, where comparison uses different rules than enforcement.

Specified by:

compare in interface Comparator<CharSequence>

Parameters:

o1 - The first string.

o2 - The second string.

Returns:

0 if the strings are equal, otherwise the comparison result.

Throws:

InvalidCodePointException - If the input contains invalid code points (which are disallowed by the underlying Precis String class).

applyWidthMappingRule

protected abstract CharSequence applyWidthMappingRule(CharSequence input)

The width mapping rule of a profile specifies whether width mapping is performed on the characters of a string, and how the mapping is done.

Parameters:

input - The input string.

Returns:

The width-mapped string.

See Also:

5.2.1. Width Mapping Rule

applyAdditionalMappingRule

protected abstract CharSequence applyAdditionalMappingRule(CharSequence input)

The additional mapping rule of a profile specifies whether additional mappings are performed on the characters of a string, such as:

Mapping of delimiter characters (such as '@', ':', '/', '+', and '-')

Mapping of special characters (e.g., non-ASCII space characters to ASCII space or control characters to nothing).

Parameters:

input - The input string.

Returns:

The mapped string.

See Also:

5.2.2. Additional Mapping Rule

applyCaseMappingRule

protected abstract CharSequence applyCaseMappingRule(CharSequence input)

The case mapping rule of a profile specifies whether case mapping (instead of case preservation) is performed on the characters of a string, and how the mapping is applied (e.g., mapping uppercase and titlecase characters to their lowercase equivalents).

If case mapping is desired (instead of case preservation), it is RECOMMENDED to use Unicode Default Case Folding as defined in the Unicode Standard

Parameters:

input - The input string.

Returns:

The case mapped string.

See Also:

5.2.3. Case Mapping Rule

applyNormalizationRule

protected abstract CharSequence applyNormalizationRule(CharSequence input)

The normalization rule of a profile specifies which Unicode normalization form (D, KD, C, or KC) is to be applied.

In accordance with [RFC5198], normalization form C (NFC) is RECOMMENDED.

Parameters:

input - The input string.

Returns:

The normalized string.

See Also:

5.2.4. Normalization Rule

applyDirectionalityRule

protected abstract CharSequence applyDirectionalityRule(CharSequence input)

The directionality rule of a profile specifies how to treat strings containing what are often called "right-to-left" (RTL) characters (see Unicode Standard Annex #9 [UAX9]). RTL characters come from scripts that are normally written from right to left and are considered by Unicode to, themselves, have right-to-left directionality. Some strings containing RTL characters also contain "left-to-right" (LTR) characters, such as numerals, as well as characters without directional properties. Consequently, such strings are known as "bidirectional strings".

Parameters:

input - The input string.

Returns:

The output string.

See Also:

5.2.5. Directionality Rule