001: /*
002: * DataMapper.java: service provider interface for data-to-token mapping.
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.TokenizerProperties;
037:
038: //-----------------------------------------------------------------------------
039: // Interface DataMapper
040: //
041:
042: /**<p>
043: * This interface declares the methods that a {@link de.susebox.jtopas.Tokenizer}
044: * will call to detect the image and type of a token. Usually, an implementation
045: * of the {@link de.susebox.jtopas.TokenizerProperties} interface should also
046: * implement the <code>DataMapper</code> interface, but this is not mandatory.
047: *</p><p>
048: * If a {@link de.susebox.jtopas.TokenizerProperties} instance given to a
049: * {@link de.susebox.jtopas.Tokenizer} does not implement the <code>DataMapper</code>
050: * interface, then the <code>Tokenizer</code> will contruct a default <code>DataMapper</code>
051: * for its properties.
052: *</p><p>
053: * This interface extends the SPI interfaces specialized in handling various token
054: * types.
055: *</p>
056: *
057: * @see de.susebox.jtopas.Tokenizer
058: * @see de.susebox.jtopas.TokenizerProperties
059: * @author Heiko Blau
060: */
061: public interface DataMapper extends WhitespaceHandler,
062: SeparatorHandler, KeywordHandler, SequenceHandler,
063: PatternHandler {
064:
065: /**
066: * Setting the backing {@link de.susebox.jtopas.TokenizerProperties} instance
067: * this <code>DataMapper</code> is working with. Usually, the <code>DataMapper</code>
068: * interface is implemented by <code>TokenizerProperties</code> implementations,
069: * too. Otherwise the {@link de.susebox.jtopas.Tokenizer} using the
070: * <code>TokenizerProperties</code>, will construct a default <code>DataMapper</code>
071: * an propagate the <code>TokenizerProperties</code> instance by calling this
072: * method.
073: *<br>
074: * The method should throw an {@link java.lang.UnsupportedOperationException}
075: * if this <code>DataMapper</code> is an extension to an <code>TokenizerProperties</code>
076: * implementation.
077: *
078: * @param props the {@link de.susebox.jtopas.TokenizerProperties}
079: * @throws UnsupportedOperationException is this is a <code>DataMapper</code>
080: * implemented by a {@link de.susebox.jtopas.TokenizerProperties}
081: * implementation
082: * @throws NullPointerException if no {@link TokenizerProperties} are given
083: */
084: public void setTokenizerProperties(TokenizerProperties props)
085: throws UnsupportedOperationException, NullPointerException;
086:
087: /**
088: * The method retrieves the backing {@link de.susebox.jtopas.TokenizerProperties}
089: * instance, this <code>DataMapper</code> is working on. For implementations
090: * of the <code>TokenizerProperties</code> interface that also implement the
091: * <code>DataMapper</code> interface, this method returns the instance itself.
092: *<br>
093: * Otherwise the method returns the <code>TokenizerProperties</code> instance
094: * passed through the last call to {@link #setTokenizerProperties} or <code>null</code>
095: * if no such call has taken place so far.
096: *
097: * @return the backing {@link de.susebox.jtopas.TokenizerProperties} or <code>null</code>
098: */
099: public TokenizerProperties getTokenizerProperties();
100: }
|