Add cloned method to VBlob, add module info (#79)

Author: lopcode

README.md

@@ -20,7 +20,7 @@ repositories {
 }
 
 dependencies {
-    implementation("app.photofox.vips-ffm:vips-ffm-core:0.5.9")
+    implementation("app.photofox.vips-ffm:vips-ffm-core:0.5.10")
 }
 ```
 When running your project you must add: `--enable-native-access=ALL-UNNAMED` to your JVM runtime arguments. If you

core/build.gradle.kts

@@ -63,12 +63,6 @@ tasks.withType<JavaExec>().configureEach {
     javaLauncher.set(project.javaToolchains.launcherFor(java.toolchain))
 }
 
-tasks.withType<Jar>().configureEach {
-    manifest {
-        attributes("Automatic-Module-Name" to "app.photofox.vipsffm")
-    }
-}
-
 tasks.withType<Javadoc> {
     (options as StandardJavadocDocletOptions).tags("optionalArg")
 }

core/src/main/java/app/photofox/vipsffm/VBlob.java

@@ -29,22 +29,38 @@ public final class VBlob {
     }
 
     /**
-     * Gets the raw [MemorySegment] (C pointer) for this blob
-     * The memory address' lifetime is bound to the scope of the [arena]
-     * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing and you need to use it with [VipsHelper]
+     * @deprecated Replaced by {@link #getUnsafeStructAddress()}
      */
-    public MemorySegment getUnsafeAddress() {
+    @Deprecated(since = "0.5.10", forRemoval = true)
+    public MemorySegment getUnsafeAddress() throws VipsError {
+        return this.getUnsafeStructAddress();
+    }
+
+    /**
+     * Gets the raw {@link MemorySegment} (C pointer) for this VipsBlob struct
+     * You might want the data address instead {@link #getUnsafeDataAddress()}
+     * The memory address' lifetime is bound to the scope of the {@link #arena}
+     * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing and you
+     * need to use it with {@link VipsHelper}
+     */
+    public MemorySegment getUnsafeStructAddress() throws VipsError {
         return this.address;
     }
 
     /**
      * Not recommended for use, use {@link #asByteBuffer()} instead
-     * Gets the raw [MemorySegment] (C pointer) for the data in this blob
+     * Gets the raw {@link MemorySegment} (C pointer) for the data in this blob
      * Sliced to the length of the data, which isn't always null terminated
      */
-    public MemorySegment getUnsafeDataAddress() {
+    public MemorySegment getUnsafeDataAddress() throws VipsError {
         var lengthOutPointer = arena.allocate(C_LONG);
-        var dataPointer = VipsRaw.vips_area_get_data(this.address, lengthOutPointer, MemorySegment.NULL, MemorySegment.NULL, MemorySegment.NULL);
+        var dataPointer = VipsRaw.vips_area_get_data(
+            this.address,
+            lengthOutPointer,
+            MemorySegment.NULL,
+            MemorySegment.NULL,
+            MemorySegment.NULL
+        );
         var length = lengthOutPointer.get(C_LONG, 0);
         if (length < 0) {
             throw new VipsError("unexpected length of vblob data " + length);
@@ -60,10 +76,35 @@ public long byteSize() {
     }
 
     /**
-     * ByteBuffer representation of the data in this blob
-     * Likely mapped to native memory, hence does not make a copy
+     * @deprecated Replaced by {@link #asArenaScopedByteBuffer()}
      */
+    @Deprecated(since = "0.5.10", forRemoval = true)
     public ByteBuffer asByteBuffer() {
+        return this.asArenaScopedByteBuffer();
+    }
+
+    /**
+     * ByteBuffer representation of the data in this blob
+     * Mapped to native memory via {@link java.nio.DirectByteBuffer}, hence does not make a copy, so the data has the
+     * same data lifetime as {@link #arena}
+     */
+    public ByteBuffer asArenaScopedByteBuffer() {
         return this.getUnsafeDataAddress().asByteBuffer();
     }
+
+    /**
+     * ByteBuffer representation of the data in this blob
+     * A full copy of the data is taken, so that its contents are not coupled to the scope of {@link #arena}
+     */
+    public ByteBuffer asClonedByteBuffer() {
+        var buffer = this.asArenaScopedByteBuffer();
+        if (buffer.capacity() == 0) {
+            return ByteBuffer.allocate(0);
+        }
+        buffer.rewind();
+        var newBuffer = ByteBuffer.allocate(buffer.capacity());
+        buffer.put(newBuffer);
+        newBuffer.rewind();
+        return newBuffer;
+    }
 }

core/src/main/java/app/photofox/vipsffm/VImage.java

@@ -15,6 +15,7 @@
 import app.photofox.vipsffm.enums.VipsOperationMorphology;
 import app.photofox.vipsffm.enums.VipsOperationRelational;
 import app.photofox.vipsffm.enums.VipsOperationRound;
+import java.lang.Deprecated;
 import java.lang.Double;
 import java.lang.Integer;
 import java.lang.Object;
@@ -57,11 +58,22 @@ public boolean equals(Object o) {
   }
 
   /**
-   * Gets the raw [MemorySegment] (C pointer) for this image
-   * The memory address' lifetime is bound to the scope of the [arena]
-   * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing and you need to use it with [VipsHelper]
+   * @deprecated See {@link #getUnsafeStructAddress}
    */
+  @Deprecated(
+      since = "0.5.10",
+      forRemoval = true
+  )
   public MemorySegment getUnsafeAddress() {
+    return this.getUnsafeStructAddress();
+  }
+
+  /**
+   * Gets the raw {@link MemorySegment} (C pointer) for this VipsImage struct
+   * The memory address' lifetime is bound to the scope of the {@link #arena}
+   * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing and you need to use it with {@link VipsHelper}
+   */
+  public MemorySegment getUnsafeStructAddress() {
     return this.address;
   }
 

core/src/main/java/app/photofox/vipsffm/VInterpolate.java

@@ -28,6 +28,16 @@ public int hashCode() {
         return Objects.hashCode(address);
     }
 
+    /**
+     * Gets the raw {@link MemorySegment} (C pointer) for this VipsInterpolate struct
+     * The memory address' lifetime is bound to the scope of the arena that created it
+     * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing, and
+     * you need to use it with {@link VipsHelper}
+     */
+    public MemorySegment getUnsafeStructAddress() {
+        return this.address;
+    }
+
     public static VInterpolate newFromName(Arena arena, String name) throws VipsError {
         var address = VipsHelper.interpolate_new(arena, name);
         return new VInterpolate(address);

core/src/main/java/app/photofox/vipsffm/VSource.java

@@ -17,11 +17,37 @@ public final class VSource {
         this.address = address;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof VSource vSource)) return false;
+
+        return address.equals(vSource.address);
+    }
+
+    @Override
+    public int hashCode() {
+        return address.hashCode();
+    }
+
     /**
-     * Gets the raw [MemorySegment] (C pointer) for this source
-     * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing and you need to use it with [VipsHelper]
+     * @deprecated See {@link #getUnsafeStructAddress}
      */
+    @Deprecated(
+        since = "0.5.10",
+        forRemoval = true
+    )
     public MemorySegment getUnsafeAddress() {
+        return this.getUnsafeStructAddress();
+    }
+
+    /**
+     * Gets the raw {@link MemorySegment} (C pointer) for this VipsSource struct
+     * The memory address' lifetime is bound to the scope of the arena that created it
+     * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing, and
+     * you need to use it with {@link VipsHelper}
+     */
+    public MemorySegment getUnsafeStructAddress() {
         return this.address;
     }
 

core/src/main/java/app/photofox/vipsffm/VTarget.java

@@ -17,11 +17,37 @@ public class VTarget {
         this.address = address;
     }
 
+    @Override
+    public final boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof VTarget vTarget)) return false;
+
+        return address.equals(vTarget.address);
+    }
+
+    @Override
+    public int hashCode() {
+        return address.hashCode();
+    }
+
     /**
-     * Gets the raw [MemorySegment] (C pointer) for this target
-     * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing and you need to use it with [VipsHelper]
+     * @deprecated See {@link #getUnsafeStructAddress}
      */
+    @Deprecated(
+        since = "0.5.10",
+        forRemoval = true
+    )
     public MemorySegment getUnsafeAddress() {
+        return this.getUnsafeStructAddress();
+    }
+
+    /**
+     * Gets the raw {@link MemorySegment} (C pointer) for this VipsTarget struct
+     * The memory address' lifetime is bound to the scope of the arena that created it
+     * Usage of the memory address is strongly discouraged, but it is available if some functionality is missing, and
+     * you need to use it with {@link VipsHelper}
+     */
+    public MemorySegment getUnsafeStructAddress() {
         return this.address;
     }
 

core/src/main/java/module-info.java

@@ -0,0 +1,5 @@
+ module app.photofox.vipffm {
+    exports app.photofox.vipsffm;
+    exports app.photofox.vipsffm.enums;
+    exports app.photofox.vipsffm.jextract;
+ }

generator/src/main/kotlin/vipsffm/GenerateVClasses.kt

@@ -3,6 +3,7 @@ package vipsffm
 import app.photofox.vipsffm.jextract.GEnumClass
 import app.photofox.vipsffm.jextract.GEnumValue
 import app.photofox.vipsffm.jextract.VipsRaw
+import com.squareup.javapoet.AnnotationSpec
 import com.squareup.javapoet.ArrayTypeName
 import com.squareup.javapoet.ClassName
 import com.squareup.javapoet.CodeBlock
@@ -135,10 +136,22 @@ object GenerateVClasses {
             .addStatement("if (!(o instanceof \$T vImage)) return false", vimageType)
             .addStatement("return Objects.equals(arena, vImage.arena) && Objects.equals(address, vImage.address)")
             .build()
-        val unsafeAddress = MethodSpec.methodBuilder("getUnsafeAddress")
-            .addJavadoc("Gets the raw [MemorySegment] (C pointer) for this image")
-            .addJavadoc("\nThe memory address' lifetime is bound to the scope of the [arena]")
-            .addJavadoc("\nUsage of the memory address is strongly discouraged, but it is available if some functionality is missing and you need to use it with [VipsHelper]")
+        val unsafeDeprecatedAddress = MethodSpec.methodBuilder("getUnsafeAddress")
+            .addJavadoc("@deprecated See {@link #getUnsafeStructAddress}")
+            .addStatement("return this.getUnsafeStructAddress()")
+            .returns(memorySegmentType)
+            .addModifiers(Modifier.PUBLIC)
+            .addAnnotation(
+                AnnotationSpec.builder(ClassName.get("java.lang", "Deprecated"))
+                    .addMember("since", "\"0.5.10\"")
+                    .addMember("forRemoval", "true")
+                    .build()
+            )
+            .build()
+        val unsafeStructAddress = MethodSpec.methodBuilder("getUnsafeStructAddress")
+            .addJavadoc("Gets the raw {@link MemorySegment} (C pointer) for this VipsImage struct")
+            .addJavadoc("\nThe memory address' lifetime is bound to the scope of the {@link #arena}")
+            .addJavadoc("\nUsage of the memory address is strongly discouraged, but it is available if some functionality is missing and you need to use it with {@link VipsHelper}")
             .addStatement("return this.address")
             .returns(memorySegmentType)
             .addModifiers(Modifier.PUBLIC)
@@ -150,7 +163,8 @@ object GenerateVClasses {
             .addMethod(ctor)
             .addMethod(hashCode)
             .addMethod(equals)
-            .addMethod(unsafeAddress)
+            .addMethod(unsafeDeprecatedAddress)
+            .addMethod(unsafeStructAddress)
             .addMethods(operationMethods)
             .addMethods(imageMethods)
             .addField(arenaType, "arena", Modifier.PRIVATE, Modifier.FINAL)

sample/src/main/kotlin/vipsffm/VBlobByteBufferSample.kt

@@ -17,7 +17,7 @@ object VBlobByteBufferSample: RunnableSample {
             .thumbnailImage(400)
 
         val blob = image.jpegsaveBuffer()
-        val bytes = blob.asByteBuffer()
+        val bytes = blob.asClonedByteBuffer()
         val rawDataSegment = blob.unsafeDataAddress
         val rawByteSize = blob.byteSize().toInt()