net.fortytwo.sesametools
Class RdfListUtil

java.lang.Object
  net.fortytwo.sesametools.RdfListUtil

public class RdfListUtil
extends Object

A utility for translating RDF lists to and from native Java lists.

Author:

Peter Ansell p_ansell@yahoo.com

Field Summary

static boolean	DEFAULT_CHECK_CYCLES The default value for checkCycles if no other value is given.
static boolean	DEFAULT_CHECK_INCOMPLETE The default value for checkIncomplete if no other value is given.
static boolean	DEFAULT_USE_ITERATIVE_ON_ERROR The default value for useIterativeOnError if no other value is given.

Constructor Summary

RdfListUtil()
Constructs an instance of the RDF List Processing Utility using the default error checking and redundancy values.

RdfListUtil(boolean checkCycles, boolean checkIncomplete, boolean useIterativeOnError)
Constructs an instance of the RDF List Processing Utility using the given values to define operational checking and redundancy parameters.

Method Summary

void	addList(org.openrdf.model.Resource head, List<org.openrdf.model.Value> nextValues, org.openrdf.model.Graph graphToAddTo, org.openrdf.model.Resource... contexts) Adds an RDF List with the given elements to a graph.
void	addListAtNode(org.openrdf.model.Resource subject, org.openrdf.model.URI predicate, List<org.openrdf.model.Value> nextValues, org.openrdf.model.Graph graphToAddTo, org.openrdf.model.Resource... contexts) Return the contents of the list serialized as an RDF list
boolean	getCheckCycles()
boolean	getCheckIncomplete()
List<org.openrdf.model.Value>	getList(org.openrdf.model.Resource head, org.openrdf.model.Graph graphToSearch, org.openrdf.model.Resource... contexts) Fetches a simple (non-branching) list from a graph.
List<org.openrdf.model.Value>	getListAtNode(org.openrdf.model.Resource subject, org.openrdf.model.URI predicate, org.openrdf.model.Graph graphToSearch, org.openrdf.model.Resource... contexts) Fetches a single headed list from the graph based on the given subject and predicate Note: We silently fail if no list is detected at all and return null In addition, only the first triple matching the subject-predicate combination is used to detect the head of the list.
Collection<List<org.openrdf.model.Value>>	getLists(Set<org.openrdf.model.Resource> heads, org.openrdf.model.Graph graphToSearch, org.openrdf.model.Resource... contexts)
Collection<List<org.openrdf.model.Value>>	getListsAtNode(org.openrdf.model.Resource subject, org.openrdf.model.URI predicate, org.openrdf.model.Graph graphToSearch, org.openrdf.model.Resource... contexts) Fetches a collection of generalized lists based on the given subject and predicate, where lists are allowed to branch from head to tail.
Collection<List<org.openrdf.model.Value>>	getListsIterative(Set<org.openrdf.model.Resource> heads, org.openrdf.model.Graph graphToSearch, org.openrdf.model.Resource... contexts) Fetches a collection of generalized lists, where lists are allowed to branch from head to tail.
Collection<List<org.openrdf.model.Value>>	getListsRecursive(org.openrdf.model.Resource head, org.openrdf.model.Graph graph, org.openrdf.model.Resource... contexts)
boolean	getUseIterativeOnError()

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CHECK_CYCLES

public static final boolean DEFAULT_CHECK_CYCLES

The default value for checkCycles if no other value is given.

See Also:

Constant Field Values

DEFAULT_CHECK_INCOMPLETE

public static final boolean DEFAULT_CHECK_INCOMPLETE

The default value for checkIncomplete if no other value is given.

See Also:

Constant Field Values

DEFAULT_USE_ITERATIVE_ON_ERROR

public static final boolean DEFAULT_USE_ITERATIVE_ON_ERROR

The default value for useIterativeOnError if no other value is given.

See Also:

Constant Field Values

Constructor Detail

RdfListUtil

public RdfListUtil()

Constructs an instance of the RDF List Processing Utility using the default error checking and redundancy values.

RdfListUtil

public RdfListUtil(boolean checkCycles,
                   boolean checkIncomplete,
                   boolean useIterativeOnError)

Constructs an instance of the RDF List Processing Utility using the given values to define operational checking and redundancy parameters.

Parameters:

checkCycles - Defines whether to check for cycles in lists.

checkIncomplete - Defines whether to check for properly ended lists.

useIterativeOnError - Defines whether to use iterative approach when recursive approach fails with out of memory or stack overflow.

Method Detail

addList

