serial-builder
Library for creating Java serialization data;
mainly intended for research purposes. It is not recommended to use it in production as alternative for ObjectOutputStream.
Compared to using Java's ObjectOutputStream this library has the following advantages:
- It is not necessary to have the target classes on the classpath; it is possible to refer to classes only by their name.
- It is possible to write arbitrary field values without having to access the internals of the target class with reflection.
- It is possible to omit data or add additional serialization data which would normally not be written.
The entrypoints of this library are the classes SerialBuilder
and SimpleSerialBuilder.
The API structure of SerialBuilder is pretty close to the actual serialization data format. This allows low level
creation of serialization data, at the cost of verbose usage and reduced error checking. SimpleSerialBuilder operates
on a higher level, which makes its usage more concise and less error-prone. In most cases the API offered by
SimpleSerialBuilder should suffice.
The API offered by this library uses a 'fluent builder style', where all methods calls are chained after each other
(with indentation to increase readability) until the end of the chain is reached, and the resulting serialization
data in the form of byte[] is returned. Using the API in any other way is not supported and might cause exceptions.
It is recommended to follow the IDE code completion suggestions while using the API, looking at the builder API
interfaces is most likely not that helpful.
Usage
Requires Java 17 or newer
Currently this library is not published to Maven Central. You can either build the project locally or you can use JitPack as Maven repository serving this library.
When using JitPack it is recommended to put the jitpack.io repository last in the list of declared repositories for better performance and to avoid pulling undesired dependencies from it. When using Gradle as build tool you should also use repository content filtering:
repositories {
mavenCentral()
exclusiveContent {
forRepository {
maven {
url = uri("https://jitpack.io")
}
}
filter {
// Only use JitPack for the `serial-builder` library
includeModule("com.github.Marcono1234.serial-builder", "serial-builder")
}
}
}API usage examples (SimpleSerialBuilder)
Note: This project also supports generating Java code using this API to recreate existing serialization data, see the code generation section below.
Class hierarchy
Let's assume you have these two classes:
class ClassA implements Serializable {
@Serial
private static final long serialVersionUID = 1L;
public String a;
}
class ClassB extends ClassA {
@Serial
private static final long serialVersionUID = 1L;
public String b;
}To create serialization data for an instance of ClassB, you can use the API in the following way:
byte[] serialData = SimpleSerialBuilder.startSerializableObject()
// Start at the superclass
.beginClassData(ClassA.class)
.beginObjectField("a", String.class)
.string("value-a")
.endField()
.endClassData()
.beginClassData(ClassB.class)
.beginObjectField("b", String.class)
.string("value-b")
.endField()
.endClassData()
.endObject();writeObject method
Let's assume you have the following class with writeObject and readObject methods:
class ClassWithWriteObject implements Serializable {
@Serial
private static final long serialVersionUID = 1L;
public int i;
public String s;
public transient int i2;
public transient String s2;
@Serial
private void writeObject(ObjectOutputStream out) throws IOException {
out.defaultWriteObject();
out.writeInt(i2);
out.writeObject(s2);
}
@Serial
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
in.defaultReadObject();
i2 = in.readInt();
s2 = (String) in.readObject();
}
}To create serialization data for it, you can use the API in the following way:
byte[] serialData = SimpleSerialBuilder.startSerializableObject()
.beginClassData(ClassWithWriteObject.class)
// Represents the data written by the `defaultWriteObject()` call
.primitiveIntField("i", 1)
.beginObjectField("s", String.class)
.string("test")
.endField()
// Represents the data manually written by `writeObject`
.writeObjectWith(writer -> {
writer.writeInt(2);
writer.string("manually-written");
})
.endClassData()
.endObject();Proxy instances
Let's assume you have the following java.lang.reflect.InvocationHandler implementation:
class CustomInvocationHandler implements InvocationHandler, Serializable {
@Serial
private static final long serialVersionUID = 1L;
public String result;
@Override
public Object invoke(Object proxy, Method method, Object[] args) {
return result;
}
}To create serialization data for a java.lang.reflect.Proxy instance which uses an instance of that invocation handler, you can use the
API in the following way:
// Starts a Proxy object which implements the Callable interface
byte[] serialData = SimpleSerialBuilder.startProxyObject(Callable.class)
.beginSerializableInvocationHandler()
.beginClassData(CustomInvocationHandler.class)
.beginObjectField("result", String.class)
.string("custom-result")
.endField()
.endClassData()
.endObject()
.endProxyObject();Handles
The serialization protocol supports handles which refer to a previously written instance. This API supports this
feature through the Handle class.
First you create a new (unassigned) Handle, then you pass it to one of the builder methods with Handle parameter
and afterwards you can use it to refer to the previously written object.
This library does not support using Handle in all cases where the serialization protocol supports it, but all
interesting cases should be covered (if you are missing support for a use case, feel free to create a GitHub issue).
Let's assume you have the following class:
class Container implements Serializable {
@Serial
private static final long serialVersionUID = 1L;
public Serializable element;
}To create serialization data for an instance of this class which contains itself, you can use the API in the following way:
// First create a new unassigned handle
Handle selfHandle = new Handle();
// Then pass the handle here as argument to assign the written object to it
byte[] serialData = SimpleSerialBuilder.startSerializableObject(selfHandle)
.beginClassData(Container.class)
.beginObjectField("element", Serializable.class)
// Finally, write a reference to the previously written object
.objectHandle(selfHandle)
.endField()
.endClassData()
.endObject();Code generation
Especially when using this API for existing large serialization data, it can be cumbersome to manually write all the Java code to recreate the serialization data. Therefore, this project provides code generation functionality which, for given serialization data, generates the corresponding API calls to recreate the serialization data (as close as possible). See the README of the subproject for more information.
Project structure
This project is a multi-project Gradle build. It has the following subprojects:
serial-builder: Contains the source code of the builder APIserial-builder-codegen: Contains the source code for code generation
Building
This project uses Gradle for building; just run:
./gradlew build
It is built against Java 17, but there is no need to manually install the correct JDK; Gradle's toolchain feature automatically downloads the needed JDK. Some IDEs do not support toolchains yet, so you might have to configure them manually.
Similar / related projects
License
This project uses the MIT license; all contributions are implicitly under that license.