You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by rm...@apache.org on 2021/10/05 17:03:13 UTC
[lucene] branch main updated: Fix
DataInput/Output/RandomAccessInput javadocs,
MIGRATE.txt to document endianness
This is an automated email from the ASF dual-hosted git repository.
rmuir pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/lucene.git
The following commit(s) were added to refs/heads/main by this push:
new 321d274 Fix DataInput/Output/RandomAccessInput javadocs, MIGRATE.txt to document endianness
321d274 is described below
commit 321d274b79934f170b0a340f59a10e496c103e64
Author: Robert Muir <rm...@apache.org>
AuthorDate: Tue Oct 5 13:01:24 2021 -0400
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.
---
lucene/MIGRATE.md | 6 ++++++
lucene/core/src/java/org/apache/lucene/store/DataInput.java | 11 +++++++----
.../core/src/java/org/apache/lucene/store/DataOutput.java | 13 ++++++-------
.../src/java/org/apache/lucene/store/RandomAccessInput.java | 10 +++++++---
4 files changed, 26 insertions(+), 14 deletions(-)
diff --git a/lucene/MIGRATE.md b/lucene/MIGRATE.md
index 81ae114..9508e7e 100644
--- a/lucene/MIGRATE.md
+++ b/lucene/MIGRATE.md
@@ -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.
diff --git a/lucene/core/src/java/org/apache/lucene/store/DataInput.java b/lucene/core/src/java/org/apache/lucene/store/DataInput.java
index f68bad5..d935cb3 100644
--- a/lucene/core/src/java/org/apache/lucene/store/DataInput.java
+++ b/lucene/core/src/java/org/apache/lucene/store/DataInput.java
@@ -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);
diff --git a/lucene/core/src/java/org/apache/lucene/store/DataOutput.java b/lucene/core/src/java/org/apache/lucene/store/DataOutput.java
index ca3d536..27c4a42 100644
--- a/lucene/core/src/java/org/apache/lucene/store/DataOutput.java
+++ b/lucene/core/src/java/org/apache/lucene/store/DataOutput.java
@@ -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);
diff --git a/lucene/core/src/java/org/apache/lucene/store/RandomAccessInput.java b/lucene/core/src/java/org/apache/lucene/store/RandomAccessInput.java
index 2da3403..3c73506 100644
--- a/lucene/core/src/java/org/apache/lucene/store/RandomAccessInput.java
+++ b/lucene/core/src/java/org/apache/lucene/store/RandomAccessInput.java
@@ -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;
}