KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * SequenceHandler.java: string, comment and special sequence handling in tokenizers
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.TokenizerProperty;
37 import de.susebox.jtopas.TokenizerException;
38
39
40 //-----------------------------------------------------------------------------
41 // Interface SequenceHandler
42 //
43
44 /**<p>
45  * This interface must be implemented by classes that should be used as a
46  * special sequence, string and comment start sequence checker for
47  * {@link de.susebox.jtopas.Tokenizer} implementations.
48  *</p>
49  *
50  * @see de.susebox.jtopas.Tokenizer
51  * @see de.susebox.jtopas.TokenizerProperties
52  * @see de.susebox.jtopas.spi.DataMapper
53  * @author Heiko Blau
54  */
55 public interface SequenceHandler {
56   
57   /**
58    * This method can be used by a {@link de.susebox.jtopas.Tokenizer} implementation
59    * for a fast detection if special sequence checking must be performed at all.
60    * If the method returns <code>false</code> time-consuming preparations can be
61    * skipped.
62    *
63    * @return <code>true</code> if there actually are pattern that can be tested
64    * for a match, <code>false</code> otherwise.
65    */
66   public boolean hasSequenceCommentOrString();
67   
68   /**
69    * This method checks if a given range of data starts with a special sequence,
70    * a comment or a string. These three types of token are tested together since
71    * both comment and string prefixes are ordinary special sequences. Only the
72    * actions preformed <strong>after</strong> a string or comment has been detected,
73    * are different.
74    *<br>
75    * The method returns <code>null</code> if no special sequence, comment or string
76    * could matches the the leading part of the data range given through the
77    * {@link DataProvider}.
78    *<br>
79    * In cases of strings or comments, the return value contains the description
80    * for the introducing character sequence, <strong>NOT</strong> the whole
81    * string or comment. The reading of the rest of the string or comment is done
82    * by the calling {@link de.susebox.jtopas.Tokenizer}.
83    *
84    * @param dataProvider the source to get the data range from
85    * @return a {@link de.susebox.jtopas.TokenizerProperty} if a special sequence,
86    * comment or string could be detected, <code>null</code> otherwise
87    * @throws TokenizerException generic exception
88    * @throws NullPointerException if no {@link DataProvider} is given
89    */
90   public TokenizerProperty startsWithSequenceCommentOrString(DataProvider dataProvider)
91     throws TokenizerException, NullPointerException JavaDoc;
92
93   /**
94    * This method returns the length of the longest special sequence, comment or
95    * string prefix that is known to this <code>SequenceHandler</code>. When
96    * calling {@link #startsWithSequenceCommentOrString}, the passed {@link DataProvider}
97    * parameter will supply at least this number of characters (see {@link DataProvider#getLength}).
98    * If less characters are provided, EOF is reached.
99    *<br>
100    * The method is an easy approach to the problem of how to provide more data
101    * in case a test runs out of characters. The invoking {@link de.susebox.jtopas.Tokenizer}
102    * (represented by the given {@link DataProvider}) can supply enough data for
103    * the {@link #startsWithSequenceCommentOrString} method.
104    *
105    * @return the number of characters needed in the worst case to identify a
106    * special sequence
107    */
108   public int getSequenceMaxLength();
109 }
110
Popular Tags