javaobj-py3

Warnings

• breaking Version 0.4.0 introduced a new 'v2' parser (`javaobj.v2`) which is more capable for deserialization but *does not support serialization* (`dumps`). The default `javaobj.loads` and `javaobj.dumps` still use the older 'v1' parser. Using `v2` for deserialization means you cannot serialize with it.
  Fix: Choose the appropriate parser: use `javaobj.loads` (v1) for both loading and dumping, or `javaobj.v2.loads` for more robust loading if serialization is not needed. Be explicit in your imports to avoid confusion.
• gotcha NumPy is an optional dependency. If you intend to deserialize Java numeric arrays into NumPy arrays, ensure 'numpy' is installed (`pip install numpy`). The library loads NumPy lazily, only when `use_numpy_arrays` is explicitly requested during unmarshalling (e.g., `javaobj.loads(bytes_data, use_numpy_arrays=True)`).
  Fix: Install 'numpy' if you need NumPy array support: `pip install numpy`. Pass `use_numpy_arrays=True` to `javaobj.loads()` or `JavaObjectUnmarshaller` if you expect NumPy arrays.
• gotcha The `javaobj.load()` function (for file-like objects) can transparently handle GZipped Java serialization streams. However, `javaobj.loads()` (for bytes in memory) expects raw bytes and will not automatically decompress GZipped input.
  Fix: If working with GZipped bytes in memory, decompress them manually before passing to `javaobj.loads()` (e.g., using `gzip.decompress`). For file paths or open file objects, prefer `javaobj.load()`.
• gotcha Primitive Java types (e.g., `java.lang.String`, `java.lang.Integer`, `java.lang.Boolean`) are deserialized into their equivalent native Python types (`str`, `int`, `bool`). Custom Java classes or complex collections (like `ArrayList`, `HashMap`) are typically mapped to `javaobj.JavaObject` instances, requiring attribute access (e.g., `obj.fieldName`).
  Fix: Be aware of the type mapping. Check `type(result)` after `loads()` and use `isinstance(result, javaobj.JavaObject)` if you expect custom Java objects to access their fields.
• gotcha While the library supports decoding CESU-8 strings (common in older Java serialization), character encoding issues can still arise with non-standard or malformed input. Ensure the Java side uses standard UTF-8 or be prepared to handle specific encoding issues.
  Fix: Verify the encoding used on the Java side. If issues persist, consider inspecting the raw bytes or implementing custom object transformers to debug encoding problems.

Install

• pip install javaobj-py3 Default install

Imports

• loads

  from javaobj import loads

• dumps

  from javaobj import dumps

  Only available with the default 'v1' parser; the 'v2' parser does not support serialization.
• JavaObject

  from javaobj import JavaObject

  Represents a deserialized custom Java object or can be used to construct objects for serialization.
• v2_loads

  from javaobj.v2 import loads as v2_loads

  The more robust 'v2' deserializer, recommended for complex Java streams, but it cannot serialize.

Quickstart

This quickstart demonstrates how to deserialize common Java types (String, List) into their Python equivalents using `javaobj.loads()`. It also shows a basic example of serializing a Python string to Java format using `javaobj.dumps()` and introduces the `v2_loads` parser for advanced deserialization.

import javaobj

# 1. Deserializing a simple Java String
# Bytes represent a serialized Java String "Hello, World!"
java_serialized_string = b'\xac\xed\x00\x05t\x00\x0cHello, World!'
python_string = javaobj.loads(java_serialized_string)
print(f"Deserialized Java String: '{python_string}' (Python type: {type(python_string)})")

# 2. Deserializing a Java object that maps to a Python list
# Bytes for a serialized Java ArrayList containing "One" and "Two"
java_list_bytes = b'\xac\xed\x00\x05sr\x00\x13java.util.ArrayListx\x81\xd2\x1d\x99\xc7\xed\x11\x00\x02\x00\x00xp\x00\x00\x00\x02w\x04\x00\x00\x00\x02t\x00\x03Onet\x00\x03Twoe\x00'
python_list = javaobj.loads(java_list_bytes)
print(f"Deserialized Java List: {python_list} (Python type: {type(python_list)})")

# 3. Basic Serialization (available via the default v1 implementation)
# Serializing a Python string back into Java format
serialized_bytes = javaobj.dumps("Python data")
print(f"Serialized 'Python data' (first 20 bytes): {serialized_bytes[:20]}...")

# 4. Deserializing using the v2 parser for potentially better compatibility
# (Note: For this simple string, output will be identical)
from javaobj.v2 import loads as v2_loads
python_string_v2 = v2_loads(java_serialized_string)
print(f"Deserialized (v2) Java String: '{python_string_v2}' (Python type: {type(python_string_v2)})")