How to (de )serialize XDI graphs

Given an implementation of the Graph interface, the xdi2-core component provides classes to (de-)serialize that graph, i.e. to read/write it from/to a string, file, stream, etc. This is done using one of the supported serialization formats, such as XDI/JSON or XDI DISPLAY. Note that these serialization formats are loss-less, i.e. no matter which format is used, the XDI graph remains the same.

Interfaces and Classes

• xdi2.core.io.XDIReader: XDI reader interface for de-serializing a graph
• xdi2.core.io.XDIWriter: XDI writer interface for serializing a graph
• xdi2.core.io.XDIReaderRegistry: XDI reader registry for getting a suitable XDIReader
• xdi2.core.io.XDIWriterRegistry: XDI writer registry for getting a suitable XDIWriter

Example

To de-serialize a graph (i.e. read a graph from a string, file, stream, etc.), an instance of the XDIReader interface is needed. An XDIReader can be obtained in a number of ways using the XDIReaderRegistry:

Graph graph = MemoryGraphFactory.getInstance().openGraph();
XDIReader reader = XDIReaderRegistry.forFormat("XDI/JSON", null);
reader.read(graph, new FileReader(new File("myxdigraph.json")));

There is also an implementation of XDIReader that attempts to detect the serialization format automatically:

XDIReader autoReader = XDIReaderRegistry.getAuto();

To serialize a graph (i.e. write a graph to a string, file, stream, etc.), an instance of the XDIWriter interface is needed. An XDIWriter can be obtained in a number of ways using the XDIWriterRegistry:

Graph graph = ...;
XDIWriter writer = XDIWriterRegistry.forFormat("XDI DISPLAY", null);
writer.write(graph, System.out);

There are also a number of "shortcuts" throughout the XDI2 library that use XDIReader and XDIWriter functionality.

For example, the toString() methods on the Graph interface:

Graph graph = ...;
System.out.println(graph.toString());	// prints the graph in the default serialization format
System.out.println(graph.toString("XDI DISPLAY", null)); prints the graph in the XDI DISPLAY serialization format

Or the parseGraph() methods on the GraphFactory interface:

String graphString = ...;
GraphFactory graphFactory = MemoryGraphFactory.getInstance();
Graph graph = graphFactory.parseGraph(graphString, "XDI/JSON", null);	// opens and parses a serialized graph

Parameters

Both XDIReader and XDIWriter implementations may take parameters to control their functionality. For example, this includes whether implied context statements are serialized or not, or whether pretty-printing should be enabled.

The following parameters are available for XDIReader implementations:

• (currently none)

The following parameters are available for XDIWriter implementations (not all implementations support all parameters):

• "implied": Set to 1 to enable serialization of implied statements
• "ordered": Set to 1 to enable ordering of statements
• "pretty": Set to 1 to enable pretty-printing (i.e. additional whitespace)
• "html": Set to 1 to enable HTML markup

For example, to serialize a graph with implied context statements and pretty-printing turned on:

Graph graph = ...;
Properties parameters = new Properties();
parameters.setProperty(XDIWriterRegistry.PARAMETER_IMPLIED, "1");
parameters.setProperty(XDIWriterRegistry.PARAMETER_PRETTY, "1");
XDIWriter writer = XDIWriterRegistry.forFormat("XDI/JSON", parameters);
writer.write(graph, System.out);

See also

• https://wiki.oasis-open.org/xdi/SerializationFormats on the OASIS XDI TC wiki
• https://wiki.oasis-open.org/xdi/XdiDisplayFormat on the OASIS XDI TC wiki
• https://wiki.oasis-open.org/xdi/JSONSerializationRules on the OASIS XDI TC wiki
• https://wiki.oasis-open.org/xdi/SerializationStatementOrder on the OASIS XDI TC wiki