mirror of https://github.com/apache/lucene.git
Fix DataInput/Output/RandomAccessInput javadocs, MIGRATE.txt to document endianness
Better document these methods directly, mentioning endianness, linking to appropriate varhandle constant, etc. Add blurb to MIGRATE.txt to call out the switch to little-endian to increase awareness.
This commit is contained in:
parent
9e0f3758d2
commit
321d274b79
|
@ -17,6 +17,12 @@
|
|||
|
||||
# Apache Lucene Migration Guide
|
||||
|
||||
## Directory API is now little endian (LUCENE-9047)
|
||||
|
||||
DataOutput's writeShort, writeInt, and writeLong methods now encode with
|
||||
LE byte order. If you have custom subclasses of DataInput/DataOutput, you
|
||||
will need to adjust them from BE byte order to LE byte order.
|
||||
|
||||
## NativeUnixDirectory removed and replaced by DirectIODirectory (LUCENE-8982)
|
||||
|
||||
Java 11 supports to use Direct IO without native wrappers from Java code.
|
||||
|
|
|
@ -73,9 +73,10 @@ public abstract class DataInput implements Cloneable {
|
|||
}
|
||||
|
||||
/**
|
||||
* Reads two bytes and returns a short.
|
||||
* Reads two bytes and returns a short (LE byte order).
|
||||
*
|
||||
* @see DataOutput#writeByte(byte)
|
||||
* @see DataOutput#writeShort(short)
|
||||
* @see BitUtil#VH_LE_SHORT
|
||||
*/
|
||||
public short readShort() throws IOException {
|
||||
final byte b1 = readByte();
|
||||
|
@ -84,9 +85,10 @@ public abstract class DataInput implements Cloneable {
|
|||
}
|
||||
|
||||
/**
|
||||
* Reads four bytes and returns an int.
|
||||
* Reads four bytes and returns an int (LE byte order).
|
||||
*
|
||||
* @see DataOutput#writeInt(int)
|
||||
* @see BitUtil#VH_LE_INT
|
||||
*/
|
||||
public int readInt() throws IOException {
|
||||
final byte b1 = readByte();
|
||||
|
@ -146,9 +148,10 @@ public abstract class DataInput implements Cloneable {
|
|||
}
|
||||
|
||||
/**
|
||||
* Reads eight bytes and returns a long.
|
||||
* Reads eight bytes and returns a long (LE byte order).
|
||||
*
|
||||
* @see DataOutput#writeLong(long)
|
||||
* @see BitUtil#VH_LE_LONG
|
||||
*/
|
||||
public long readLong() throws IOException {
|
||||
return (readInt() & 0xFFFFFFFFL) | (((long) readInt()) << 32);
|
||||
|
|
|
@ -63,11 +63,10 @@ public abstract class DataOutput {
|
|||
public abstract void writeBytes(byte[] b, int offset, int length) throws IOException;
|
||||
|
||||
/**
|
||||
* Writes an int as four bytes.
|
||||
*
|
||||
* <p>32-bit unsigned integer written as four bytes, low-order bytes first.
|
||||
* Writes an int as four bytes (LE byte order).
|
||||
*
|
||||
* @see DataInput#readInt()
|
||||
* @see BitUtil#VH_LE_INT
|
||||
*/
|
||||
public void writeInt(int i) throws IOException {
|
||||
writeByte((byte) i);
|
||||
|
@ -77,9 +76,10 @@ public abstract class DataOutput {
|
|||
}
|
||||
|
||||
/**
|
||||
* Writes a short as two bytes.
|
||||
* Writes a short as two bytes (LE byte order).
|
||||
*
|
||||
* @see DataInput#readShort()
|
||||
* @see BitUtil#VH_LE_SHORT
|
||||
*/
|
||||
public void writeShort(short i) throws IOException {
|
||||
writeByte((byte) i);
|
||||
|
@ -215,11 +215,10 @@ public abstract class DataOutput {
|
|||
}
|
||||
|
||||
/**
|
||||
* Writes a long as eight bytes.
|
||||
*
|
||||
* <p>64-bit unsigned integer written as eight bytes, low-order bytes first.
|
||||
* Writes a long as eight bytes (LE byte order).
|
||||
*
|
||||
* @see DataInput#readLong()
|
||||
* @see BitUtil#VH_LE_LONG
|
||||
*/
|
||||
public void writeLong(long i) throws IOException {
|
||||
writeInt((int) i);
|
||||
|
|
|
@ -17,6 +17,7 @@
|
|||
package org.apache.lucene.store;
|
||||
|
||||
import java.io.IOException;
|
||||
import org.apache.lucene.util.BitUtil; // javadocs
|
||||
|
||||
/**
|
||||
* Random Access Index API. Unlike {@link IndexInput}, this has no concept of file position, all
|
||||
|
@ -31,21 +32,24 @@ public interface RandomAccessInput {
|
|||
*/
|
||||
public byte readByte(long pos) throws IOException;
|
||||
/**
|
||||
* Reads a short at the given position in the file
|
||||
* Reads a short (LE byte order) at the given position in the file
|
||||
*
|
||||
* @see DataInput#readShort
|
||||
* @see BitUtil#VH_LE_SHORT
|
||||
*/
|
||||
public short readShort(long pos) throws IOException;
|
||||
/**
|
||||
* Reads an integer at the given position in the file
|
||||
* Reads an integer (LE byte order) at the given position in the file
|
||||
*
|
||||
* @see DataInput#readInt
|
||||
* @see BitUtil#VH_LE_INT
|
||||
*/
|
||||
public int readInt(long pos) throws IOException;
|
||||
/**
|
||||
* Reads a long at the given position in the file
|
||||
* Reads a long (LE byte order) at the given position in the file
|
||||
*
|
||||
* @see DataInput#readLong
|
||||
* @see BitUtil#VH_LE_LONG
|
||||
*/
|
||||
public long readLong(long pos) throws IOException;
|
||||
}
|
||||
|
|
Loading…
Reference in New Issue