Package org.apache.lucene.store

Class DataOutput

java.lang.Object

org.apache.lucene.store.DataOutput

Direct Known Subclasses:

ByteArrayDataOutput, ByteBuffersDataOutput, IndexOutput, OutputStreamDataOutput, PagedBytes.PagedBytesDataOutput

public abstract class DataOutput
extends Object

Abstract base class for performing write operations of Lucene's low-level data types.

DataOutput may only be used from one thread, because it is not thread safe (it keeps internal state like file position).

Constructor Summary

Constructors

Constructor	Description
DataOutput()

Method Summary

Modifier and Type	Method	Description
void	copyBytes(DataInput input, long numBytes)	Copy numBytes bytes from input to ourself.
abstract void	writeByte(byte b)	Writes a single byte.
void	writeBytes(byte[] b, int length)	Writes an array of bytes.
abstract void	writeBytes(byte[] b, int offset, int length)	Writes an array of bytes.
void	writeGroupVInts(long[] values, int limit)	Encode integers using group-varint.
void	writeInt(int i)	Writes an int as four bytes (LE byte order).
void	writeLong(long i)	Writes a long as eight bytes (LE byte order).
void	writeMapOfStrings(Map<String,String> map)	Writes a String map.
void	writeSetOfStrings(Set<String> set)	Writes a String set.
void	writeShort(short i)	Writes a short as two bytes (LE byte order).
void	writeString(String s)	Writes a string.
void	writeVInt(int i)	Writes an int in a variable-length format.
void	writeVLong(long i)	Writes an long in a variable-length format.
void	writeZInt(int i)	Write a zig-zag-encoded variable-length integer.
void	writeZLong(long i)	Write a zig-zag-encoded variable-length long.

Methods inherited from class java.lang.Object

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

Constructor Detail

DataOutput

public DataOutput()

Method Detail

writeByte

public abstract void writeByte(byte b)
                        throws IOException

Writes a single byte.

The most primitive data type is an eight-bit byte. Files are accessed as sequences of bytes. All other data types are defined as sequences of bytes, so file formats are byte-order independent.

Throws:

IOException

See Also:

DataInput.readByte()

writeBytes

public void writeBytes(byte[] b,
                       int length)
                throws IOException

Writes an array of bytes.

Parameters:

b - the bytes to write

length - the number of bytes to write

Throws:

IOException

See Also:

DataInput.readBytes(byte[],int,int)

writeBytes

public abstract void writeBytes(byte[] b,
                                int offset,
                                int length)
                         throws IOException

Writes an array of bytes.

Parameters:

b - the bytes to write

offset - the offset in the byte array

length - the number of bytes to write

Throws:

IOException

See Also:

DataInput.readBytes(byte[],int,int)

writeInt

public void writeInt(int i)
              throws IOException

Writes an int as four bytes (LE byte order).

Throws:

IOException

See Also:

DataInput.readInt(), BitUtil.VH_LE_INT

writeShort

public void writeShort(short i)
                throws IOException

Writes a short as two bytes (LE byte order).

Throws:

IOException

See Also:

DataInput.readShort(), BitUtil.VH_LE_SHORT

writeVInt

public final void writeVInt(int i)
                     throws IOException

Writes an int in a variable-length format. Writes between one and five bytes. Smaller values take fewer bytes. Negative numbers are supported, but should be avoided.

VByte is a variable-length format for positive integers is defined where the high-order bit of each byte indicates whether more bytes remain to be read. The low-order seven bits are appended as increasingly more significant bits in the resulting integer value. Thus values from zero to 127 may be stored in a single byte, values from 128 to 16,383 may be stored in two bytes, and so on.

VByte Encoding Example

variable length encoding examples

Value	Byte 1	Byte 2	Byte 3
0	00000000
1	00000001
2	00000010
...
127	01111111
128	10000000	00000001
129	10000001	00000001
130	10000010	00000001
...
16,383	11111111	01111111
16,384	10000000	10000000	00000001
16,385	10000001	10000000	00000001
...

This provides compression while still being efficient to decode.

Parameters:

i - Smaller values take fewer bytes. Negative numbers are supported, but should be avoided.

Throws:

IOException - If there is an I/O error writing to the underlying medium.

See Also:

DataInput.readVInt()

writeZInt

public final void writeZInt(int i)
                     throws IOException

Write a zig-zag-encoded variable-length integer. This is typically useful to write small signed ints and is equivalent to calling writeVInt(BitUtil.zigZagEncode(i)).

Throws:

IOException

See Also:

DataInput.readZInt()

writeLong

public void writeLong(long i)
               throws IOException

Writes a long as eight bytes (LE byte order).

Throws:

IOException

See Also:

DataInput.readLong(), BitUtil.VH_LE_LONG

writeVLong

public final void writeVLong(long i)
                      throws IOException

Writes an long in a variable-length format. Writes between one and nine bytes. Smaller values take fewer bytes. Negative numbers are not supported.

The format is described further in writeVInt(int).

Throws:

IOException

See Also:

DataInput.readVLong()

writeZLong

public final void writeZLong(long i)
                      throws IOException

Write a zig-zag-encoded variable-length long. Writes between one and ten bytes. This is typically useful to write small signed ints.

Throws:

IOException

See Also:

DataInput.readZLong()

writeString

public void writeString(String s)
                 throws IOException

Writes a string.

Writes strings as UTF-8 encoded bytes. First the length, in bytes, is written as a VInt, followed by the bytes.

Throws:

IOException

See Also:

DataInput.readString()

copyBytes

public void copyBytes(DataInput input,
                      long numBytes)
               throws IOException

Copy numBytes bytes from input to ourself.

Throws:

IOException

writeMapOfStrings

public void writeMapOfStrings(Map<String,String> map)
                       throws IOException

Writes a String map.

First the size is written as an vInt, followed by each key-value pair written as two consecutive Strings.

Parameters:

map - Input map.

Throws:

NullPointerException - if map is null.

IOException

writeSetOfStrings

public void writeSetOfStrings(Set<String> set)
                       throws IOException

Writes a String set.

First the size is written as an vInt, followed by each value written as a String.

Parameters:

set - Input set.

Throws:

NullPointerException - if set is null.

IOException

writeGroupVInts

public void writeGroupVInts(long[] values,
                            int limit)
                     throws IOException

Encode integers using group-varint. It uses VInt to encode tail values that are not enough for a group. we need a long[] because this is what postings are using, all longs are actually required to be integers.

Parameters:

values - the values to write

limit - the number of values to write.

Throws:

IOException

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