This is an automated email from the ASF dual-hosted git repository.
szehon-ho pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg.git
The following commit(s) were added to refs/heads/main by this push:
new 2a3ffa8bfe API, Core: Add missing @return Javadoc (#17394)
2a3ffa8bfe is described below
commit 2a3ffa8bfe3147ce53041a03e6d33deafa0b7e92
Author: Uros Bojanic <[email protected]>
AuthorDate: Fri Jul 31 19:42:05 2026 +0200
API, Core: Add missing @return Javadoc (#17394)
---
api/src/main/java/org/apache/iceberg/ManageSnapshots.java | 2 ++
api/src/main/java/org/apache/iceberg/SnapshotUpdate.java | 1 +
api/src/main/java/org/apache/iceberg/catalog/SessionCatalog.java | 1 +
api/src/main/java/org/apache/iceberg/catalog/SupportsNamespaces.java | 2 ++
api/src/main/java/org/apache/iceberg/io/FileIO.java | 1 +
api/src/main/java/org/apache/iceberg/util/BinaryUtil.java | 4 ++++
core/src/main/java/org/apache/iceberg/ManifestFilterManager.java | 1 +
core/src/main/java/org/apache/iceberg/MetricsConfig.java | 1 +
core/src/main/java/org/apache/iceberg/TrackedFile.java | 1 +
core/src/main/java/org/apache/iceberg/TrackingBuilder.java | 4 ++++
core/src/main/java/org/apache/iceberg/data/avro/RawDecoder.java | 1 +
.../org/apache/iceberg/encryption/NativeFileCryptoParameters.java | 1 +
core/src/main/java/org/apache/iceberg/formats/ReadBuilder.java | 3 +++
core/src/main/java/org/apache/iceberg/io/PartitionedFanoutWriter.java | 1 +
core/src/main/java/org/apache/iceberg/io/PartitionedWriter.java | 1 +
15 files changed, 25 insertions(+)
diff --git a/api/src/main/java/org/apache/iceberg/ManageSnapshots.java
b/api/src/main/java/org/apache/iceberg/ManageSnapshots.java
index 007bf94aef..5774c0d7f5 100644
--- a/api/src/main/java/org/apache/iceberg/ManageSnapshots.java
+++ b/api/src/main/java/org/apache/iceberg/ManageSnapshots.java
@@ -66,6 +66,7 @@ public interface ManageSnapshots extends
PendingUpdate<Snapshot> {
*
* @param snapshotId long id of snapshot id to roll back table to. Must be
an ancestor of the
* current snapshot
+ * @return this for method chaining
* @throws IllegalArgumentException If the table has no snapshot with the
given id
* @throws ValidationException If given snapshot id is not an ancestor of
the current state
*/
@@ -130,6 +131,7 @@ public interface ManageSnapshots extends
PendingUpdate<Snapshot> {
*
* @param name name of branch to rename
* @param newName the desired new name of the branch
+ * @return this for method chaining
* @throws IllegalArgumentException if the branch to rename does not exist
or if there is already
* a branch with the same name as the desired new name.
*/
diff --git a/api/src/main/java/org/apache/iceberg/SnapshotUpdate.java
b/api/src/main/java/org/apache/iceberg/SnapshotUpdate.java
index b57607cbf7..9ce946c0a0 100644
--- a/api/src/main/java/org/apache/iceberg/SnapshotUpdate.java
+++ b/api/src/main/java/org/apache/iceberg/SnapshotUpdate.java
@@ -80,6 +80,7 @@ public interface SnapshotUpdate<ThisT> extends
PendingUpdate<Snapshot> {
* Perform operations on a particular branch
*
* @param branch which is name of SnapshotRef of type branch.
+ * @return this for method chaining
*/
default ThisT toBranch(String branch) {
throw new UnsupportedOperationException(
diff --git a/api/src/main/java/org/apache/iceberg/catalog/SessionCatalog.java
b/api/src/main/java/org/apache/iceberg/catalog/SessionCatalog.java
index b545704853..ac6a1114eb 100644
--- a/api/src/main/java/org/apache/iceberg/catalog/SessionCatalog.java
+++ b/api/src/main/java/org/apache/iceberg/catalog/SessionCatalog.java
@@ -363,6 +363,7 @@ public interface SessionCatalog {
* @param namespace a {@link Namespace namespace}
* @param updates properties to set for the namespace
* @param removals properties to remove from the namespace
+ * @return true if the namespace metadata was successfully updated, false
otherwise
* @throws NoSuchNamespaceException If the namespace does not exist
(optional)
* @throws UnsupportedOperationException If namespace properties are not
supported
*/
diff --git
a/api/src/main/java/org/apache/iceberg/catalog/SupportsNamespaces.java
b/api/src/main/java/org/apache/iceberg/catalog/SupportsNamespaces.java
index 7c3af5fe57..fda96a324e 100644
--- a/api/src/main/java/org/apache/iceberg/catalog/SupportsNamespaces.java
+++ b/api/src/main/java/org/apache/iceberg/catalog/SupportsNamespaces.java
@@ -129,6 +129,7 @@ public interface SupportsNamespaces {
*
* @param namespace a namespace. {@link Namespace}
* @param properties a collection of metadata to apply to the namespace
+ * @return true if the properties were successfully set, false otherwise
* @throws NoSuchNamespaceException If the namespace does not exist
(optional)
* @throws UnsupportedOperationException If namespace properties are not
supported
*/
@@ -142,6 +143,7 @@ public interface SupportsNamespaces {
*
* @param namespace a namespace. {@link Namespace}
* @param properties a collection of metadata to apply to the namespace
+ * @return true if the properties were successfully removed, false otherwise
* @throws NoSuchNamespaceException If the namespace does not exist
(optional)
* @throws UnsupportedOperationException If namespace properties are not
supported
*/
diff --git a/api/src/main/java/org/apache/iceberg/io/FileIO.java
b/api/src/main/java/org/apache/iceberg/io/FileIO.java
index 78b61f60be..72d2d9b0fc 100644
--- a/api/src/main/java/org/apache/iceberg/io/FileIO.java
+++ b/api/src/main/java/org/apache/iceberg/io/FileIO.java
@@ -99,6 +99,7 @@ public interface FileIO extends Serializable, Closeable {
/**
* Returns the property map used to configure this FileIO
*
+ * @return the property map used to configure this FileIO
* @throws UnsupportedOperationException if this FileIO does not expose its
configuration
* properties
*/
diff --git a/api/src/main/java/org/apache/iceberg/util/BinaryUtil.java
b/api/src/main/java/org/apache/iceberg/util/BinaryUtil.java
index d94b25d0ae..5c44779ec0 100644
--- a/api/src/main/java/org/apache/iceberg/util/BinaryUtil.java
+++ b/api/src/main/java/org/apache/iceberg/util/BinaryUtil.java
@@ -37,6 +37,8 @@ public class BinaryUtil {
*
* @param input The ByteBuffer to be truncated
* @param length The non-negative length to truncate input to
+ * @return a ByteBuffer truncated to the given length, or the input if it is
already no longer
+ * than length
*/
public static ByteBuffer truncateBinary(ByteBuffer input, int length) {
Preconditions.checkArgument(length >= 0, "Truncate length should be
non-negative");
@@ -57,6 +59,8 @@ public class BinaryUtil {
*
* @param value The ByteBuffer to be truncated
* @param width The non-negative length to truncate input to
+ * @return a ByteBuffer view of the input truncated to the given width,
sharing the input's
+ * backing data
*/
public static ByteBuffer truncateBinaryUnsafe(ByteBuffer value, int width) {
ByteBuffer ret = value.duplicate();
diff --git a/core/src/main/java/org/apache/iceberg/ManifestFilterManager.java
b/core/src/main/java/org/apache/iceberg/ManifestFilterManager.java
index c418afacd3..3b9627634f 100644
--- a/core/src/main/java/org/apache/iceberg/ManifestFilterManager.java
+++ b/core/src/main/java/org/apache/iceberg/ManifestFilterManager.java
@@ -251,6 +251,7 @@ abstract class ManifestFilterManager<F extends
ContentFile<F>> {
* Creates a snapshot summary builder with the files deleted from the set of
filtered manifests.
*
* @param manifests a set of filtered manifests
+ * @return a snapshot summary builder describing the files deleted from the
filtered manifests
*/
SnapshotSummary.Builder buildSummary(Iterable<ManifestFile> manifests) {
SnapshotSummary.Builder summaryBuilder = SnapshotSummary.builder();
diff --git a/core/src/main/java/org/apache/iceberg/MetricsConfig.java
b/core/src/main/java/org/apache/iceberg/MetricsConfig.java
index 2522c57f13..87dae4c95d 100644
--- a/core/src/main/java/org/apache/iceberg/MetricsConfig.java
+++ b/core/src/main/java/org/apache/iceberg/MetricsConfig.java
@@ -115,6 +115,7 @@ public final class MetricsConfig implements Serializable {
* Creates a metrics config from a table.
*
* @param table iceberg table
+ * @return a metrics config for the given table
*/
public static MetricsConfig forTable(Table table) {
return from(table.properties(), table.schema(), table.sortOrder());
diff --git a/core/src/main/java/org/apache/iceberg/TrackedFile.java
b/core/src/main/java/org/apache/iceberg/TrackedFile.java
index 1a457fb048..052d021aac 100644
--- a/core/src/main/java/org/apache/iceberg/TrackedFile.java
+++ b/core/src/main/java/org/apache/iceberg/TrackedFile.java
@@ -186,6 +186,7 @@ interface TrackedFile {
* Copies this tracked file with stats only for specific columns.
*
* @param requestedColumnIds table field IDs for which to keep stats
+ * @return a copy of this tracked file retaining stats only for the
requested columns
*/
TrackedFile copyWithStats(Set<Integer> requestedColumnIds);
diff --git a/core/src/main/java/org/apache/iceberg/TrackingBuilder.java
b/core/src/main/java/org/apache/iceberg/TrackingBuilder.java
index c5a11bc53c..3c733825e2 100644
--- a/core/src/main/java/org/apache/iceberg/TrackingBuilder.java
+++ b/core/src/main/java/org/apache/iceberg/TrackingBuilder.java
@@ -37,6 +37,7 @@ class TrackingBuilder {
* Creates a builder for a newly added file.
*
* @param newSnapshotId the snapshot ID in which the new tracking instance
will be committed
+ * @return a builder for a newly added file
*/
static TrackingBuilder added(long newSnapshotId) {
return new TrackingBuilder(newSnapshotId);
@@ -47,6 +48,7 @@ class TrackingBuilder {
*
* @param source source tracking from a manifest entry
* @param newSnapshotId the snapshot ID in which the new tracking instance
will be committed
+ * @return a builder for a tracking row derived from the source
*/
static TrackingBuilder from(Tracking source, long newSnapshotId) {
return new TrackingBuilder(source, newSnapshotId);
@@ -57,6 +59,7 @@ class TrackingBuilder {
*
* @param source source tracking from a manifest entry
* @param newSnapshotId the snapshot ID in which the new tracking instance
will be committed
+ * @return a DELETED tracking row derived from the source
*/
static Tracking deleted(Tracking source, long newSnapshotId) {
return terminal(EntryStatus.DELETED, source, newSnapshotId);
@@ -67,6 +70,7 @@ class TrackingBuilder {
*
* @param source source tracking from a manifest entry
* @param newSnapshotId the snapshot ID in which the new tracking instance
will be committed
+ * @return a REPLACED tracking row derived from the source
*/
static Tracking replaced(Tracking source, long newSnapshotId) {
return terminal(EntryStatus.REPLACED, source, newSnapshotId);
diff --git a/core/src/main/java/org/apache/iceberg/data/avro/RawDecoder.java
b/core/src/main/java/org/apache/iceberg/data/avro/RawDecoder.java
index 9f3cdfdad5..7b388a79c4 100644
--- a/core/src/main/java/org/apache/iceberg/data/avro/RawDecoder.java
+++ b/core/src/main/java/org/apache/iceberg/data/avro/RawDecoder.java
@@ -44,6 +44,7 @@ public class RawDecoder<D> extends
MessageDecoder.BaseDecoder<D> {
* @param readSchema an Iceberg schema to produce when reading
* @param readerFunction a function that produces a DatumReader from the
read schema
* @param writeSchema an Avro schema that describes serialized data to be
read
+ * @return a new decoder that produces datum instances described by the read
schema
*/
public static <D> RawDecoder<D> create(
org.apache.iceberg.Schema readSchema,
diff --git
a/core/src/main/java/org/apache/iceberg/encryption/NativeFileCryptoParameters.java
b/core/src/main/java/org/apache/iceberg/encryption/NativeFileCryptoParameters.java
index 143404edbc..93178c495d 100644
---
a/core/src/main/java/org/apache/iceberg/encryption/NativeFileCryptoParameters.java
+++
b/core/src/main/java/org/apache/iceberg/encryption/NativeFileCryptoParameters.java
@@ -45,6 +45,7 @@ public class NativeFileCryptoParameters {
*
* @param fileKey per-file encryption key. For example, used as "footer key"
DEK in Parquet
* encryption.
+ * @return a builder for creating {@link NativeFileCryptoParameters}
*/
public static Builder create(ByteBuffer fileKey) {
return new Builder(fileKey);
diff --git a/core/src/main/java/org/apache/iceberg/formats/ReadBuilder.java
b/core/src/main/java/org/apache/iceberg/formats/ReadBuilder.java
index 2809750970..05f8a4b7fd 100644
--- a/core/src/main/java/org/apache/iceberg/formats/ReadBuilder.java
+++ b/core/src/main/java/org/apache/iceberg/formats/ReadBuilder.java
@@ -43,6 +43,7 @@ public interface ReadBuilder<D, S> {
*
* @param start the start position for this read
* @param length the length of the range this read should scan
+ * @return this for method chaining
*/
ReadBuilder<D, S> split(long start, long length);
@@ -68,6 +69,7 @@ public interface ReadBuilder<D, S> {
* must respect this setting. The default value is <code>true</code>.
*
* @param caseSensitive indicates if filtering is case-sensitive
+ * @return this for method chaining
*/
ReadBuilder<D, S> caseSensitive(boolean caseSensitive);
@@ -78,6 +80,7 @@ public interface ReadBuilder<D, S> {
* the caller's responsibility to apply the filter again.
*
* @param filter the filter to set
+ * @return this for method chaining
*/
ReadBuilder<D, S> filter(Expression filter);
diff --git
a/core/src/main/java/org/apache/iceberg/io/PartitionedFanoutWriter.java
b/core/src/main/java/org/apache/iceberg/io/PartitionedFanoutWriter.java
index 8c196505ae..f93b49195e 100644
--- a/core/src/main/java/org/apache/iceberg/io/PartitionedFanoutWriter.java
+++ b/core/src/main/java/org/apache/iceberg/io/PartitionedFanoutWriter.java
@@ -54,6 +54,7 @@ public abstract class PartitionedFanoutWriter<T> extends
BaseTaskWriter<T> {
* <p>Any PartitionKey returned by this method can be reused by the
implementation.
*
* @param row a data row
+ * @return the PartitionKey for the given row
*/
protected abstract PartitionKey partition(T row);
diff --git a/core/src/main/java/org/apache/iceberg/io/PartitionedWriter.java
b/core/src/main/java/org/apache/iceberg/io/PartitionedWriter.java
index 50ca3dbb84..f7727784f7 100644
--- a/core/src/main/java/org/apache/iceberg/io/PartitionedWriter.java
+++ b/core/src/main/java/org/apache/iceberg/io/PartitionedWriter.java
@@ -62,6 +62,7 @@ public abstract class PartitionedWriter<T> extends
BaseTaskWriter<T> {
* <p>Any PartitionKey returned by this method can be reused by the
implementation.
*
* @param row a data row
+ * @return the PartitionKey for the given row
*/
protected abstract PartitionKey partition(T row);
