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)serialised 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 deserialising). A ClassResolver or YggdrasilSerializer can also be used to find classes and IDs dynamically.

Default behaviour

A Java object can be serialised and deserialised if it is a primitive, a primitive wrapper, a String, an enum or PseudoEnum (both require an ID), or its class meets all of 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 serialised)
• All its non-transient and non-static fields are serialisable 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)serialised 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 short	LATEST_VERSION	latest protocol version
static int	MAGIC_NUMBER	Magic Number: "Ygg\0"
short	version

Constructor Summary

Constructors

Constructor	Description
Yggdrasil()
Yggdrasil(short version)

Method Summary

Modifier and Type	Method	Description
void	excessiveField(Object o, Fields.FieldContext field)
Class<?>	getClass(String id)
static <T extends Enum<T>> Enum<T>	getEnumConstant(Class<T> c, String id)
String	getID(Class<?> c)
static String	getID(Enum<?> e)
static String	getID(Field f)	Gets the ID of a field.
void	incompatibleField(Object o, Field f, Fields.FieldContext field)
boolean	isSerializable(Class<?> c)
<T> @Nullable T	loadFromFile(File f, Class<T> expectedType)
static void	main(String[] args)
void	missingField(Object o, Field f)
YggdrasilInputStream	newInputStream(InputStream in)
YggdrasilOutputStream	newOutputStream(OutputStream out)
YggdrasilInputStream	newXMLInputStream(InputStream in)	Deprecated.
YggXMLOutputStream	newXMLOutputStream(OutputStream out)	Deprecated.
void	registerClassResolver(ClassResolver r)
void	registerFieldHandler(FieldHandler h)
void	registerSingleClass(Class<?> c)	Registers a class and uses its YggdrasilID as id.
void	registerSingleClass(Class<?> c, String id)
void	saveToFile(Object o, File f)

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"

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

newXMLOutputStream

@Deprecated
public YggXMLOutputStream newXMLOutputStream(OutputStream out)
                                      throws IOException

Deprecated.

Throws:

IOException

newXMLInputStream

@Deprecated
public YggdrasilInputStream newXMLInputStream(InputStream in)
                                       throws IOException

Deprecated.

Throws:

IOException

registerClassResolver

public void registerClassResolver(ClassResolver r)

registerSingleClass

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

registerSingleClass

public void registerSingleClass(Class<?> c)

Registers a class and uses its YggdrasilID as id.

registerFieldHandler

public void registerFieldHandler(FieldHandler h)

isSerializable

public final boolean isSerializable(Class<?> c)

getClass

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

Throws:

StreamCorruptedException

getID

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

Throws:

NotSerializableException

getID

public static String getID(Field f)

Gets the ID of a field.

This method performs no checks on the given field.

Parameters:

f -

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> c,
 String id)
                                                   throws StreamCorruptedException

Throws:

StreamCorruptedException

excessiveField

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

Throws:

StreamCorruptedException

missingField

public void missingField(Object o,
 Field f)
                  throws StreamCorruptedException

Throws:

StreamCorruptedException

incompatibleField

public void incompatibleField(Object o,
 Field f,
 Fields.FieldContext field)
                       throws StreamCorruptedException

Throws:

StreamCorruptedException

saveToFile

public void saveToFile(Object o,
 File f)
                throws IOException

Throws:

IOException

loadFromFile

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

Throws:

IOException

main

public static void main(String[] args)