org.apache.lucene.store
Class DataOutput

java.lang.Object
  extended by org.apache.lucene.store.DataOutput
Direct Known Subclasses:
ByteArrayDataOutput, 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
DataOutput()
           
 
Method Summary
 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 writeInt(int i)
          Writes an int as four bytes.
 void writeLong(long i)
          Writes a long as eight bytes.
 void writeShort(short i)
          Writes a short as two bytes.
 void writeString(String s)
          Writes a string.
 void writeStringSet(Set<String> set)
          Writes a String set.
 void writeStringStringMap(Map<String,String> map)
          Writes a String map.
 void writeVInt(int i)
          Writes an int in a variable-length format.
 void writeVLong(long i)
          Writes an long in a variable-length format.
 
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.

32-bit unsigned integer written as four bytes, high-order bytes first.

Throws:
IOException
See Also:
DataInput.readInt()

writeShort

public void writeShort(short i)
                throws IOException
Writes a short as two bytes.

Throws:
IOException
See Also:
DataInput.readShort()

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

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()

writeLong

public void writeLong(long i)
               throws IOException
Writes a long as eight bytes.

64-bit unsigned integer written as eight bytes, high-order bytes first.

Throws:
IOException
See Also:
DataInput.readLong()

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()

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

writeStringStringMap

public void writeStringStringMap(Map<String,String> map)
                          throws IOException
Writes a String map.

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

Parameters:
map - Input map. May be null (equivalent to an empty map)
Throws:
IOException

writeStringSet

public void writeStringSet(Set<String> set)
                    throws IOException
Writes a String set.

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

Parameters:
set - Input set. May be null (equivalent to an empty set)
Throws:
IOException


Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.