de.susebox.jtopas.spi

Interface DataProvider

public interface DataProvider

This interface supplies the nessecary methods for a DataMapper or its subinterfaces (WhitespaceHandler, SeparatorHandler, PatternHandler KeywordHandler and SequenceHandler) to perform its operations like checking for whitespaces, special sequences etc. Instances of the interface are created by Tokenizer implementations.

A Tokenizer implementation will either implement the DataProvider interface itself or has an associated - probably non-public - implementing class.

Note:: Each implementation of this interface should also override the method Object.toString(). The implementation of toString should return a string composed of all characters of a DataProvider between getStartPosition() (including) and getStartPosition() + getLength() (excluding).

Note:: This interface will eventually be deprecated in favour of the new JDK 1.4 interface CharSequence.

Author:

Heiko Blau

See Also:

Tokenizer, TokenizerProperties, DataMapper

Method Summary

Modifier and Type	Method and Description
char	getCharAt(int index) This method retrieves a single character from the available data.
char[]	getData() Deprecated. use subsequent calls to getCharAt(int) or toString instead
char[]	getDataCopy() Deprecated. use subsequent calls to getCharAt(int) or toString instead
int	getLength() Retrieving the number of characters that a DataProvider can provide.
int	getStartPosition() Deprecated. use indexes for getCharAt(int) starting with 0 up to getLength() (excluding).

Method Detail

getCharAt

char getCharAt(int index)

This method retrieves a single character from the available data. Valid values for the parameter index start from 0 and are smaller than getLength().
This method should be used in favour of getData() and getDataCopy whereever possible.

Parameters:

index - an index between 0 and getLength()

Returns:

the character at the given position

getData

char[] getData()

Deprecated. use subsequent calls to getCharAt(int) or toString instead

This method retrieves the data range the active DataMapper should use for its operations. The calling method of the DataMapper should be aware that the provided array is probably the input buffer of the Tokenizer. It should therefore treat it as a read-only object.
Use this method in combination with getStartPosition() and getLength(). Characters outside this range are invalid.
For a more secure but slower access, use the method getDataCopy() to retrieve a copy of the valid character range.
An implementation is still free to decide if this method gives access to an internal buffer or copies data into a new buffer. The latter case means that getData is equivalent to getDataCopy().

Returns:

the character buffer to read data from

getDataCopy

char[] getDataCopy()

Deprecated. use subsequent calls to getCharAt(int) or toString instead

This method copies the current data range of the Tokenizer providing the DataProvider into a character buffer. Use this method if data should be modified.
The copy contains only valid data starting at position 0 with the length of the array returned. Don't use getStartPosition() or getLength() on this copy.
An alternative to this method is Object.toString() which should therefore be overridden in implementations of this interface.

Returns:

a copy of the valid data of this DataProvider

See Also:

getData()

getStartPosition

int getStartPosition()

Deprecated. use indexes for getCharAt(int) starting with 0 up to getLength() (excluding).

Retrieving the position where the data to analyze start in the buffer provided by getData(). The calling DataMapper must not access data prior to this index in the character array.

Returns:

index in the character array returned by getData(), where data starts

getLength

int getLength()

Retrieving the number of characters that a DataProvider can provide. The return value should be a positive integer.

Returns:

number of characters this DataProvider contains. false otherwise