{"id":4583,"library":"javaobj-py3","title":"javaobj-py3","description":"javaobj-py3 is a Python library designed for serializing and de-serializing Java objects, facilitating interoperability between Python and Java applications. It is currently at version 0.4.4 and receives irregular but active updates, with the latest significant features and fixes released recently.","status":"active","version":"0.4.4","language":"python","source_language":"en","source_url":"https://github.com/tcalmant/python-javaobj","tags":["java","serialization","deserialization","interoperability"],"install":[{"cmd":"pip install javaobj-py3","lang":"bash","label":"Default install"}],"dependencies":[{"reason":"Optional dependency for loading numeric arrays as NumPy arrays. It is loaded lazily only when explicitly requested.","package":"numpy","optional":true}],"imports":[{"symbol":"loads","correct":"from javaobj import loads"},{"note":"Only available with the default 'v1' parser; the 'v2' parser does not support serialization.","symbol":"dumps","correct":"from javaobj import dumps"},{"note":"Represents a deserialized custom Java object or can be used to construct objects for serialization.","symbol":"JavaObject","correct":"from javaobj import JavaObject"},{"note":"The more robust 'v2' deserializer, recommended for complex Java streams, but it cannot serialize.","symbol":"v2_loads","correct":"from javaobj.v2 import loads as v2_loads"}],"quickstart":{"code":"import javaobj\n\n# 1. Deserializing a simple Java String\n# Bytes represent a serialized Java String \"Hello, World!\"\njava_serialized_string = b'\\xac\\xed\\x00\\x05t\\x00\\x0cHello, World!'\npython_string = javaobj.loads(java_serialized_string)\nprint(f\"Deserialized Java String: '{python_string}' (Python type: {type(python_string)})\")\n\n# 2. Deserializing a Java object that maps to a Python list\n# Bytes for a serialized Java ArrayList containing \"One\" and \"Two\"\njava_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'\npython_list = javaobj.loads(java_list_bytes)\nprint(f\"Deserialized Java List: {python_list} (Python type: {type(python_list)})\")\n\n# 3. Basic Serialization (available via the default v1 implementation)\n# Serializing a Python string back into Java format\nserialized_bytes = javaobj.dumps(\"Python data\")\nprint(f\"Serialized 'Python data' (first 20 bytes): {serialized_bytes[:20]}...\")\n\n# 4. Deserializing using the v2 parser for potentially better compatibility\n# (Note: For this simple string, output will be identical)\nfrom javaobj.v2 import loads as v2_loads\npython_string_v2 = v2_loads(java_serialized_string)\nprint(f\"Deserialized (v2) Java String: '{python_string_v2}' (Python type: {type(python_string_v2)})\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"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.","message":"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)`).","severity":"gotcha","affected_versions":">=0.2.3"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=0.4.3"},{"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.","message":"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`).","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.4.4':32 'activ':37 'applic':26 'current':29 'de':16 'de-seri':15 'deseri':50 'design':11 'facilit':20 'featur':43 'fix':45 'interoper':21,51 'irregular':35 'java':18,25,48 'javaobj':2,5 'javaobj-py3':1,4 'latest':41 'librari':10 'object':19 'py3':3,6 'python':9,23 'receiv':34 'recent':47 'releas':46 'serial':13,17,49 'signific':42 'updat':38 'version':31","created_at":"2026-04-12T13:58:51.533233+00:00","updated_at":"2026-04-16T15:50:51.757987+00:00","problems":[{"fix":"Ensure the input bytes object or file stream contains correctly serialized Java objects. Verify the source of the data and its serialization method.","cause":"The input byte stream does not start with the magic number and version (AC ED 00 05) that identifies a standard Java serialized object stream, indicating the data is not a valid Java serialized object.","error":"IOError: The stream is not java serialized object. Invalid stream header: ACED0573"},{"fix":"Provide a complete and uncorrupted Java serialized byte stream. Check if the entire serialized object data was read from the source (e.g., file, network stream).","cause":"The input byte stream ended prematurely before a complete Java object could be deserialized, often indicating truncated or corrupted serialized data.","error":"RuntimeError: Stream has been ended unexpectedly while unmarshaling."},{"fix":"If using an older version, try deserializing with `javaobj.v2` (e.g., `import javaobj.v2 as javaobj`) as it's based on `jdeserialize` and supports more cases. Otherwise, simplify the Java objects being serialized or investigate the exact Java serialization format being used.","cause":"The javaobj-py3 parser encountered an unrecognized opcode (byte sequence) in the Java serialized stream, suggesting a malformed stream, a version of Java serialization not fully supported, or unsupported complex Java objects.","error":"RuntimeError: Unknown OpCode in the stream: 0x... (at offset 0x...)"},{"fix":"Inspect the deserialized `JavaObject` structure (e.g., `print(pobj.__dict__)` or `dir(pobj)`) to see the available attributes. Ensure the attribute name matches the expected Java field name. For complex Java objects, custom object transformers might be needed to map Java fields to Python attributes correctly.","cause":"After deserializing a Java object, you are trying to access an attribute (field) that either does not exist in the original Java class or `javaobj-py3` could not properly map to a Python attribute.","error":"AttributeError: 'JavaObject' object has no attribute 'someAttribute'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.6.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/tcalmant/python-javaobj","docs":null,"changelog":null,"pypi":"https://pypi.org/project/javaobj-py3/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}