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:
Robert Muir 2021-10-05 13:01:24 -04:00
parent 9e0f3758d2
commit 321d274b79
No known key found for this signature in database
GPG Key ID: 817AE1DD322D7ECA
4 changed files with 26 additions and 14 deletions

View File

@ -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.

View File

@ -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);

View File

@ -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);

View File

@ -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;
}