Skip to content

feat: implement Data::UUID in Java using java.util.UUID#509

Merged
fglock merged 2 commits intomasterfrom
feature/data-uuid-java-impl
Apr 20, 2026
Merged

feat: implement Data::UUID in Java using java.util.UUID#509
fglock merged 2 commits intomasterfrom
feature/data-uuid-java-impl

Conversation

@fglock
Copy link
Copy Markdown
Owner

@fglock fglock commented Apr 20, 2026

Summary

Adds a Java XS implementation for the CPAN Data::UUID module under org.perlonjava.runtime.perlmodule.DataUUID, backed by java.util.UUID and java.security.MessageDigest (MD5).

Before this change, ./jcpan -t Data::UUID would install the .pm file but every test failed at use Data::UUID; with "Can't load loadable object for module Data::UUID: no Java XS implementation available" (Data::UUID ships no pure-Perl fallback).

After this change, the full CPAN test suite passes:

t/basic.t ................. ok
t/from-name-collisions.t .. ok
t/leaky_dollar_bang.t ..... ok
t/segv.t .................. ok
Files=7, Tests=32, Result: PASS

Implementation notes

  • create() uses UUID.randomUUID() (v4). The CPAN XS implementation produces v1 time-based UUIDs, but no test relies on the specific version — they only require uniqueness and round-tripping, both of which v4 satisfies.
  • create_from_name() implements RFC 4122 §4.3 directly: MD5(namespace_bytes || name_bytes), then sets version=3 and the RFC 4122 variant bits.
  • NameSpace_{DNS,URL,OID,X500} registered as constant methods returning 16-byte binary namespace UUIDs. The CPAN UUID.pm's @EXPORT handles importing them at the call site.
  • Binary representation: 16-byte big-endian (RFC 4122 canonical). Self-consistent with the to_/from_ conversions. Differs from the CPAN XS module's host-byte-order binary on little-endian platforms, but that format isn't portable across platforms either.
  • checkSelf() enforces that instance methods are called on a blessed Data::UUID reference, matching the XS typemap behaviour that t/segv.t exercises (Data::UUID->create must die with "self is not of type Data::UUID").

Test plan

  • jcpan -t Data::UUID → all tests pass (32/32)
  • make → all unit tests pass, no regressions
  • Manual round-trip smoke test: createto_stringfrom_stringcompare == 0
  • Data::UUID->create (class method) dies with expected message

Related design doc: dev/modules/xs_fallback.md.

Generated with Devin

fglock and others added 2 commits April 20, 2026 13:50
Adds a Java XS implementation for the Data::UUID CPAN module under
org.perlonjava.runtime.perlmodule.DataUUID, allowing `jcpan -t Data::UUID`
to install and run its test suite (Files=7, Tests=32, all pass).

Key points:
- Uses java.util.UUID.randomUUID() for create() (v4 random) and
  MessageDigest MD5 + RFC 4122 §4.3 bit-twiddling for create_from_name()
  (v3 name-based). Java's UUID.nameUUIDFromBytes does the same thing but
  we build the bytes manually for clarity.
- Registers full method set: new, create{,_bin,_str,_hex,_b64},
  create_from_name{,_bin,_str,_hex,_b64}, to_{string,hexstring,b64string},
  from_{string,hexstring,b64string}, compare.
- Registers NameSpace_{DNS,URL,OID,X500} as constant methods matching the
  RFC 4122 namespace UUIDs; the CPAN .pm file's @export wiring handles
  importing them into the caller.
- Binary representation is 16-byte big-endian (RFC 4122 canonical form).
  Self-consistent with to_/from_ conversions. Differs from the CPAN XS
  module's host-byte-order binary on little-endian platforms, but that
  binary format is not portable across platforms either.
- checkSelf() enforces that methods are called on a blessed Data::UUID
  reference, matching the XS typemap behaviour that segv.t relies on.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Copies basic.t, from-name-collisions.t, leaky_dollar_bang.t and segv.t
from the CPAN Data-UUID-1.227 distribution into
src/test/resources/module/Data-UUID/t/ so they run as part of
'make test-bundled-modules'. All 4 tests pass against the new Java
implementation.

Skipped upstream tests: pod.t and pod-coverage.t (require
AUTHOR_TESTING) and threads.t (PerlOnJava has no ithreads).

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@fglock fglock merged commit 55135d9 into master Apr 20, 2026
2 checks passed
@fglock fglock deleted the feature/data-uuid-java-impl branch April 20, 2026 12:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant