Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.hp.hpl.jena.rdf.model
Interface RDFList

All Superinterfaces:
  FrontsNode, RDFNode, Resource

    public interface RDFList

extends Resource

Provides a convenience encapsulation for lists formed from chains of RDF statements arranged to form a head/tail cons-cell structure. The properties that form the links between cells, and from cells to values, are specified by a vocabulary interface, so this abstraction is designed to cope equally well with DAML lists, RDF lists, and user-defined lists.

A well-formed list has cells that are made up of three statements: one denoting the `rdf:type` of the list cell, one denoting the link to the value of the list at that point, and one pointing to the list tail. If a list cell is not well-formed, list operations may fail in unpredictable ways. However, to explicitly check that the list is well-formed at all times is expensive. Therefore the list operates in two modes: in strict mode, the well-formedness of the list is checked at the start of each list operation, and an `InvalidListException` is thrown if the list is not well- formed. This ensures that list operations are safe, but will slow down processing. In non-strict mode, this checking is switched off, but can be invoked explicitly by clients by calling `isValid()`. By default, RDF lists are processed in non-strict mode.

Version:
  Release ($Id: RDFList.java,v 1.13 2008/01/02 12:05:46 andy_seaborne Exp $)
Author:
  Ian Dickinson, HP Labs (email)

Nested Class Summary
`static interface` | `RDFList.ApplyFn` Interface that encapsulates a function to apply to every element in a list.
`static interface` | `RDFList.ReduceFn` Interface that encapsulates a function to apply to each element of a list in turn, and passing the result to an accumulator.

Method Summary
`void` | `add(RDFNode value)` Add the given value to the end of the list.
`RDFList` | `append(java.util.Iterator nodes)` Answer a new list that is formed by adding each element of this list to the head of the the list formed from the given `nodes`.
`RDFList` | `append(RDFList list)` Answer a new list that is formed by adding each element of this list to the head of the given `list`.
`void` | `apply(RDFList.ApplyFn fn)` Apply a function to each value in the list in turn.
`java.util.List` | `asJavaList()` Answer the contents of this RDF list as a Java list of RDFNode values.
`void` | `concatenate(java.util.Iterator nodes)` Add the nodes returned by the given iterator to the end of this list.
`void` | `concatenate(RDFList list)` Change the tail of this list to point to the given list, so that this list becomes the list of the concatenation of the elements of both lists.
`RDFList` | `cons(RDFNode value)` Return a reference to a new list cell whose head is `value` and whose tail is this list.
`boolean` | `contains(RDFNode value)` Answer true if the given node appears as the value of a value of any of the cells of this list.
`RDFList` | `copy()` Answer a list that contains all of the elements of this list in the same order, but is a duplicate copy in the underlying model.
`RDFNode` | `get(int i)` Answer the node that is the i'th element of the list, assuming that the head is item zero.
`RDFNode` | `getHead()` Answer the value that is at the head of the list.
`boolean` | `getStrict()` Answer true lists are operating in strict mode, in which the well- formedness of the list is checked at every operation.
`RDFList` | `getTail()` Answer the list that is the tail of this list.
`java.lang.String` | `getValidityErrorMessage()` Answer the error message returned by the last failed validity check, if any.
`int` | `indexOf(RDFNode value)` Answer the index of the first occurrence of the given value in the list, or -1 if the value is not in the list.
`int` | `indexOf(RDFNode value, int start)` Answer the index of the first occurrence of the given value in the list after index `start`, or -1 if the value is not in the list after the given start point.
`boolean` | `isEmpty()` Answer true if this list is the empty list.
`boolean` | `isValid()` Answer true if the list is well-formed, by checking that each node is correctly typed, and has a head and tail pointer from the correct vocabulary.
`ExtendedIterator` | `iterator()` Answer an iterator over the elements of the list.
`ExtendedIterator` | `mapWith(Map1 fn)` Answer an iterator of the elements of this list, to each of which the given map function has been applied.
`java.lang.Object` | `reduce(RDFList.ReduceFn fn, java.lang.Object initial)` Apply a function to each value in the list in turn, accumulating the results in an accumulator.
`RDFList` | `remove(RDFNode val)` Remove the given value from this list.
`void` | `removeAll()` Deprecated. Replaced by `removeList()`
`RDFList` | `removeHead()` Remove the value from the head of the list.
`void` | `removeList()` Remove all of the components of this list from the model.
`RDFNode` | `replace(int i, RDFNode value)` Replace the value at the i'th position in the list with the given value.
`boolean` | `sameListAs(RDFList list)` Answer true if this list has the same elements in the same order as the given list.
`RDFNode` | `setHead(RDFNode value)` Update the head of the list to have the given value, and return the previous value.
`void` | `setStrict(boolean strict)` Set a flag to indicate whether to strictly check the well-formedness of lists at each operation.
`RDFList` | `setTail(RDFList tail)` Update the list cell at the front of the list to have the given list as tail.
`int` | `size()` Answer the number of elements in the list.
`RDFList` | `with(RDFNode value)` Answer the list that is this list with the given value added to the end of the list.

