KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > de > susebox > jtopas > spi > DataProvider


1 /*
2  * DataProvider.java: service provider interface for data sources.
3  *
4  * Copyright (C) 2002 Heiko Blau
5  *
6  * This file belongs to the JTopas Library.
7  * JTopas is free software; you can redistribute it and/or modify it
8  * under the terms of the GNU Lesser General Public License as published by the
9  * Free Software Foundation; either version 2.1 of the License, or (at your
10  * option) any later version.
11  *
12  * This software is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE.
15  * See the GNU Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public License along
18  * with JTopas. If not, write to the
19  *
20  * Free Software Foundation, Inc.
21  * 59 Temple Place, Suite 330,
22  * Boston, MA 02111-1307
23  * USA
24  *
25  * or check the Internet: http://www.fsf.org
26  *
27  * Contact:
28  * email: heiko@susebox.de
29  */
30
31 package de.susebox.jtopas.spi;
32
33 //-----------------------------------------------------------------------------
34 // Imports
35 //
36 import de.susebox.jtopas.Tokenizer;
37
38
39 //-----------------------------------------------------------------------------
40 // Interface DataProvider
41 //
42
43 /**<p>
44  * This interface supplies the nessecary methods for a {@link DataMapper} or its
45  * subinterfaces ({@link WhitespaceHandler}, {@link SeparatorHandler}, {@link PatternHandler}
46  * {@link KeywordHandler} and {@link SequenceHandler}) to perform its operations
47  * like checking for whitespaces, special sequences etc. Instances of the interface
48  * are created by {@link de.susebox.jtopas.Tokenizer} implementations.
49  *</p><p>
50  * A {@link de.susebox.jtopas.Tokenizer} implementation will either implement the
51  * <code>DataProvider</code> interface itself or has an associated - probably
52  * non-public - implementing class.
53  *</p><p>
54  * <strong>Note:</strong>: Each implementation of this interface should also
55  * override the method {@link java.lang.Object#toString}. The implementation of
56  * <code>toString</code> should return a string composed of all characters of a
57  * <code>DataProvider</code> between {@link #getStartPosition} (including) and
58  * {@link #getStartPosition} + {@link #getLength} (excluding).
59  *</p><p>
60  * <strong>Note:</strong>: This interface will eventually be deprecated in favour
61  * of the new JDK 1.4 interface {@link java.lang.CharSequence}.
62  *</p>
63  *
64  * @see de.susebox.jtopas.Tokenizer
65  * @see de.susebox.jtopas.TokenizerProperties
66  * @see DataMapper
67  * @author Heiko Blau
68  */
69 public interface DataProvider {
70   
71   /**
72    * This method retrieves a single character from the available data. Valid
73    * values for the parameter <code>index</code> start from 0 and are smaller
74    * than {@link #getLength}.
75    *<br>
76    * This method should be used in favour of {@link #getData} and {@link getDataCopy}
77    * whereever possible.
78    *
79    * @param index an index between 0 and {@link #getLength}
80    * @return the character at the given position
81    */
82   public char getCharAt(int index);
83   
84   /**
85    * This method retrieves the data range the active {@link DataMapper} should
86    * use for its operations. The calling method of the <code>DataMapper</code>
87    * should be aware that the provided array is probably the input buffer of the
88    * {@link de.susebox.jtopas.Tokenizer}. It should therefore treat it as a
89    * read-only object.
90    *<br>
91    * Use this method in combination with {@link #getStartPosition} and {@link #getLength}.
92    * Characters outside this range are invalid.
93    *<br>
94    * For a more secure but slower access, use the method {@link #getDataCopy}
95    * to retrieve a copy of the valid character range.
96    *<br>
97    * An implementation is still free to decide if this method gives access to
98    * an internal buffer or copies data into a new buffer. The latter case means
99    * that <code>getData</code> is equivalent to {@link #getDataCopy}.
100    *
101    * @return the character buffer to read data from
102    * @deprecated use subsequent calls to {@link #getCharAt} or <code>toString</code>
103    * instead
104    */
105   public char[] getData();
106   
107   /**
108    * This method copies the current data range of the {@link de.susebox.jtopas.Tokenizer}
109    * providing the <code>DataProvider</code> into a character buffer. Use this
110    * method if data should be modified.
111    *<br>
112    * The copy contains only valid data starting at position 0 with the length of
113    * the array returned. <strong>Don't</strong> use {@link #getStartPosition} or
114    * {@link #getLength} on this copy.
115    *<br>
116    * An alternative to this method is {@link java.lang.Object#toString} which
117    * should therefore be overridden in implementations of this interface.
118    *
119    * @return a copy of the valid data of this {@link DataProvider}
120    * @see #getData
121    * @deprecated use subsequent calls to {@link #getCharAt} or <code>toString</code>
122    * instead
123    */
124   public char[] getDataCopy();
125      
126   /**
127    * Retrieving the position where the data to analyze start in the buffer provided
128    * by {@link #getData}. The calling {@link DataMapper} must not access data
129    * prior to this index in the character array.
130    *
131    * @return index in the character array returned by {@link #getData}, where data starts
132    * @deprecated use indexes for {@link #getCharAt} starting with 0 up to
133    * {@link #getLength} (excluding).
134    */
135   public int getStartPosition();
136
137   /**
138    * Retrieving the number of characters that a <code>DataProvider</code> can
139    * provide. The return value should be a positive integer.
140    *
141    * @return number of characters this <code>DataProvider</code> contains.
142    * <code>false</code> otherwise
143    */
144   public int getLength();
145 }
146
Popular Tags