jdsl.core.api
Interface CircularSequence

All Superinterfaces:

Container, InspectableCircularSequence, InspectableContainer, InspectablePositionalContainer, PositionalContainer

All Known Implementing Classes:

AbstractCircularSequence

public interface CircularSequence

extends InspectableCircularSequence, PositionalContainer

A circular sequence stores elements in a ring, in other words it is a sequence without a head or a tail. As a result, it is impossible to generate a boundary violation in methods such as before(Position) and after(Position).

For a CircularSequence, methods InspectableContainer.elements() and InspectablePositionalContainer.positions() are guaranteed to return iterators in order. Which is to say that these iterators return elements in order in which they would have been accessed by repeated application of InspectableCircularSequence.after(.) but do not guarantee that they start with InspectableCircularSequence.startingPosition().

Version:

$Id: CircularSequence.java,v 1.8 2001/01/22 18:02:15 lv Exp $

Author:

Mark Handy (mdh), Luca Vismara (lv), Andrew Schwerin (schwerin), Galina Shubina (gs)

See Also:

InspectableCircularSequence, PositionalContainer

Method Summary

Position	insertAfter(Position p, java.lang.Object element) Inserts an element after a given position.
Position	insertBefore(Position p, java.lang.Object element) Inserts an element before a given position.
Position	insertInitial(java.lang.Object element) Inserts a given element into an empty circular sequence.
java.lang.Object	remove(Position pos) Remove and invalidate the position specified
java.lang.Object	removeAfter(Position pos) Remove and invalidate the position after the position specified
java.lang.Object	removeBefore(Position pos) Remove the position before the position specified
void	setStartingPosition(Position p) Sets the position that will be returned by method startingPosition() of InspectableCircularSequence
void	splice(Position afterWhich, CircularSequence toMerge, Position newSuccessor) Merges in another CircularSequence (leaving it empty) after a given position.
CircularSequence	split(Position inNewA, Position inNewB) Snips out a chain of nodes from this CircularSequence, repairs this CircularSequence, and makes a new CircularSequence with the snipped-out nodes.

Methods inherited from interface jdsl.core.api.InspectableCircularSequence

after, before, startingPosition

Methods inherited from interface jdsl.core.api.InspectablePositionalContainer

positions

Methods inherited from interface jdsl.core.api.InspectableContainer

contains, elements, isEmpty, size

Methods inherited from interface jdsl.core.api.PositionalContainer

swapElements

Methods inherited from interface jdsl.core.api.Container

newContainer, replaceElement

Method Detail

setStartingPosition

public void setStartingPosition(Position p)
                         throws InvalidAccessorException,
                                EmptyContainerException

Sets the position that will be returned by method startingPosition() of InspectableCircularSequence

Throws:

InvalidAccessorException - if p is not a valid position in this circular sequence

EmptyContainerException - if there are no elements in this circular sequence

insertBefore

public Position insertBefore(Position p,
                             java.lang.Object element)
                      throws InvalidAccessorException

Inserts an element before a given position.

Parameters:

p - A position in this sequence

element - Any object

Returns:

Position of Object element, now stored before Position p (the parameter)

Throws:

InvalidAccessorException - if p is not a valid position in this circular sequence

insertAfter

public Position insertAfter(Position p,
                            java.lang.Object element)
                     throws InvalidAccessorException

Inserts an element after a given position.

Parameters:

p - A position in this sequence

element - object

Returns:

Position of Object element, now stored after Position p (the parameter)

Throws:

InvalidAccessorException - if p is not a valid position in this circular sequence

insertInitial

public Position insertInitial(java.lang.Object element)
                       throws NonEmptyContainerException

Inserts a given element into an empty circular sequence. Necessary so that an empty container may be caused to contain elements, this method will throw an exception when called upon a circular sequence containing any elements.

Parameters:

element - Any object

Returns:

Position of the inserted object

Throws:

NonEmptyContainerException - if there are no elements in this circular sequence.

remove

public java.lang.Object remove(Position pos)
                        throws InvalidAccessorException

Remove and invalidate the position specified

Parameters:

pos - the position to be removed

Returns:

the element formerly stored at pos

Throws:

InvalidAccessorException - if pos is not a valid position in the circular sequence.

removeAfter

public java.lang.Object removeAfter(Position pos)
                             throws InvalidAccessorException

Remove and invalidate the position after the position specified

Parameters:

pos - a position

Returns:

the element formerly stored at the position after pos

Throws:

InvalidAccessorException - if pos is not a valid position in the circular sequence.

removeBefore

public java.lang.Object removeBefore(Position pos)
                              throws InvalidAccessorException

Remove the position before the position specified

Parameters:

pos - a position

Returns:

the element formerly stored at the position before pos

Throws:

InvalidAccessorException - if pos is not a valid position in the circular sequence.

split

public CircularSequence split(Position inNewA,
                              Position inNewB)
                       throws InvalidAccessorException

Snips out a chain of nodes from this CircularSequence, repairs this CircularSequence, and makes a new CircularSequence with the snipped-out nodes. If inNewA==inNewB, only that one Position is removed from the initial CircularSequence and inserted into the new one.

Parameters:

inNewA - Start of sequence of Positions to be removed from this CircularSequence

inNewB - End of sequence of Positions to be removed from this CircularSequence

Returns:

A new CircularSequence holding inNewA, inNewB, and all the Positions after inNewA and before inNewB.

Throws:

InvalidAccessorException - if neither inNewA nor inNewB is a valid positions contained in this circular sequence.

splice

public void splice(Position afterWhich,
                   CircularSequence toMerge,
                   Position newSuccessor)
            throws InvalidAccessorException,
                   InvalidContainerException

Merges in another CircularSequence (leaving it empty) after a given position. That is, this CircularSequence is snipped after a given Position, and the merged-in CircularSequence is snipped before a given Position.

Parameters:

afterWhich - Position after which to break this CircularSequence

toMerge - CircularSequence to be spliced into this one

newSuccessor - Position from toMerge that will follow Position afterWhich in this CircularSequence

Throws:

InvalidAccessorException - if either afterWhich is not a valid position in this container or newSuccessor is not a valid position in toMerge

InvalidContainerException - if toMerge is null, or of the wrong implementation type, or equal to this circular sequence