Methods inherited from interface com.hp.hpl.jena.rdf.model.Resource
`abort, addLiteral, addLiteral, addLiteral, addLiteral, addLiteral, addLiteral, addProperty, addProperty, addProperty, addProperty, begin, commit, equals, getId, getLocalName, getModel, getNameSpace, getNode, getProperty, getRequiredProperty, getURI, hasLiteral, hasLiteral, hasLiteral, hasLiteral, hasLiteral, hasLiteral, hasProperty, hasProperty, hasProperty, hasProperty, hasURI, listProperties, listProperties, removeAll, removeProperties, toString`

Methods inherited from interface com.hp.hpl.jena.rdf.model.RDFNode
`as, canAs, inModel, isAnon, isLiteral, isResource, isURIResource, visitWith`

Methods inherited from interface com.hp.hpl.jena.graph.FrontsNode
`asNode`

Method Detail

### size

    int size()

  Answer the number of elements in the list.

  Returns:
    The size of the list as an integer

### getHead

    RDFNode getHead()

  Answer the value that is at the head of the list.

  Returns:
    The value that is associated with the head of the list.
  Throws:
    `EmptyListException` - if this list is the empty list

### setHead

    RDFNode setHead(RDFNode value)

  Update the head of the list to have the given value, and return the previous value.

  Parameters:
    `value` - The value that will become the value of the list head
  Throws:
    `EmptyListException` - if this list is the empty list

### getTail

    RDFList getTail()

  Answer the list that is the tail of this list.

  Returns:
    The tail of the list, as a list
  Throws:
    `EmptyListException` - if this list is the empty list

### setTail

    RDFList setTail(RDFList tail)

  Update the list cell at the front of the list to have the given list as tail. The old tail is returned, and remains in the model.

  Parameters:
    `tail` - The new tail for this list.
  Returns:
    The old tail.

### isEmpty

    boolean isEmpty()

  Answer true if this list is the empty list.

  Returns:
    True if this is the empty (nil) list, otherwise false.

### cons

    RDFList cons(RDFNode value)

  Return a reference to a new list cell whose head is `value` and whose tail is this list.

  Parameters:
    `value` - A new value to add to the head of the list
  Returns:
    The new list, whose head is `value`

