rocks.xmpp.precis

Class PrecisProfile

java.lang.Object

rocks.xmpp.precis.PrecisProfile

All Implemented Interfaces:

java.io.Serializable, java.util.Comparator<java.lang.CharSequence>

public abstract class PrecisProfile
extends java.lang.Object
implements java.util.Comparator<java.lang.CharSequence>, java.io.Serializable

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, Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PrecisProfile(boolean identifierClass)

Method Summary

Modifier and Type	Method and Description
protected abstract java.lang.CharSequence	applyAdditionalMappingRule(java.lang.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 java.lang.CharSequence	applyCaseMappingRule(java.lang.CharSequence input) The case mapping rule of a profile specifies whether case mapping (instead of case preservation) is performed on a string and how the mapping is applied (e.g., mapping uppercase and titlecase code points to their lowercase equivalents).
protected abstract java.lang.CharSequence	applyDirectionalityRule(java.lang.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 java.lang.CharSequence	applyNormalizationRule(java.lang.CharSequence input) The normalization rule of a profile specifies which Unicode normalization form (D, KD, C, or KC) is to be applied.
protected abstract java.lang.CharSequence	applyWidthMappingRule(java.lang.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 java.lang.CharSequence	caseMap(java.lang.CharSequence input) Applies the default case folding to a string.
protected static void	checkBidiRule(java.lang.CharSequence label) Checks the Bidi Rule.
int	compare(java.lang.CharSequence o1, java.lang.CharSequence o2) Compares two strings with each other.
java.lang.String	enforce(java.lang.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.
java.lang.String	prepare(java.lang.CharSequence input) Preparation entails only ensuring that the characters in an individual string are allowed by the underlying PRECIS string class.
protected java.lang.String	stabilize(java.lang.CharSequence input, java.util.function.Function<java.lang.CharSequence,java.lang.String> rules) Applying the rules for any given PRECIS profile is not necessarily an idempotent procedure (e.g., under certain circumstances, such as when Unicode Normalization Form KC is used, performing Unicode normalization after case mapping can still yield uppercase characters for certain code points).
java.lang.String	toComparableString(java.lang.CharSequence input) Converts a string to a comparable string.
protected static java.lang.CharSequence	widthMap(java.lang.CharSequence input) 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 java.lang.CharSequence widthMap(java.lang.CharSequence input)

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

Parameters:

input - The input string.

Returns:

The mapped string.

See Also:

Halfwidth and Fullwidth Forms

caseMap

protected static java.lang.CharSequence caseMap(java.lang.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(java.lang.CharSequence label)

Checks the Bidi Rule.

Parameters:

label - The label to check.

Throws:

InvalidDirectionalityException - If the label violates the Bidi Rule.

prepare

public java.lang.String prepare(java.lang.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 java.lang.String enforce(java.lang.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 final int compare(java.lang.CharSequence o1,
                         java.lang.CharSequence o2)

Compares two strings with each other.

Specified by:

compare in interface java.util.Comparator<java.lang.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).

See Also:

toComparableString(CharSequence)

toComparableString

public java.lang.String toComparableString(java.lang.CharSequence input)

Converts a string to a comparable string. The default comparison method uses the same rules as enforcement. However, there are exceptions to this approach, like in the Nickname profile, where comparison uses different rules than enforcement.

Parameters:

input - The input string.

Returns:

The comparable string.

See Also:

compare(CharSequence, CharSequence)

applyWidthMappingRule

protected abstract java.lang.CharSequence applyWidthMappingRule(java.lang.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 java.lang.CharSequence applyAdditionalMappingRule(java.lang.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 java.lang.CharSequence applyCaseMappingRule(java.lang.CharSequence input)

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

If case mapping is desired (instead of case preservation), it is RECOMMENDED to use the Unicode toLowerCase() operation defined in the Unicode Standard [Unicode]. In contrast to the Unicode toCaseFold() operation, the toLowerCase() operation is less likely to violate the "Principle of Least Astonishment", especially when an application merely wishes to convert uppercase and titlecase code points to their lowercase equivalents while preserving lowercase code points.

Parameters:

input - The input string.

Returns:

The case mapped string.

See Also:

5.2.3. Case Mapping Rule

applyNormalizationRule

protected abstract java.lang.CharSequence applyNormalizationRule(java.lang.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 java.lang.CharSequence applyDirectionalityRule(java.lang.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

stabilize

protected final java.lang.String stabilize(java.lang.CharSequence input,
                                           java.util.function.Function<java.lang.CharSequence,java.lang.String> rules)

Applying the rules for any given PRECIS profile is not necessarily an idempotent procedure (e.g., under certain circumstances, such as when Unicode Normalization Form KC is used, performing Unicode normalization after case mapping can still yield uppercase characters for certain code points). Therefore, an implementation SHOULD apply the rules repeatedly until the output string is stable; if the output string does not stabilize after reapplying the rules three (3) additional times after the first application, the implementation SHOULD terminate application of the rules and reject the input string as invalid.

This method applies the rules once (the first time) and then maximum three additional times.

Parameters:

input - The input string.

rules - The function which applies the rules.

Returns:

The stable output string.

See Also:

7. Order of Operations