001: package it.unimi.dsi.mg4j.index.payload;
002:
003: /*
004: * MG4J: Managing Gigabytes for Java
005: *
006: * Copyright (C) 2007 Paolo Boldi and Sebastiano Vigna
007: *
008: * This library is free software; you can redistribute it and/or modify it
009: * under the terms of the GNU Lesser General Public License as published by the Free
010: * Software Foundation; either version 2.1 of the License, or (at your option)
011: * any later version.
012: *
013: * This library is distributed in the hope that it will be useful, but
014: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
015: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
016: * for more details.
017: *
018: * You should have received a copy of the GNU Lesser General Public License
019: * along with this program; if not, write to the Free Software
020: * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
021: *
022: */
023:
024: import it.unimi.dsi.io.InputBitStream;
025: import it.unimi.dsi.io.OutputBitStream;
026: import it.unimi.dsi.mg4j.search.DocumentIteratorBuilderVisitor;
027:
028: import java.io.IOException;
029: import java.io.Serializable;
030:
031: import org.apache.commons.collections.Predicate;
032:
033: /** An index payload.
034: *
035: * <p>The main responsibility of this class is that of providing efficient
036: * ways to read and write a payload from and to bit streams. An instance of this
037: * class has at any given time a <em>current value</em>, which is set when
038: * {@linkplain #read(InputBitStream) reading}.
039: * and output when {@linkplain #write(OutputBitStream) writing}.
040: *
041: * <p>The current value can be modified using {@link #set(Object)}, and
042: * each implementation must document thoroughly which objects are
043: * accepted by this method.
044: *
045: * <p>It is expected that in most implementations reading and writing is
046: * much more efficient than reading, {@linkplain #get() getting a value},
047: * {@linkplain #set(Object) setting that value} in another instance, and
048: * finally {@linkplain #write(OutputBitStream) writing}.
049: *
050: * <p>Implementation of a payload might have parameters. If you need to know
051: * whether two instances are <em>compatible</em>, in the sense that each
052: * instance can read correctly data written by the other one, you can invoke
053: * the {@link #compatibleWith(Payload)} method.
054: *
055: * <p>Optionally, implementations can feature a <code>parse(String)</code> method
056: * that returns an object of the correct type for {@link #set(Object)}. This method
057: * can be used (for instance, by reflection) to try to build a payload from a string
058: * specification (this is what happens in {@link DocumentIteratorBuilderVisitor}).
059: */
060:
061: public interface Payload extends Serializable, Comparable<Payload> {
062:
063: /** Serialises the current value of this payload to the given output bit stream.
064: *
065: * @param obs the bit stream receiving the bits.
066: * @return the number of bits written.
067: * @throws IllegalStateException if this serialiser contains no object.
068: */
069: int write(OutputBitStream obs) throws IOException;
070:
071: /** Sets the current value of this payload by reading from an input bit stream.
072: *
073: * @param ibs a bit stream.
074: * @return the number of bits read.
075: */
076: int read(InputBitStream ibs) throws IOException;
077:
078: /** Returns the value of this payload.
079: *
080: * <p>Implementing classes are expected to override covariantly the return
081: * value to the actual class stored by the payload.
082: *
083: * @return the current value of this payload.
084: */
085: Object get();
086:
087: /** Sets the current value of this payload.
088: *
089: * @param o the new value of this payload.
090: */
091: void set(Object o);
092:
093: /** Returns a copy of this payload.
094: *
095: * <p>Implementing classes are expected to override covariantly the return
096: * value to the actual payload type.
097: *
098: * @return a copy of this payload.
099: */
100: Payload copy();
101:
102: /** Returns true if this payload instance is compatible with another instance.
103: *
104: * @return true if this payload instance is compatible with another instance.
105: */
106: boolean compatibleWith(Payload payload);
107:
108: /** Returns a payload filter matching the interval defined by the given parameters.
109: *
110: * @param left the left extreme of the interval (inclusive). It will be cached (but not copied) internally.
111: * @param right the right extreme of the interval (exclusive). It will be cached (but not copied) internally.
112: * @return a payload filter for the interval defined above.
113: */
114: public Predicate rangeFilter(final Payload left, final Payload right);
115: }
|