public void addList(org.openrdf.model.Resource head,
                    List<org.openrdf.model.Value> nextValues,
                    org.openrdf.model.Graph graphToAddTo,
                    org.openrdf.model.Resource... contexts)

Adds an RDF List with the given elements to a graph.

Parameters:

head - the head resource of the list

nextValues - the list to add. If this list is empty, no statements will be written

graphToAddTo - the Graph to add the resulting list to

contexts - the graph contexts into which to add the new statements. If no contexts are given, statements will be added to the default (null) context.

addListAtNode

public void addListAtNode(org.openrdf.model.Resource subject,
                          org.openrdf.model.URI predicate,
                          List<org.openrdf.model.Value> nextValues,
                          org.openrdf.model.Graph graphToAddTo,
                          org.openrdf.model.Resource... contexts)

Return the contents of the list serialized as an RDF list

Parameters:

subject - the subject of a new statement pointing to the head of the list

predicate - the predicate of a new statement pointing to the head of the list

nextValues - the list to add. If this list is empty, only the pointer statement will be written.

graphToAddTo - the Graph to add the resulting list to

contexts - the graph contexts into which to add the new statements. If no contexts are given, statements will be added to the default (null) context.

getList

public List<org.openrdf.model.Value> getList(org.openrdf.model.Resource head,
                                             org.openrdf.model.Graph graphToSearch,
                                             org.openrdf.model.Resource... contexts)

Fetches a simple (non-branching) list from a graph.

Parameters:

head - the head of the list

graphToSearch - the graph from which the list is to be fetched

contexts - the graph contexts from which the list is to be fetched

Returns:

the contents of the list

getListAtNode

public List<org.openrdf.model.Value> getListAtNode(org.openrdf.model.Resource subject,
                                                   org.openrdf.model.URI predicate,
                                                   org.openrdf.model.Graph graphToSearch,
                                                   org.openrdf.model.Resource... contexts)

Fetches a single headed list from the graph based on the given subject and predicate

Note: We silently fail if no list is detected at all and return null

In addition, only the first triple matching the subject-predicate combination is used to detect the head of the list.

Parameters:

subject - the subject of a statement pointing to the list

predicate - the predicate of a statement pointing to the list

graphToSearch - the graph from which the list is to be fetched

contexts - the graph contexts from which the list is to be fetched

Returns:

the contents of the list

Throws:

RuntimeException - if the list structure was not complete, or it had cycles

getListsIterative

public Collection<List<org.openrdf.model.Value>> getListsIterative(Set<org.openrdf.model.Resource> heads,
                                                                   org.openrdf.model.Graph graphToSearch,
                                                                   org.openrdf.model.Resource... contexts)

Fetches a collection of generalized lists, where lists are allowed to branch from head to tail.

Parameters:

heads - the heads of the lists to fetch

graphToSearch - the graph from which the list is to be fetched

contexts - the graph contexts from which the list is to be fetched

Returns:

all matching lists. If no matching lists are found, an empty collection is returned.

getLists

public Collection<List<org.openrdf.model.Value>> getLists(Set<org.openrdf.model.Resource> heads,
                                                          org.openrdf.model.Graph graphToSearch,
                                                          org.openrdf.model.Resource... contexts)

getListsRecursive

public Collection<List<org.openrdf.model.Value>> getListsRecursive(org.openrdf.model.Resource head,
                                                                   org.openrdf.model.Graph graph,
                                                                   org.openrdf.model.Resource... contexts)

getListsAtNode

public Collection<List<org.openrdf.model.Value>> getListsAtNode(org.openrdf.model.Resource subject,
                                                                org.openrdf.model.URI predicate,
                                                                org.openrdf.model.Graph graphToSearch,
                                                                org.openrdf.model.Resource... contexts)

Fetches a collection of generalized lists based on the given subject and predicate, where lists are allowed to branch from head to tail.

Parameters:

subject - the subject of a statement pointing to the list

predicate - the predicate of a statement pointing to the list

graphToSearch - the graph from which the list is to be fetched

contexts - the graph contexts from which the list is to be fetched

Returns:

all matching lists. If no matching lists are found, an empty collection is returned.

getCheckCycles

public boolean getCheckCycles()

Returns:

True if this utility is setup to check for cycles and throw exceptions if it finds cycles in lists.

getCheckIncomplete

public boolean getCheckIncomplete()

Returns:

True if this utility is setup to check for incomplete, unterminated lists, and throw exceptions if it finds any.

getUseIterativeOnError

public boolean getUseIterativeOnError()

Returns:

True if this utility is setup to use a slower iterative approach then a recursive approach fails.