Package ch.njol.yggdrasil

Class Yggdrasil

java.lang.Object

ch.njol.yggdrasil.Yggdrasil

@NotThreadSafe
public final class Yggdrasil
extends Object

Yggdrasil is a simple data format to store object graphs.

Yggdrasil uses String IDs to identify classes, thus all classes to be (de)serialized have to be registered to Yggdrasil before doing anything (they can also be registered while Yggdrasil is working, but you must make sure that all classes are registered in time when deserializing). A ClassResolver or YggdrasilSerializer can also be used to find classes and IDs dynamically.

Default behaviour

A Java object can be serialized and deserialized if it is a primitive, a primitive wrapper, a String, an enum or PseudoEnum (both require an ID), or its class meets all the following requirements:

• It implements YggdrasilSerializable
• It has an ID assigned to it (using the methods described above)
• It provides a nullary constructor (any access modifier) (in particular anonymous and non-static inner classes can't be serialized)
• All its non-transient and non-static fields are serializable according to these requirements

Yggdrasil will generate errors if an object loaded either has too many fields and/or is missing some in the stream.

Customisation

Any object that does not meet the above requirements for serialisation can still be (de)serialized using an YggdrasilSerializer (useful for objects of an external API), or by implementing YggdrasilSerializable.YggdrasilExtendedSerializable.

The behaviour in case of an invalid or outdated stream can be defined likewise, or one can implement YggdrasilSerializable.YggdrasilRobustSerializable or YggdrasilSerializable.YggdrasilRobustEnum respectively.

Field Summary

Fields

Modifier and Type	Field	Description
static final short	LATEST_VERSION	latest protocol version
static final int	MAGIC_NUMBER	Magic Number: "Ygg\0" (('Y' invalid input: '<'invalid input: '<' 24) + ('g' invalid input: '<'invalid input: '<' 16) + ('g' invalid input: '<'invalid input: '<' 8) + '\0')
final short	version

Constructor Summary

Constructors

Constructor	Description
Yggdrasil()
Yggdrasil(short version)

Method Summary

Modifier and Type	Method	Description
void	excessiveField(Object object, Fields.FieldContext field)
Class<?>	getClass(String id)
static <T extends Enum<T>> Enum<T>	getEnumConstant(Class<T> type, String id)
String	getID(Class<?> type)
static String	getID(Enum<?> e)
static String	getID(Field field)	Gets the ID of a field.
void	incompatibleField(Object object, Field field, Fields.FieldContext context)
boolean	isSerializable(Class<?> type)
<T> T	loadFromFile(File file, Class<T> expectedType)
void	missingField(Object object, Field field)
YggdrasilInputStream	newInputStream(InputStream in)
YggdrasilOutputStream	newOutputStream(OutputStream out)
void	registerClassResolver(ClassResolver resolver)
void	registerFieldHandler(FieldHandler handler)
void	registerSingleClass(Class<?> type)	Registers a class and uses its YggdrasilID as id.
void	registerSingleClass(Class<?> type, String id)
void	saveToFile(Object object, File file)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MAGIC_NUMBER

public static final int MAGIC_NUMBER

Magic Number: "Ygg\0" (('Y' invalid input: '<'invalid input: '<' 24) + ('g' invalid input: '<'invalid input: '<' 16) + ('g' invalid input: '<'invalid input: '<' 8) + '\0')

hex: 0x59676700

See Also:

• Constant Field Values

LATEST_VERSION

public static final short LATEST_VERSION

latest protocol version

See Also:

• Constant Field Values

version

public final short version

Constructor Details

Yggdrasil

public Yggdrasil()

Yggdrasil

public Yggdrasil(short version)

Method Details

newOutputStream

public YggdrasilOutputStream newOutputStream(OutputStream out)
                                      throws IOException

Throws:

IOException

newInputStream

public YggdrasilInputStream newInputStream(InputStream in)
                                    throws IOException

Throws:

IOException

registerClassResolver

public void registerClassResolver(ClassResolver resolver)

registerSingleClass

public void registerSingleClass(Class<?> type,
 String id)

registerSingleClass

public void registerSingleClass(Class<?> type)

Registers a class and uses its YggdrasilID as id.

registerFieldHandler

public void registerFieldHandler(FieldHandler handler)

isSerializable

public boolean isSerializable(Class<?> type)

getClass

public Class<?> getClass(String id)
                  throws StreamCorruptedException

Throws:

StreamCorruptedException

getID

public String getID(Class<?> type)
             throws NotSerializableException

Throws:

NotSerializableException

getID

public static String getID(Field field)

Gets the ID of a field.

This method performs no checks on the given field.

Returns:

The field's id as given by its YggdrasilID annotation, or its name if it's not annotated.

getID

public static String getID(Enum<?> e)

getEnumConstant

public static <T extends Enum<T>> Enum<T> getEnumConstant(Class<T> type,
 String id)
                                                   throws StreamCorruptedException

Throws:

StreamCorruptedException

excessiveField

public void excessiveField(Object object,
 Fields.FieldContext field)
                    throws StreamCorruptedException

Throws:

StreamCorruptedException

missingField

public void missingField(Object object,
 Field field)
                  throws StreamCorruptedException

Throws:

StreamCorruptedException

incompatibleField

public void incompatibleField(Object object,
 Field field,
 Fields.FieldContext context)
                       throws StreamCorruptedException

Throws:

StreamCorruptedException

saveToFile

public void saveToFile(Object object,
 File file)
                throws IOException

Throws:

IOException

loadFromFile

@Nullable
public <T> T loadFromFile(File file,
 Class<T> expectedType)
                   throws IOException

Throws:

IOException