Package org.eclipse.equinox.bidi.custom

Class StructuredTextTypeHandler

java.lang.Object

org.eclipse.equinox.bidi.custom.StructuredTextTypeHandler

public class StructuredTextTypeHandler
extends Object

Generic handler to be used as superclass (base class) for specific structured text handlers.

Here are some guidelines about how to write structured text handlers.

• Handler instances may be accessed simultaneously by several threads. They should have no instance variables.
• This class provides common logic in code which can be invoked by any structured text handler. This common logic uses handler methods to query the characteristics of the specific handler:
  • the separators which separate the structured text into tokens. See getSeparators(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert).
  • the direction which governs the display of tokens one after the other. See getDirection(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String).
  • the number of special cases which need to be handled by code specific to that handler. See getSpecialsCount(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert).
• Before starting deeper analysis of the submitted text, the common logic gives to the handler a chance to shorten the process by invoking its skipProcessing(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes) method.
• The common logic then analyzes the text to segment it into tokens according to the appearance of separators (as retrieved using getSeparators(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert)).
• If the handler indicated a positive number of special cases as return value from its getSpecialsCount(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert) method, the common logic will repeatedly invoke the handler's indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) method to let it signal the presence of special strings which may further delimit the source text.
• When such a special case is signaled by the handler, the common logic will call the handler's processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) method to give it the opportunity to handle it as needed. Typical actions that the handler may perform are to add directional marks unconditionally (by calling insertMark(java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int) or conditionally (by calling processSeparator(java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int)).

Constructor Summary

Constructors

Constructor	Description
StructuredTextTypeHandler()	Creates a new instance of the StructuredTextTypeHandler class.
StructuredTextTypeHandler(String separators)	Creates a new instance of the StructuredTextTypeHandler class.

Method Summary

Modifier and Type	Method	Description
int	getDirection(IStructuredTextExpert expert, String text)	Indicates the base text direction appropriate for an instance of structured text.
int	getDirection(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes)	Indicates the base text direction appropriate for an instance of structured text.
String	getSeparators(IStructuredTextExpert expert)	Indicates the separators to use for the current handler.
int	getSpecialsCount(IStructuredTextExpert expert)	Indicates the number of special cases handled by the current handler.
int	indexOfSpecial(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int caseNumber, int fromIndex)	Locates occurrences of special strings within a structured text and returns their indexes one after the other in successive calls.
static void	insertMark(String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int offset)	Specifies that a mark character must be added before the character at the specified position of the lean text when generating the full text.
static void	processSeparator(String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int separLocation)	Adds a directional mark before a separator if needed for correct display, depending on the base direction of the text and on the class of the characters in the lean text preceding and following the separator itself.
int	processSpecial(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int caseNumber, int separLocation)	Handles special cases specific to this handler.
boolean	skipProcessing(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes)	Checks if there is a need for processing structured text.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

StructuredTextTypeHandler

public StructuredTextTypeHandler()

Creates a new instance of the StructuredTextTypeHandler class.

StructuredTextTypeHandler

public StructuredTextTypeHandler(String separators)

Creates a new instance of the StructuredTextTypeHandler class.

Parameters:

separators - string consisting of characters that split the text into fragments.

Method Detail

indexOfSpecial

public int indexOfSpecial(IStructuredTextExpert expert,
                          String text,
                          StructuredTextCharTypes charTypes,
                          StructuredTextOffsets offsets,
                          int caseNumber,
                          int fromIndex)

Locates occurrences of special strings within a structured text and returns their indexes one after the other in successive calls.

This method is called repeatedly if the number of special cases returned by getSpecialsCount(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert) is greater than zero.

A handler handling special cases must override this method.

Parameters:

expert - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current environment.

text - the structured text string before addition of any directional formatting characters.

charTypes - an object whose methods can be useful to the handler.

offsets - an object whose methods can be useful to the handler.

caseNumber - number of the special case to locate. This number varies from 1 to the number of special cases returned by getSpecialsCount(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert) for this handler. The meaning of this number is internal to the class implementing indexOfSpecial.

fromIndex - the index within text to start the search from.

Returns:

the position where the start of the special case corresponding to caseNumber was located. The method must return the first occurrence of whatever identifies the start of the special case starting from fromIndex. The method does not have to check if this occurrence appears within the scope of another special case (e.g. a comment starting delimiter within the scope of a literal or vice-versa).
If no occurrence is found, the method must return -1.

Throws:

IllegalStateException - If not overridden, this method throws an IllegalStateException. This is appropriate behavior (and does not need to be overridden) for handlers whose number of special cases is zero, which means that indexOfSpecial should never be called for them.

processSpecial

public int processSpecial(IStructuredTextExpert expert,
                          String text,
                          StructuredTextCharTypes charTypes,
                          StructuredTextOffsets offsets,
                          int caseNumber,
                          int separLocation)

Handles special cases specific to this handler. It is called when a special case occurrence is located by indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int).

If a special processing cannot be completed within a current call to processSpecial (for instance, a comment has been started in the current line but its end appears in a following line), processSpecial should specify a final state by calling IStructuredTextExpert.setState(Object). The meaning of this state is internal to the handler.

On a later call, processSpecial will be called with -1 for parameter separLocation. It should then retrieve the last state by calling IStructuredTextExpert.getState() and clear the state by calling IStructuredTextExpert.clearState(). After that, it should perform whatever initializations are required depending on the last state.