### add

    void add(RDFNode value)

  Add the given value to the end of the list. This is a side-effecting operation on the underlying model that is only defined if this is not the empty list. If this list is the empty (nil) list, we cannot perform a side-effecting update without changing the URI of this node (from `rdf:nil`with(com.hp.hpl.jena.rdf.model.RDFNode)` and `cons(com.hp.hpl.jena.rdf.model.RDFNode)`.`

  Parameters:
    `value` - A value to add to the end of the list
  Throws:
    `EmptyListUpdateException` - if an attempt is made to `add` to the empty list.

### with

    RDFList with(RDFNode value)

  Answer the list that is this list with the given value added to the end of the list. This operation differs from `add(com.hp.hpl.jena.rdf.model.RDFNode)` in that it will always work, even on an empty list, but the return value is the updated list. Specifically, in the case of adding a value to the empty list, the returned list will not be the same as this list. Client code should not assume that this is an in-place update, but should ensure that the resulting list is asserted back into the graph into the appropriate relationships.

  Parameters:
    `value` - A value to add to the end of the list
  Returns:
    The list that results from adding a value to the end of this list

### get

    RDFNode get(int i)

  Answer the node that is the i'th element of the list, assuming that the head is item zero. If the list is too short to have an i'th element, throws a `ListIndexException`.

  Parameters:
    `i` - The index into the list, from 0
  Returns:
    The list value at index i, or null
  Throws:
    `ListIndexException` - if the list has fewer than (i + 1) elements.

### replace

    RDFNode replace(int i,
                    RDFNode value)

  Replace the value at the i'th position in the list with the given value. If the list is too short to have an i'th element, throws a `ListIndexException`.

  Parameters:
    `i` - The index into the list, from 0
    `value` - The new value to associate with the i'th list element
  Returns:
    The value that was previously at position i in the list
  Throws:
    `ListIndexException` - if the list has fewer than (i + 1) elements.

### contains

    boolean contains(RDFNode value)

  Answer true if the given node appears as the value of a value of any of the cells of this list.

  Parameters:
    `value` - A value to test for
  Returns:
    True if the list contains value.

### indexOf

    int indexOf(RDFNode value)

  Answer the index of the first occurrence of the given value in the list, or -1 if the value is not in the list.

  Parameters:
    `value` - The value to search for
  Returns:
    The index of the first occurrence of value in the list, or `-1` if not found.

### indexOf

    int indexOf(RDFNode value,
                int start)

  Answer the index of the first occurrence of the given value in the list after index `start`, or -1 if the value is not in the list after the given start point.

  Parameters:
    `value` - The value to search for
    `start` - The index into the list to start searching from
  Returns:
    The index of the first occurrence of value in the list not less than `start`, or `-1` if not found.
  Throws:
    `ListIndexException` - if `start` is greater than the length of the list.

### append

    RDFList append(RDFList list)

  Answer a new list that is formed by adding each element of this list to the head of the given `list`. This is a non side-effecting operation on either this list or the given list, but generates a copy of this list. For a more storage efficient alternative, see `concatenate`.

  Parameters:
    `list` - The argument list
  Returns:
    A new RDFList that contains all of this elements of this list, followed by all of the elements of the given list.

### append

    RDFList append(java.util.Iterator nodes)

  Answer a new list that is formed by adding each element of this list to the head of the the list formed from the given `nodes`. This is a non side-effecting operation on either this list or the given list, but generates a copy of this list. For a more storage efficient alternative, see `concatenate`.

  Parameters:
    `nodes` - An iterator whose range is RDFNode
  Returns:
    A new RDFList that contains all of this elements of this list, followed by all of the elements of the given iterator.

### concatenate

    void concatenate(RDFList list)

  Change the tail of this list to point to the given list, so that this list becomes the list of the concatenation of the elements of both lists. This is a side-effecting operation on this list; for a non side-effecting alternative, see `append(com.hp.hpl.jena.rdf.model.RDFList)`. Due to the problem of maintaining the URI invariant on a node, this operation will throw an exception if an attempt is made to concatenate onto an empty list. To avoid this, test for an empty list: if true replace the empty list with the argument list, otherwise proceed with the concatenate as usual. An alternative solution is to use `append(com.hp.hpl.jena.rdf.model.RDFList)` and replace the original list with the return value.

  Parameters:
    `list` - The argument list to concatenate to this list
  Throws:
    `EmptyListUpdateException` - if this list is the nil list

### concatenate

    void concatenate(java.util.Iterator nodes)

  Add the nodes returned by the given iterator to the end of this list.

  Parameters:
    `nodes` - An iterator whose range is RDFNode
  Throws:
    `EmptyListUpdateException` - if this list is the nil list
  See Also:
    `for details on avoiding the empty list update exception.`

### copy

    RDFList copy()

  Answer a list that contains all of the elements of this list in the same order, but is a duplicate copy in the underlying model.

  Returns:
    A copy of the current list

### apply

    void apply(RDFList.ApplyFn fn)

  Apply a function to each value in the list in turn.

  Parameters:
    `fn` - The function to apply to each list node.

### reduce

    java.lang.Object reduce(RDFList.ReduceFn fn,
                            java.lang.Object initial)

  Apply a function to each value in the list in turn, accumulating the results in an accumulator. The final value of the accumulator is returned as the value of `reduce()`.

  Parameters:
    `fn` - The reduction function to apply
    `initial` - The initial value for the accumulator
  Returns:
    The final value of the accumulator.

### mapWith

    ExtendedIterator mapWith(Map1 fn)

  Answer an iterator of the elements of this list, to each of which the given map function has been applied.

  Parameters:
    `fn` - A Map function
  Returns:
    The iterator of the elements of this list mapped with the given map function.

### removeHead

    RDFList removeHead()

  Remove the value from the head of the list. The tail of the list remains in the model. Note that no changes are made to list cells that point to this list cell as their tail. Immediately following a `removeHead` operation, such lists will be in a non-valid state.

  Returns:
    The remainder of the list after the head is removed (i.e. the pre-removal list tail)

### removeAll

    void removeAll()

  Deprecated. Replaced by `removeList()`

  Deprecated. Since an `RDFList` does not behave like a Java container, it is not the case that the contents of the list can be removed and the container filled with values again. Therefore, this method name has been deprecated in favour of `removeList()`

### removeList

    void removeList()

  Remove all of the components of this list from the model. Once this operation has completed, the `RDFList` resource on which it was called will no longer be a resource in the model, so further methods calls on the list object (for example, `size()` will fail. Due to restrictions on the encoding of lists in RDF, it is not possible to perform an operation which empties a list and then adds further values to that list. Client code wishing to perform such an operation should do so in two steps: first remove the old list, then create a new list with the new contents. It is important that RDF statements that reference the old list (in the object position) be updated to point to the newly created list. Note that this is operation is only removing the list cells themselves, not the resources referenced by the list - unless being the object of an `rdf:first` statement is the only mention of that resource in the model.

### remove

    RDFList remove(RDFNode val)

  Remove the given value from this list. If `val` does not occur in the list, no action is taken. Since removing the head of the list will invalidate the list head cell, in general the list must return the list that results from this operation. However, in many cases the return value will be the same as the object that this method is invoked on

  Parameters:
    `val` - The value to be removed from the list
  Returns:
    The resulting list, which will be the same as the current list in most cases, except when `val` occurs at the head of the list.

### iterator

    ExtendedIterator iterator()

  Answer an iterator over the elements of the list. Note that this iterator does not take a snapshot of the list, so changes to the list statements in the model while iterating will affect the behaviour of the iterator. To get an iterator that is not affected by model changes, use `asJavaList()`.

  Returns:
    A closable iterator over the elements of the list.

### asJavaList

    java.util.List asJavaList()

  Answer the contents of this RDF list as a Java list of RDFNode values.

  Returns:
    The contents of this list as a Java List.

### sameListAs

    boolean sameListAs(RDFList list)

  Answer true if this list has the same elements in the same order as the given list. Note that the standard `equals` test just tests for equality of two given list cells. While such a test is sufficient for many purposes, this test provides a broader equality definition, but is correspondingly more expensive to test.

  Parameters:
    `list` - The list to test against
  Returns:
    True if the given list and this list are the same length, and contain equal elements in the same order.

### getStrict

    boolean getStrict()

  Answer true lists are operating in strict mode, in which the well- formedness of the list is checked at every operation.

  Returns:
    True lists are being strictly checked.

### setStrict

    void setStrict(boolean strict)

  Set a flag to indicate whether to strictly check the well-formedness of lists at each operation. Default false. Note that the flag that is manipulated is actually a static: it applies to all lists. However, RDFList is a Java interface, and Java does not permit static methods in interfaces.

  Parameters:
    `strict` - The static flag for whether lists will be checked strictly.

### isValid

    boolean isValid()

  Answer true if the list is well-formed, by checking that each node is correctly typed, and has a head and tail pointer from the correct vocabulary. If the list is invalid, the reason is available via `getValidityErrorMessage()`.

  Returns:
    True if the list is well-formed.
  See Also:
    `getValidityErrorMessage()`

### getValidityErrorMessage

    java.lang.String getValidityErrorMessage()

  Answer the error message returned by the last failed validity check, if any.

  Returns:
    The most recent error message, or null.
  See Also:
    `isValid()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP