001: /*
002: * DataProvider.java: service provider interface for data sources.
003: *
004: * Copyright (C) 2002 Heiko Blau
005: *
006: * This file belongs to the JTopas Library.
007: * JTopas is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as published by the
009: * Free Software Foundation; either version 2.1 of the License, or (at your
010: * option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful, but WITHOUT
013: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
014: * FITNESS FOR A PARTICULAR PURPOSE.
015: * See the GNU Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public License along
018: * with JTopas. If not, write to the
019: *
020: * Free Software Foundation, Inc.
021: * 59 Temple Place, Suite 330,
022: * Boston, MA 02111-1307
023: * USA
024: *
025: * or check the Internet: http://www.fsf.org
026: *
027: * Contact:
028: * email: heiko@susebox.de
029: */
030:
031: package de.susebox.jtopas.spi;
032:
033: //-----------------------------------------------------------------------------
034: // Imports
035: //
036: import de.susebox.jtopas.Tokenizer;
037:
038: //-----------------------------------------------------------------------------
039: // Interface DataProvider
040: //
041:
042: /**<p>
043: * This interface supplies the nessecary methods for a {@link DataMapper} or its
044: * subinterfaces ({@link WhitespaceHandler}, {@link SeparatorHandler}, {@link PatternHandler}
045: * {@link KeywordHandler} and {@link SequenceHandler}) to perform its operations
046: * like checking for whitespaces, special sequences etc. Instances of the interface
047: * are created by {@link de.susebox.jtopas.Tokenizer} implementations.
048: *</p><p>
049: * A {@link de.susebox.jtopas.Tokenizer} implementation will either implement the
050: * <code>DataProvider</code> interface itself or has an associated - probably
051: * non-public - implementing class.
052: *</p><p>
053: * <strong>Note:</strong>: Each implementation of this interface should also
054: * override the method {@link java.lang.Object#toString}. The implementation of
055: * <code>toString</code> should return a string composed of all characters of a
056: * <code>DataProvider</code> between {@link #getStartPosition} (including) and
057: * {@link #getStartPosition} + {@link #getLength} (excluding).
058: *</p><p>
059: * <strong>Note:</strong>: This interface will eventually be deprecated in favour
060: * of the new JDK 1.4 interface {@link java.lang.CharSequence}.
061: *</p>
062: *
063: * @see de.susebox.jtopas.Tokenizer
064: * @see de.susebox.jtopas.TokenizerProperties
065: * @see DataMapper
066: * @author Heiko Blau
067: */
068: public interface DataProvider {
069:
070: /**
071: * This method retrieves a single character from the available data. Valid
072: * values for the parameter <code>index</code> start from 0 and are smaller
073: * than {@link #getLength}.
074: *<br>
075: * This method should be used in favour of {@link #getData} and {@link getDataCopy}
076: * whereever possible.
077: *
078: * @param index an index between 0 and {@link #getLength}
079: * @return the character at the given position
080: */
081: public char getCharAt(int index);
082:
083: /**
084: * This method retrieves the data range the active {@link DataMapper} should
085: * use for its operations. The calling method of the <code>DataMapper</code>
086: * should be aware that the provided array is probably the input buffer of the
087: * {@link de.susebox.jtopas.Tokenizer}. It should therefore treat it as a
088: * read-only object.
089: *<br>
090: * Use this method in combination with {@link #getStartPosition} and {@link #getLength}.
091: * Characters outside this range are invalid.
092: *<br>
093: * For a more secure but slower access, use the method {@link #getDataCopy}
094: * to retrieve a copy of the valid character range.
095: *<br>
096: * An implementation is still free to decide if this method gives access to
097: * an internal buffer or copies data into a new buffer. The latter case means
098: * that <code>getData</code> is equivalent to {@link #getDataCopy}.
099: *
100: * @return the character buffer to read data from
101: * @deprecated use subsequent calls to {@link #getCharAt} or <code>toString</code>
102: * instead
103: */
104: public char[] getData();
105:
106: /**
107: * This method copies the current data range of the {@link de.susebox.jtopas.Tokenizer}
108: * providing the <code>DataProvider</code> into a character buffer. Use this
109: * method if data should be modified.
110: *<br>
111: * The copy contains only valid data starting at position 0 with the length of
112: * the array returned. <strong>Don't</strong> use {@link #getStartPosition} or
113: * {@link #getLength} on this copy.
114: *<br>
115: * An alternative to this method is {@link java.lang.Object#toString} which
116: * should therefore be overridden in implementations of this interface.
117: *
118: * @return a copy of the valid data of this {@link DataProvider}
119: * @see #getData
120: * @deprecated use subsequent calls to {@link #getCharAt} or <code>toString</code>
121: * instead
122: */
123: public char[] getDataCopy();
124:
125: /**
126: * Retrieving the position where the data to analyze start in the buffer provided
127: * by {@link #getData}. The calling {@link DataMapper} must not access data
128: * prior to this index in the character array.
129: *
130: * @return index in the character array returned by {@link #getData}, where data starts
131: * @deprecated use indexes for {@link #getCharAt} starting with 0 up to
132: * {@link #getLength} (excluding).
133: */
134: public int getStartPosition();
135:
136: /**
137: * Retrieving the number of characters that a <code>DataProvider</code> can
138: * provide. The return value should be a positive integer.
139: *
140: * @return number of characters this <code>DataProvider</code> contains.
141: * <code>false</code> otherwise
142: */
143: public int getLength();
144: }
|