com.hp.hpl.jena.daml
Interface DAMLList

All Superinterfaces:

DAMLCommon, RDFNode, Resource

All Known Implementing Classes:

DAMLListImpl

public interface DAMLList

extends DAMLCommon

Java representation of a DAML List. A list is the specified interpretation of rdf:parseType="daml:Collection" attributes, where a sequence of values is interpreted as a nested sequence of head/tail list cells. One consequence of this is that the list is quite specifically ordered, whereas the daml:collection is said to be an unordered collection. Consquently, we must caution that future versions of the DAML specificiation may create an unordered interpretation of daml:collection, and client code should not rely on the positionality of elements in the current list interpretation.

Version:

CVS info: $Id: DAMLList.java,v 1.1 2001/09/24 17:02:39 ijd Exp $

Author:

Ian Dickinson, HP Labs (email)

Method Summary

void	add(DAMLCommon value) Add an element to the list.
DAMLList	cons(DAMLCommon value) Answer a new list formed by creating a new DAMLList element whose first is the given value and whose rest is the current list.
DAMLList	findLast() Find the last list element, i.e.
java.util.Iterator	getAll() Answer an iteration over the values in the list.
int	getCount() Answer a count of the items in the list.
DAMLCommon	getFirst() Answer the first value from the list.
DAMLCommon	getItem(int i) Answer the i'th element of the list, if it exists.
DAMLList	getNil() Answer the well-known constant denoting the nil list.
DAMLList	getRest() Answer a new list that consists of all values of the list save the first.
boolean	isEmpty() Answer true if the list has no values.
boolean	isNil(Resource resource) Answer true if the given resource is the nil list.
void	remove(DAMLCommon value) Remove the given value from the list.
void	setFirst(DAMLCommon value) Set the property daml:first for the given list element.
void	setRest(DAMLList tail) Set the property daml:rest for the given list element.
void	setRestNil() Set the property daml:rest for the given list element to be the nil list.

Methods inherited from interface com.hp.hpl.jena.daml.DAMLCommon

getAll, getDAMLModel, getEquivalenceSet, getEquivalentValues, getNumPropertyValues, getPropertyValue, getPropertyValues, getRDFTypes, getVocabulary, hasRDFType, hasRDFType, prop_comment, prop_equivalentTo, prop_label, prop_type, remove, removeAll, removeProperty, replaceProperty, setPropertyValue, setRDFType, setRDFType

Methods inherited from interface com.hp.hpl.mesa.rdf.jena.model.Resource

abort, addProperty, addProperty, addProperty, addProperty, addProperty, addProperty, addProperty, addProperty, addProperty, begin, commit, equals, getId, getLocalName, getModel, getNameSpace, getProperty, getURI, hasProperty, hasProperty, hasProperty, hasProperty, hasProperty, hasProperty, hasProperty, hasProperty, hasProperty, hasProperty, isAnon, listProperties, listProperties, removeProperties, toString

Method Detail

add

public void add(DAMLCommon value)

Add an element to the list. The element will in fact be added to the head of the list, but DAML collections are, strictly speaking, unordered, so the position of the element in the list should not be relied upon. Note also that we can't add directly into the nil list: this is reserved strictly for marking the end of a list.

Parameters:

value - A DAML value to add to the list

remove

public void remove(DAMLCommon value)

Remove the given value from the list. If the value is not in the list, has no effect. If the value is in the list multiple times, only one of them will be removed.

Parameters:

value - A DAML value to be removed from the list.

getAll

public java.util.Iterator getAll()

Answer an iteration over the values in the list.

Returns:

An iterator over the DAML values in the list

getFirst

public DAMLCommon getFirst()

Answer the first value from the list. Since, strictly speaking, DAML collections are unordered, the position items in the list should not be relied on in client code, as the definition of 'first' in the list may change in future releases. However, the identity

      List L = L.getFirst() + L.getRest()
 

is guaranteed, providing that the contents of L do not change.

Returns:

The first value in the list, or, strictly, an unspecified value from the list.

cons

public DAMLList cons(DAMLCommon value)

Answer a new list formed by creating a new DAMLList element whose first is the given value and whose rest is the current list. This is the 'cons' operator familiar from other list processing languages.

Parameters:

The - new value to be added to the head of the list

Returns:

a new list whose daml:first is the value, and whose daml:rest is this list.

getRest

public DAMLList getRest()

Answer a new list that consists of all values of the list save the first. Since, strictly speaking, DAML collections are unordered, this corresponds to returning the collection minus an unspecified one of its values. However, the identity

      List L = L.getFirst() + L.getRest()
 

is guaranteed, providing that the contents of L do not change.

Returns:

a list that contains all the elements of the current list save one.

getCount

public int getCount()

Answer a count of the items in the list. Does not check for duplications, so this is the count of entries in the list, not the count of distinct items in the list.

Returns:

The number of entries in the list

isEmpty

public boolean isEmpty()

Answer true if the list has no values. The nil list is empty, as is the list with no first and no rest. Note that we retain both conditions as we define the primary resource of a DAML value to be invariant (for indexing purposes). Therefore, a newly created list must be empty, but must not be identical to the nil list since we could never then change it to be a list of values.

Returns:

true for an empty list

setFirst

public void setFirst(DAMLCommon value)

Set the property daml:first for the given list element. This is a single value that denotes the value at this position of the list.

Parameters:

value - The value to be assigned to the 'first' property of a list cell

setRest

public void setRest(DAMLList tail)

Set the property daml:rest for the given list element. This is a single value that denotes the tail of the list.

Parameters:

value - The value to be assigned to the tail of the list.

setRestNil

public void setRestNil()

Set the property daml:rest for the given list element to be the nil list. This correctly terminates the list at this point.

getNil

public DAMLList getNil()

Answer the well-known constant denoting the nil list.

Returns:

The resource denoting nil

isNil

public boolean isNil(Resource resource)

Answer true if the given resource is the nil list.

Parameters:

resource - The resource to be tested

Returns:

true if the resource is the nil list

findLast

public DAMLList findLast()

Find the last list element, i.e. the one whose rest is nil.

Returns:

A list element

getItem

public DAMLCommon getItem(int i)

Answer the i'th element of the list, if it exists. If i is less than 1, or is larger than the length of the list, throw an illegal argument exception.

Parameters:

i - The position of the list to return

Returns:

The DAML value at the i'th position in the list

Throws:

java.lang.IllegalArgumentException - if i is less than one, or larger than the length of the list.