This is an automated email from the ASF dual-hosted git repository. leerho pushed a commit to branch integrateJava17_v3 in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git
commit 7791ddcc355fa52f57d039df548af750d851a9cb Author: Lee Rhodes <[email protected]> AuthorDate: Tue Jun 4 08:54:21 2024 -0700 fix typos, etc. --- pom.xml | 11 ++++++-- .../org/apache/datasketches/memory/BaseState.java | 17 +++++++++--- .../apache/datasketches/memory/WritableBuffer.java | 1 - .../memory/internal/BaseStateImpl.java | 4 +-- .../memory/internal/BaseWritableBufferImpl.java | 8 ++++++ .../memory/internal/BaseWritableMemoryImpl.java | 31 +++++++++++++++++++--- .../memory/internal/MurmurHash3v3.java | 1 - .../datasketches/memory/internal/package-info.java | 3 +++ tools/scripts/run-javadocs.sh | 25 +++++++++++++++++ 9 files changed, 88 insertions(+), 13 deletions(-) diff --git a/pom.xml b/pom.xml index 0928bd1..73a96a8 100644 --- a/pom.xml +++ b/pom.xml @@ -96,7 +96,7 @@ under the License. <maven-enforcer-plugin.version>3.4.1</maven-enforcer-plugin.version> <maven-gpg-plugin.version>3.2.3</maven-gpg-plugin.version> <maven-jar-plugin.version>3.4.0</maven-jar-plugin.version> - <maven-javadoc-plugin.version>3.6.3</maven-javadoc-plugin.version> + <maven-javadoc-plugin.version>3.7.0</maven-javadoc-plugin.version> <maven-release-plugin.version>3.0.1</maven-release-plugin.version> <maven-remote-resources-plugin.version>3.2.0</maven-remote-resources-plugin.version> <maven-source-plugin.version>3.3.1</maven-source-plugin.version> @@ -229,8 +229,14 @@ under the License. <artifactId>maven-javadoc-plugin</artifactId> <version>${maven-javadoc-plugin.version}</version> <configuration> - <docfilessubdirs>true</docfilessubdirs> + <show>public</show> + <packages>org.apache.datasketches.memory</packages> + <excludePackageNames>org.apache.datasketches.memory/internal</excludePackageNames> + <additionalOptions> + <additionalOption>--add-modules=jdk.incubator.foreign</additionalOption> + </additionalOptions> </configuration> + <executions> <execution> <id>attach-javadocs</id> @@ -274,6 +280,7 @@ under the License. <artifactId>maven-surefire-plugin</artifactId> <version>${maven-surefire-plugin.version}</version> <configuration> + <argLine>--add-modules=jdk.incubator.foreign</argLine> <trimStackTrace>false</trimStackTrace> <useManifestOnlyJar>false</useManifestOnlyJar> <redirectTestOutputToFile>true</redirectTestOutputToFile> diff --git a/src/main/java/org/apache/datasketches/memory/BaseState.java b/src/main/java/org/apache/datasketches/memory/BaseState.java index 583f95d..4280d20 100644 --- a/src/main/java/org/apache/datasketches/memory/BaseState.java +++ b/src/main/java/org/apache/datasketches/memory/BaseState.java @@ -38,7 +38,14 @@ public interface BaseState { */ static final String LS = System.getProperty("line.separator"); + /** + * The static final for <i>ByteOrder.nativeOrder()</i>. + */ static final ByteOrder NATIVE_BYTE_ORDER = ByteOrder.nativeOrder(); + + /** + * The static final for NON <i>ByteOrder.nativeOrder()</i>. + */ static final ByteOrder NON_NATIVE_BYTE_ORDER = (ByteOrder.nativeOrder() == ByteOrder.LITTLE_ENDIAN) ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN; @@ -93,8 +100,8 @@ public interface BaseState { /** * Forces any changes made to the contents of this mapped segment to be written to the storage device described - * by the mapped segment's file descriptor. Please refer to - * <a href="https://docs.oracle.com/en/java/javase/17/docs/api/jdk.incubator.foreign/jdk/incubator/foreign/MemorySegment.html#force()">force()</a> + * by the mapped segment's file descriptor. + * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/api/jdk.incubator.foreign/jdk/incubator/foreign/MemorySegment.html#force()">force()</a> */ void force(); @@ -107,9 +114,9 @@ public interface BaseState { /** * Gets the relative base offset of <i>this</i> with respect to <i>that</i>, defined as: <i>this</i> - <i>that</i>. * This method is only valid for <i>native</i> (off-heap) allocated resources. - * @throws IllegalArgumentException if one of the resources is on-heap. * @param that the given resource. * @return <i>this</i> - <i>that</i> offset + * @throws IllegalArgumentException if one of the resources is on-heap. */ long getRelativeOffset(BaseState that); @@ -220,6 +227,8 @@ public interface BaseState { /** * Returns true if the underlying resource is the same underlying resource as <i>that</i>. + * @param that the other BaseState object + * @return a long value representing the ordering and size of overlap between <i>this</i> and <i>that</i> */ boolean isSameResource(BaseState that); @@ -241,7 +250,7 @@ public interface BaseState { long nativeOverlap(BaseState that); /** - * See <a href="https://docs.oracle.com/en/java/javase/17/docs/api/jdk.incubator.foreign/jdk/incubator/foreign/MemorySegment.html#mismatch(jdk.incubator.foreign.MemorySegment)>mismatch</a> + * See <a href="https://docs.oracle.com/en/java/javase/17/docs/api/jdk.incubator.foreign/jdk/incubator/foreign/MemorySegment.html#mismatch(jdk.incubator.foreign.MemorySegment)">mismatch> </a> * @param that the other BaseState * @return the relative offset, in bytes, of the first mismatch between this and the given other BaseState object, * otherwise -1 if no mismatch diff --git a/src/main/java/org/apache/datasketches/memory/WritableBuffer.java b/src/main/java/org/apache/datasketches/memory/WritableBuffer.java index 1854558..7b2ffb9 100644 --- a/src/main/java/org/apache/datasketches/memory/WritableBuffer.java +++ b/src/main/java/org/apache/datasketches/memory/WritableBuffer.java @@ -17,7 +17,6 @@ * under the License. */ - package org.apache.datasketches.memory; import java.nio.ByteBuffer; diff --git a/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java b/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java index 6f3a5c8..9523619 100644 --- a/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java +++ b/src/main/java/org/apache/datasketches/memory/internal/BaseStateImpl.java @@ -304,8 +304,8 @@ abstract class BaseStateImpl implements BaseState { @Override public final long getRelativeOffset(final BaseState that) { - final BaseStateImpl that2 = (BaseStateImpl) that; - return this.seg.address().segmentOffset(that2.seg); + final BaseStateImpl that2 = (BaseStateImpl) that; + return this.seg.address().segmentOffset(that2.seg); } @Override diff --git a/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java b/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java index 773a565..d1bb61a 100644 --- a/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java +++ b/src/main/java/org/apache/datasketches/memory/internal/BaseWritableBufferImpl.java @@ -63,6 +63,14 @@ public abstract class BaseWritableBufferImpl extends BaseBufferImpl implements W //BYTE BUFFER RESOURCE + /** + * The implementation of <i>wrapByteBuffer</i> for WritableBuffer. + * @param byteBuffer the given <i>ByteBuffer</i> + * @param localReadOnly true is read-only is being imposed locally, independent of the read-only state of the given ByteBuffer. + * @param byteOrder the given <i>ByteOrder</i>. + * @param memReqSvr the given <i>MemoryRequestServer</i>. + * @return a <i>WritableBuffer</i>. + */ public static WritableBuffer wrapByteBuffer( final ByteBuffer byteBuffer, final boolean localReadOnly, diff --git a/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java b/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java index 660a900..82f89f3 100644 --- a/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java +++ b/src/main/java/org/apache/datasketches/memory/internal/BaseWritableMemoryImpl.java @@ -68,6 +68,13 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr //WRAP HEAP ARRAY RESOURCE + /** + * Wrap a <i>MemorySegment</i> as an array + * @param seg the given <i>MemorySegment</i>. + * @param byteOrder the given <i>ByteOrder</i>. + * @param memReqSvr the given <i>MemoryRequestServer</i>. + * @return a <i>WritableMemory</i>. + */ public static WritableMemory wrapSegmentAsArray( final MemorySegment seg, final ByteOrder byteOrder, @@ -84,6 +91,14 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr //BYTE BUFFER RESOURCE + /** + * The implementation of <i>wrapByteBuffer</i> for WritableMemory. + * @param byteBuffer the given <i>ByteBuffer</i> + * @param localReadOnly true if read-only is being imposed locally, independent of the read-only state of the given ByteBuffer. + * @param byteOrder the given <i>ByteOrder</i>. + * @param memReqSvr the given <i>MemoryRequestServer</i>. + * @return a <i>WritableMemory</i>. + */ public static WritableMemory wrapByteBuffer( final ByteBuffer byteBuffer, final boolean localReadOnly, @@ -122,7 +137,18 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr //MAP FILE RESOURCE - //@SuppressWarnings("resource") + /** + * The implementation of <i>wrapMap</i> for <i>WritableMemory</i>. + * @param file the given file to map. + * @param fileOffsetBytes the file starting offset in bytes. + * @param capacityBytes the capacity of the mapped memory. + * @param scope the given scope + * @param localReadOnly true if read-only is being imposed locally, independent of the read-only state of the given ByteBuffer. + * @param byteOrder the given <i>ByteOrder</i> + * @return a <i>WritableMemory</i> + * @throws IllegalArgumentException if file is not readable. + * @throws IOException if mapping is not successful. + */ public static WritableMemory wrapMap( final File file, final long fileOffsetBytes, @@ -130,7 +156,7 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr final ResourceScope scope, final boolean localReadOnly, final ByteOrder byteOrder) - throws IllegalArgumentException, IllegalStateException, IOException, SecurityException { + throws IllegalArgumentException, IOException { Objects.requireNonNull(file, "File must be non-null."); Objects.requireNonNull(byteOrder, "ByteOrder must be non-null."); Objects.requireNonNull(scope, "ResourceScope must be non-null."); @@ -319,7 +345,6 @@ public abstract class BaseWritableMemoryImpl extends BaseStateImpl implements Wr putByte(offsetBytes, value ? (byte)1 : 0); } - @Override public final void putByte(final long offsetBytes, final byte value) { MemoryAccess.setByteAtOffset(seg, offsetBytes, value); diff --git a/src/main/java/org/apache/datasketches/memory/internal/MurmurHash3v3.java b/src/main/java/org/apache/datasketches/memory/internal/MurmurHash3v3.java index c873120..e3936ce 100644 --- a/src/main/java/org/apache/datasketches/memory/internal/MurmurHash3v3.java +++ b/src/main/java/org/apache/datasketches/memory/internal/MurmurHash3v3.java @@ -341,7 +341,6 @@ public final class MurmurHash3v3 { return k2; } - /** * Final self mix of h*. * diff --git a/src/main/java/org/apache/datasketches/memory/internal/package-info.java b/src/main/java/org/apache/datasketches/memory/internal/package-info.java index 2a3bb7a..45023ac 100644 --- a/src/main/java/org/apache/datasketches/memory/internal/package-info.java +++ b/src/main/java/org/apache/datasketches/memory/internal/package-info.java @@ -17,4 +17,7 @@ * under the License. */ +/** + * The internal classes for Memory. + */ package org.apache.datasketches.memory.internal; diff --git a/tools/scripts/run-javadocs.sh b/tools/scripts/run-javadocs.sh new file mode 100755 index 0000000..35cebe7 --- /dev/null +++ b/tools/scripts/run-javadocs.sh @@ -0,0 +1,25 @@ +#!/bin/bash -e + +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +ProjectBaseDir=$1 #this must be an absolute path + +####Move to project directory#### +cd ${ProjectBaseDir} + +javadoc --add-modules=jdk.incubator.foreign --show-members public -d "target/site" -sourcepath "src/main/java" "org.apache.datasketches.memory" \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
