be.SIRAPRISE.client
Interface TupleContainer

All Superinterfaces:

java.lang.Iterable<Tuple>

All Known Subinterfaces:

Relation, TupleBag

All Known Implementing Classes:

AbstractRelation, AbstractTupleBag, AbstractTupleContainer, InsertionOrderRelation, InsertionOrderTupleBag, OrderedRelation

public interface TupleContainer
extends java.lang.Iterable<Tuple>

The TupleContainer interface defines all methods that must be implemented by tuple containers of any kind.

Author:

Erwin Smout

Method Summary

void	addTuplesWithHeadingCheck(TupleContainer tupleContainer) Adds all tuples of the given TupleContainer to this one.
void	addTuplesWithoutHeadingCheck(TupleContainer tupleContainer) Adds all tuples of the given TupleContainer to this one.
void	addTupleWithHeadingCheck(Tuple tuple) Adds a Tuple to the container.
void	addTupleWithoutHeadingCheck(Tuple tuple) Adds a Tuple to the container without checking the conformance of the tuple to the declared heading.
void	clear() Empties the TupleContainer
boolean	containsTuple(Tuple t) Checks whether the given tuple appears in this container
boolean	containsTuples(TupleContainer tupleContainer) Checks whether all tuples that appear in the given container also appear in this one
Heading	getHeading() Gets the Heading of the tuple container
java.util.Iterator<Tuple>	iterator() Gets an iterator over the tuples in the container.
java.lang.String	printValueEscapedWithoutTypeNames() Gets this relation value in SIRAPRISE syntactical format (i.e. including the SIRA_PRISE escape token preceding any appearance of the tokens '(', ')' and '\' in scalar attribute values in the relation.
java.lang.String	printValueEscapedWithTypeNames() Gets this relation value in SIRAPRISE syntactical format (i.e. including the SIRA_PRISE escape token preceding any appearance of the tokens '(', ')' and '\' in scalar attribute values in the relation.
java.lang.String	printValueWithoutTypeNames() Gets this relation value in 'plain text' format (i.e. if a scalar attribute value includes any of the tokens '(', ')' or '\', these will appear 'as is' in the string value and will not be replaced by the appropriate SIRA_PRISE escape sequence.
java.lang.String	printValueWithTypeNames() Gets this relation value in 'plain text' format (i.e. if a scalar attribute value includes any of the tokens '(', ')' or '\', these will appear 'as is' in the string value and will not be replaced by the appropriate SIRA_PRISE escape sequence.
java.lang.String	printValueXML() Gets this relation value in 'XML text' format.
boolean	removeTuple(Tuple t) Removes the given tuple from this container if that tuple appears there
int	removeTuples(TupleContainer tupleContainer) Removes all tuples appearing in the given tupleContainer from this tupleContainer if that tuple appears there
int	size() Gets The number of tuples that appear in the relation.
<C> C[]	toObjectArray(java.lang.Class<C> objectClass) Deprecated. - Use the replacing DBObjectFactory method instead.
<C> C[]	toObjectArrayIgnoringMissingSetters(java.lang.Class<C> objectClass) Deprecated. - Use the replacing DBObjectFactory method instead.
<C> java.util.Collection<C>	toObjectCollection(java.lang.Class<C> objectClass) Get a collection of objects holding the same information as that which is held in this TupleContainer.
<C> java.util.Collection<C>	toObjectCollectionIgnoringMissingSetters(java.lang.Class<C> objectClass) Get a collection of objects holding a (potentially proper) subset of the information held in this TupleContainer.
java.util.Map<java.lang.Class<?>,java.lang.Object>[]	toObjectsArray(java.lang.Class<?>[] objectClass) Get an array of Maps of objects holding the same information as that which is held in this TupleContainer.
java.util.Collection<java.util.Map<java.lang.Class<?>,java.lang.Object>>	toObjectsCollection(java.lang.Class<?>[] objectClass) Get a collection of Maps of objects holding the same information as that which is held in this TupleContainer.

Method Detail

addTuplesWithHeadingCheck

void addTuplesWithHeadingCheck(TupleContainer tupleContainer)

Adds all tuples of the given TupleContainer to this one. The assignment-compatibility check between the Heading of the given tupleContainer and this one is to be carried out. It is assumed that all tuples contained in the given tupleContainer conform to that container's Heading, so no assignment compatibility checks are needed between the 'source' tuples' Headings and this Container's Heading.

Parameters:

tupleContainer - The TupleContainer whose tuples are all to be added to this one

addTuplesWithoutHeadingCheck

void addTuplesWithoutHeadingCheck(TupleContainer tupleContainer)

Adds all tuples of the given TupleContainer to this one. The assignment-compatibility check between the involved Headings is skipped. This means that it must be guaranteed 'externally' that the tuples to be added do conform to this container's Heading.

Parameters:

tupleContainer - The TupleContainer whose tuples are all to be added to this one

addTupleWithHeadingCheck

void addTupleWithHeadingCheck(Tuple tuple)

Adds a Tuple to the container. The tuple's Heading is checked for conformance with the Container's Heading.

Parameters:

tuple - The tuple to be added to the container

addTupleWithoutHeadingCheck

void addTupleWithoutHeadingCheck(Tuple tuple)

Adds a Tuple to the container without checking the conformance of the tuple to the declared heading. The conformance should be guaranteed externally to this method.

Parameters:

tuple - The tuple to be added to the container

clear

void clear()

Empties the TupleContainer

containsTuple

boolean containsTuple(Tuple t)

Checks whether the given tuple appears in this container

Parameters:

t - The tuple value to be tested for presence in the container

Returns:

true if the tuple value is present in this container

containsTuples

boolean containsTuples(TupleContainer tupleContainer)

Checks whether all tuples that appear in the given container also appear in this one

Parameters:

tupleContainer - The tuple container whose tuples must all be contained in this one for the method to return true

Returns:

true if all tuples that appear in the given container also appear in this one

getHeading

Heading getHeading()

Gets the Heading of the tuple container

Returns:

the Heading of the tuples container

iterator

java.util.Iterator<Tuple> iterator()

Gets an iterator over the tuples in the container. The objects returned by the iterator's next() method will be Tuple obejcts.

Specified by:

iterator in interface java.lang.Iterable<Tuple>

Returns:

an iterator over the tuples in the container

printValueEscapedWithoutTypeNames

java.lang.String printValueEscapedWithoutTypeNames()

Gets this relation value in SIRAPRISE syntactical format (i.e. including the SIRA_PRISE escape token preceding any appearance of the tokens '(', ')' and '\' in scalar attribute values in the relation.

Returns:

this relation value in SIRAPRISE syntactical format

printValueEscapedWithTypeNames

java.lang.String printValueEscapedWithTypeNames()

Gets this relation value in SIRAPRISE syntactical format (i.e. including the SIRA_PRISE escape token preceding any appearance of the tokens '(', ')' and '\' in scalar attribute values in the relation.

Returns:

this relation value in SIRAPRISE syntactical format

printValueWithoutTypeNames

java.lang.String printValueWithoutTypeNames()

Gets this relation value in 'plain text' format (i.e. if a scalar attribute value includes any of the tokens '(', ')' or '\', these will appear 'as is' in the string value and will not be replaced by the appropriate SIRA_PRISE escape sequence.

Returns:

this relation value in 'plain text' format.

printValueWithTypeNames

java.lang.String printValueWithTypeNames()

Gets this relation value in 'plain text' format (i.e. if a scalar attribute value includes any of the tokens '(', ')' or '\', these will appear 'as is' in the string value and will not be replaced by the appropriate SIRA_PRISE escape sequence.

Returns:

this relation value in 'plain text' format.

printValueXML

java.lang.String printValueXML()

Gets this relation value in 'XML text' format.

Returns:

this relation value in 'plain text' format.

removeTuple

boolean removeTuple(Tuple t)

Removes the given tuple from this container if that tuple appears there

Parameters:

t - The tuple to be removed from the container

Returns:

true if the tuple was removed, false if it was not found in this TupleContainer

removeTuples

int removeTuples(TupleContainer tupleContainer)

Removes all tuples appearing in the given tupleContainer from this tupleContainer if that tuple appears there

Parameters:

tupleContainer - The tupleContainer holding all the tuples to be removed from the container

Returns:

the number of tuples effectively removed

size

int size()

Gets The number of tuples that appear in the relation.

Returns:

The number of tuples that appear in the relation.

toObjectArray

<C> C[] toObjectArray(java.lang.Class<C> objectClass)
                  throws ConstructorMissingException,
                         SettersMissingException,
                         ClassDoesNotImplementDBObjectException

Deprecated. - Use the replacing DBObjectFactory method instead.

Get an array of objects holding the same information as that which is held in this TupleContainer. One object is created for each tuple.

Type Parameters:

C - The name of the objectClass, also naming the class/object type of the objects making up the returned array

Parameters:

objectClass - A Class object denoting the class of the objects to be returned. objectClass must denote a public, non-abstract class that has a public no-arg constructor, and that has a unique setter method for each attribute in the heading. The name of this unique method must be the concatenation of the word "set" (all lowercase), followed by the uppercased attribute name (i.e. first character uppercase, all others lowercase), followed by "FromDB". The argument list of this setter method must consist of excatly one java.lang.String argument.

Returns:

An array of objects of the given object Class.

Throws:

ConstructorMissingException - if objectClass does not denote a public class, or it denotes an abstract class, or the class does not have a public no-arg constructor

SettersMissingException - if a needed setter is missing in the class denoted by objectClass

ClassDoesNotImplementDBObjectException - if objectClass does not implement the required DBObject interface

toObjectArrayIgnoringMissingSetters

<C> C[] toObjectArrayIgnoringMissingSetters(java.lang.Class<C> objectClass)
                                        throws ConstructorMissingException,
                                               ClassDoesNotImplementDBObjectException

Deprecated. - Use the replacing DBObjectFactory method instead.

Get an array of objects holding a (potentially proper) subset of the information held in this TupleContainer. One object is created for each tuple. Setters matching an attribute in the heading will be invoked, attributes for which no corresponding setter is found, are ignored.

Type Parameters:

C - The name of the objectClass, also naming the class/object type of the objects making up the returned array

Parameters:

objectClass - A Class object denoting the class of the objects to be returned. objectClass must denote a public, non-abstract class that has a public no-arg constructor, and that has at most one unique setter method for each attribute in the heading. The name of this unique method must be the concatenation of the word "set" (all lowercase), followed by the uppercased attribute name (i.e. first character uppercase, all others lowercase), followed by "FromDB". The argument list of this setter method must consist of excatly one java.lang.String argument.

Returns:

An array of objects of the given object Class.

Throws:

ConstructorMissingException - if objectClass does not denote a public class, or it denotes an abstract class, or the class does not have a public no-arg constructor

ClassDoesNotImplementDBObjectException - if objectClass does not implement the required DBObject interface

toObjectCollection

<C> java.util.Collection<C> toObjectCollection(java.lang.Class<C> objectClass)
                                           throws ConstructorMissingException,
                                                  SettersMissingException,
                                                  ClassDoesNotImplementDBObjectException

Get a collection of objects holding the same information as that which is held in this TupleContainer. One object is created for each tuple.

Type Parameters:

C -

Parameters:

objectClass - A Class object denoting the class of the objects to be returned. objectClass must denote a public, non-abstract class that has a public no-arg constructor, and that has a unique setter method for each attribute in the heading. The name of this unique method must be the concatenation of the word "set" (all lowercase), followed by the uppercased attribute name (i.e. first character uppercase, all others lowercase), followed by "FromDB". The argument list of this setter method must consist of excatly one java.lang.String argument.

Returns:

An array of objects of the given object Class.

Throws:

ConstructorMissingException - if objectClass does not denote a public class, or it denotes an abstract class, or the class does not have a public no-arg constructor

SettersMissingException - if a needed setter is missing in the class denoted by objectClass

ClassDoesNotImplementDBObjectException - if objectClass does not implement the required DBObject interface

toObjectCollectionIgnoringMissingSetters

<C> java.util.Collection<C> toObjectCollectionIgnoringMissingSetters(java.lang.Class<C> objectClass)
                                                                 throws ConstructorMissingException,
                                                                        ClassDoesNotImplementDBObjectException

Get a collection of objects holding a (potentially proper) subset of the information held in this TupleContainer. One object is created for each tuple. Setters matching an attribute in the heading will be invoked, attributes for which no corresponding setter is found, are ignored.

Type Parameters:

C -

Parameters:

objectClass - A Class object denoting the class of the objects to be returned. objectClass must denote a public, non-abstract class that has a public no-arg constructor, and that has at most one unique setter method for each attribute in the heading. The name of this unique method must be the concatenation of the word "set" (all lowercase), followed by the uppercased attribute name (i.e. first character uppercase, all others lowercase), followed by "FromDB". The argument list of this setter method must consist of excatly one java.lang.String argument.

Returns:

An array of objects of the given object Class.

Throws:

ConstructorMissingException - if objectClass does not denote a public class, or it denotes an abstract class, or the class does not have a public no-arg constructor

ClassDoesNotImplementDBObjectException - if objectClass does not implement the required DBObject interface

toObjectsArray

java.util.Map<java.lang.Class<?>,java.lang.Object>[] toObjectsArray(java.lang.Class<?>[] objectClass)
                                                                    throws ConstructorMissingException,
                                                                           SettersMissingException,
                                                                           ClassDoesNotImplementDBObjectException

Get an array of Maps of objects holding the same information as that which is held in this TupleContainer. One Map is returned for each tuple in the container. The entries in the map have one of the objectClass[] objects as their key, and an object of that class as their value. The object of that class holds the attribute values of the tuple for which a corresponding setter method was found in the class.

Parameters:

objectClass - An array of Class objects denoting the classes of the objects to be returned for each tuple. Each objectClass must denote a public, non-abstract class that has a public no-arg constructor, and that has a unique setter method for some attribute in the heading. The name of this unique method must be the concatenation of the word "set" (all lowercase), followed by the uppercased attribute name (i.e. first character uppercase, all others lowercase), followed by "FromDB". The argument list of this setter method must consist of excatly one java.lang.String argument.

Returns:

The array of maps of objects holding the same information as this relation.

Throws:

ConstructorMissingException - if some objectClass does not denote a public class, or it denotes an abstract class, ordenotes a class that does not have a public no-arg constructor

SettersMissingException - if some attribute in the heading exists for which no corresponding setter could be found in any of the classes denoted by objectClass[]

ClassDoesNotImplementDBObjectException - if objectClass does not implement the required DBObject interface

toObjectsCollection

java.util.Collection<java.util.Map<java.lang.Class<?>,java.lang.Object>> toObjectsCollection(java.lang.Class<?>[] objectClass)
                                                                                             throws ConstructorMissingException,
                                                                                                    SettersMissingException,
                                                                                                    ClassDoesNotImplementDBObjectException

Get a collection of Maps of objects holding the same information as that which is held in this TupleContainer. One Map is returned for each tuple in the container. The entries in the map have one of the objectClass[] objects as their key, and an object of that class as their value. The object of that class holds the attribute values of the tuple for which a corresponding setter method was found in the class.

Parameters:

objectClass - An array of Class objects denoting the classes of the objects to be returned for each tuple. Each objectClass must denote a public, non-abstract class that has a public no-arg constructor, and that has a unique setter method for some attribute in the heading. The name of this unique method must be the concatenation of the word "set" (all lowercase), followed by the uppercased attribute name (i.e. first character uppercase, all others lowercase), followed by "FromDB". The argument list of this setter method must consist of excatly one java.lang.String argument.

Returns:

The array of maps of objects holding the same information as this relation.

Throws:

ConstructorMissingException - if some objectClass does not denote a public class, or it denotes an abstract class, ordenotes a class that does not have a public no-arg constructor

SettersMissingException - if some attribute in the heading exists for which no corresponding setter could be found in any of the classes denoted by objectClass[]

ClassDoesNotImplementDBObjectException - if objectClass does not implement the required DBObject interface