XDI4j Tutorial 1

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

This tutorial explains how to create and manipulate a simple XDI graph.

Interfaces and classes

This section briefly describes the core Java interfaces that represent various parts of an XDI graph.

Graph

org.eclipse.higgins.xdi4j.Graph;

This interface represents an XDI graph. XDI graphs consist of subjects, predicates, literals, references and inner graphs. Operations on the graph include creating these graph components, finding and manipulating them

Subject

org.eclipse.higgins.xdi4j.Subject;

This interface represents a subject in an XDI graph. Methods include creating and finding predicates of the subject.

Predicate

 org.eclipse.higgins.xdi4j.Predicate;

This interface represents a predicate in an XDI graph. Methods include creating and finding references, literals and inner graphs of the predicate.

Reference

org.eclipse.higgins.xdi4j.Reference;

This interface represents a reference in an XDI graph.

Literal

org.eclipse.higgins.xdi4j.Literal;

This interface represents a literal in an XDI graph.

Statement

org.eclipse.higgins.xdi4j.Statement;

This interface represents a statement in an XDI graph.

A statement consists of either:

• A subject (if the subject has no predicates).
• A subject and a predicate (if the predicate has no references or literals).
• A subject and a predicate and a reference.
• A subject and a predicate and a literal.
• A subject and a predicate and an inner graph.

GraphFactory

org.eclipse.higgins.xdi4j.GraphFactory;

Graph factories can create new XDI graphs and load existing ones. Different graph factories use different backing stores (e.g. In-Memory, XML file, Hibernate). Some graph factories have configuration properties that should be set before creating an XDI graph.

Constructing an XDI graph

We will write a simple Java program that creates the following XDI graph using the MemoryGraphFactory:

=markus
	+name
		"Markus"
	+friend
		=giovanni
		=drummond
=giovanni
	+friend
		=drummond

Note that subjects, predicates and references have no specific order, i.e. when the graph is serialized and printed, the subject =giovanni could just as well come before =markus.

There are several ways of working with an XDI graph. For example, we could create the XDI subject =markus, then the XDI predicate +name, and then the XDI literal "Markus". Or, we could create an entire XDI statement with all three parts in a single step. The result is the same.

Example Code:

package org.eclipse.higgins.xdi4j.tutorial;

import org.eclipse.higgins.xdi4j.Graph;
import org.eclipse.higgins.xdi4j.GraphFactory;
import org.eclipse.higgins.xdi4j.Predicate;
import org.eclipse.higgins.xdi4j.Subject;
import org.eclipse.higgins.xdi4j.impl.memory.MemoryGraphFactory;
import org.eclipse.higgins.xdi4j.xri3.impl.XRI3Segment;

/**
 * This example app shows how to create a new XDI
 * document and how to perform basic graph operations on it.
 */
public class Tutorial1 {

	public static void main(String[] args) throws Exception {

		GraphFactory factory = MemoryGraphFactory.getInstance();
		Graph graph = factory.openGraph();

		// there are basically two ways of working with graphs

		// 1) work with subjects, predicates, references and literals

		Subject markus = graph.createSubject(new XRI3Segment("=alice"));

		Predicate name = markus.createPredicate(new XRI3Segment("+name"));
		Predicate friend = markus.createPredicate(new XRI3Segment("+friend"));

		name.createLiteral("Alice X.");
		friend.createReference(new XRI3Segment("=bob"));

		// 2) work with statements

		graph.createStatement(new XRI3Segment("=alice"), new XRI3Segment("+friend"), new XRI3Segment("=charlie"));
		graph.createStatement(new XRI3Segment("=charlie"), new XRI3Segment("+friend"), new XRI3Segment("=bob"));

		// after our graph is filled, we can output it

		System.out.println(graph.toString());

		// and we can navigate and read from it

		String aliceName = graph.getSubject(new XRI3Segment("=alice")).getPredicate(new XRI3Segment("+name")).getLiteral().getData();

		System.out.println("=alice's name: " + aliceName);

		// don't forget to close the graph

		graph.close();
	}
}