A handler handling special cases (with a number of special cases greater than zero) must override this method.

Parameters:

expert - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current environment.

text - the structured text string before addition of any directional formatting characters.

charTypes - an object whose methods can be useful to the handler.

offsets - an object whose methods can be useful to the handler.

caseNumber - number of the special case to handle.

separLocation - the position returned by indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int). After calls to IStructuredTextExpert.leanToFullText(java.lang.String) and other methods of IStructuredTextExpert which set a non-null final state, processSpecial is called when initializing the processing with value of separLocation equal to -1.

Returns:

the position after the scope of the special case ends. For instance, the position after the end of a comment, the position after the end of a literal.
A value greater or equal to the length of text means that there is no further occurrence of this case in the current structured text.

Throws:

IllegalStateException - If not overridden, this method throws an IllegalStateException. This is appropriate behavior (and does not need to be overridden) for handlers whose number of special cases is zero, which means that processSpecial should never be called for them.

insertMark

public static final void insertMark(String text,
                                    StructuredTextCharTypes charTypes,
                                    StructuredTextOffsets offsets,
                                    int offset)

Specifies that a mark character must be added before the character at the specified position of the lean text when generating the full text. This method can be called from within indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) or processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) in extensions of StructuredTextTypeHandler. The mark character will be LRM for structured text with a LTR base direction, and RLM for structured text with RTL base direction. The mark character is not added physically by this method, but its position is noted and will be used when generating the full text.

Parameters:

text - is the structured text string received as parameter to indexOfSpecial or processSpecial.

charTypes - is a parameter received by indexOfSpecial or processSpecial.

offsets - is a parameter received by indexOfSpecial or processSpecial.

offset - position of the character in the lean text. It must be a non-negative number smaller than the length of the lean text. For the benefit of efficiency, it is better to insert multiple marks in ascending order of the offsets.

processSeparator

public static final void processSeparator(String text,
                                          StructuredTextCharTypes charTypes,
                                          StructuredTextOffsets offsets,
                                          int separLocation)

Adds a directional mark before a separator if needed for correct display, depending on the base direction of the text and on the class of the characters in the lean text preceding and following the separator itself. This method can be called from within indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) or processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) in extensions of StructuredTextTypeHandler.

The logic implemented in this method considers the text before separLocation and the text following it. If, and only if, a directional mark is needed to insure that the two parts of text will be laid out according to the base direction, a mark will be added when generating the full text.

Parameters:

text - is the structured text string received as parameter to indexOfSpecial or processSpecial.

charTypes - is a parameter received by indexOfSpecial or processSpecial.

offsets - is a parameter received by indexOfSpecial or processSpecial.

separLocation - offset of the separator in the lean text. It must be a non-negative number smaller than the length of the lean text.

getSeparators

public String getSeparators(IStructuredTextExpert expert)

Indicates the separators to use for the current handler. This method is invoked before starting the processing.

If no separators are specified, this method returns an empty string.

Parameters:

expert - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current environment.

Returns:

a string grouping one-character separators which separate the structured text into tokens.

getDirection

public int getDirection(IStructuredTextExpert expert,
                        String text)

Indicates the base text direction appropriate for an instance of structured text. This method is invoked before starting the processing.

If not overridden, this method returns DIR_LTR.

Parameters:

expert - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current environment.

text - the structured text string to process.

Returns:

the base direction of the structured text. This direction may not be the same depending on the environment and on whether the structured text contains Arabic or Hebrew letters.
The value returned is either DIR_LTR or DIR_RTL.

getDirection

public int getDirection(IStructuredTextExpert expert,
                        String text,
                        StructuredTextCharTypes charTypes)

Indicates the base text direction appropriate for an instance of structured text. This method is invoked before starting the processing.

If not overridden, this method returns DIR_LTR.

Parameters:

expert - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current environment.

text - is the structured text string to process.

charTypes - is a parameter received by indexOfSpecial or processSpecial.

Returns:

the base direction of the structured text. This direction may not be the same depending on the environment and on whether the structured text contains Arabic or Hebrew letters.
The value returned is either DIR_LTR or DIR_RTL.

getSpecialsCount

public int getSpecialsCount(IStructuredTextExpert expert)

Indicates the number of special cases handled by the current handler. This method is invoked before starting the processing. If the number returned is zero, indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) and processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) will not be invoked.

If not overridden, this method returns zero.

Parameters:

expert - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current environment.

Returns:

the number of special cases for the associated handler. Special cases exist for some types of structured text handlers. They are implemented by overriding methods indexOfSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int) and processSpecial(org.eclipse.equinox.bidi.advanced.IStructuredTextExpert, java.lang.String, org.eclipse.equinox.bidi.custom.StructuredTextCharTypes, org.eclipse.equinox.bidi.custom.StructuredTextOffsets, int, int). Examples of special cases are comments, literals, or anything which is not identified by a one-character separator.

skipProcessing

public boolean skipProcessing(IStructuredTextExpert expert,
                              String text,
                              StructuredTextCharTypes charTypes)

Checks if there is a need for processing structured text. This method is invoked before starting the processing. If the handler returns true, no directional formatting characters are added to the lean text and the processing is shortened.

If not overridden, this method returns false.

Parameters:

expert - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current environment.

text - is the structured text string to process.

charTypes - is a parameter received by indexOfSpecial or processSpecial.

Returns:

a flag indicating if there is no need to process the structured text to add directional formatting characters.

toString

public String toString()

Overrides:

toString in class Object