org.apache.lucene.util.encoding
Class IntEncoder

java.lang.Object
  org.apache.lucene.util.encoding.IntEncoder

Direct Known Subclasses:

ChunksIntEncoder, IntEncoderFilter, SimpleIntEncoder, VInt8IntEncoder

public abstract class IntEncoder
extends Object

Encodes integers to a set OutputStream. Extending classes need to override encode(int) to encode the value using their encoding algorithm. The default implementation of close() closes the set OutputStream.

The default constructor is provided for convenience only. One must call reInit(OutputStream) before calling encode(int) or close().

For convenience, each encoder implements createMatchingDecoder() for easy access to the matching decoder.

NOTE: some implementations may buffer the encoded values in memory (such as IntEncoderFilter implementations) and encoding will happen only upon calling close(). Therefore it is important to always call close() on the encoder at hand.

NOTE: encoders are usually not thread safe, unless specifically documented otherwise by an implementation.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Field Summary

protected OutputStream

out

Constructor Summary

IntEncoder()
Default constructor, provided here for robustness: if in the future a constructor with parameters will be added, this might break custom implementations of this class which call this implicit constructor.

Method Summary

void	close() Instructs the encoder to finish the encoding process.
abstract IntDecoder	createMatchingDecoder() Returns an IntDecoder which matches this encoder.
abstract void	encode(int value) Encodes an integer to the output stream given in reInit
void	reInit(OutputStream out) Reinitializes the encoder with the give OutputStream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

out

protected OutputStream out

Constructor Detail

IntEncoder

public IntEncoder()

Default constructor, provided here for robustness: if in the future a constructor with parameters will be added, this might break custom implementations of this class which call this implicit constructor. So we make it explicit to avoid any such issue in the future.

Method Detail

close

public void close()
           throws IOException

Instructs the encoder to finish the encoding process. This method closes the output stream which was specified by reInit. An implementation may do here additional cleanup required to complete the encoding, such as flushing internal buffers, etc.
Once this method was called, no further calls to encode should be made before first calling reInit.

NOTE: overriding classes should make sure they either call super.close() or close the output stream themselves.

Throws:

IOException

encode

public abstract void encode(int value)
                     throws IOException

Encodes an integer to the output stream given in reInit

Throws:

IOException

createMatchingDecoder

public abstract IntDecoder createMatchingDecoder()

Returns an IntDecoder which matches this encoder. Every encoder must return an IntDecoder and null is not a valid value. If an encoder is just a filter, it should at least return its wrapped encoder's matching decoder.

NOTE: this method should create a new instance of the matching decoder and leave the instance sharing to the caller. Returning the same instance over and over is risky because encoders and decoders are not thread safe.

reInit

public void reInit(OutputStream out)

Reinitializes the encoder with the give OutputStream. For re-usability it can be changed without the need to reconstruct a new object.

NOTE: after calling close(), one must call this method even if the output stream itself hasn't changed. An example case is that the output stream wraps a byte[], and the output stream itself is reset, but its instance hasn't changed. Some implementations of IntEncoder may write some metadata about themselves to the output stream, and therefore it is imperative that one calls this method before encoding any data.