001 /*
002 * www.ti.bfh.ch
003 *
004 * Copyright 2007, Berne University of Applied Sciences,
005 * School of Engineering and Information Technology
006 * and individual contributors as indicated by the @authors tag.
007 *
008 * This is free software; you can redistribute it and/or modify it under the terms of the
009 * GNU Lesser General Public License as published by the Free Software Foundation;
010 * either version 3 of the License, or (at your option) any later version.
011 *
012 * This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
013 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
014 * See the GNU Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License along with this software;
017 * if not, see <http://www.gnu.org/licenses/>.
018 *
019 */
020 package ch.bfh.algo;
021
022 import java.util.Collection;
023 import java.util.Iterator;
024
025 /**
026 * <p>
027 * A {@link ch.bfh.algo.Container} is a {@link java.util.Collection} of
028 * elements. An element can be directly accessed, it is manipulated through its
029 * {@link ch.bfh.algo.Position} in the {@link ch.bfh.algo.Container}. The
030 * additional methods depend all on the {@link ch.bfh.algo.Position}-based
031 * behaviour of the elements of a {@link ch.bfh.algo.Container}.
032 *
033 *
034 *
035 * @author <a href="http://www.iam.unibe.ch/til/staff/kraehenbuehl">Juerg
036 * Kraehenbuehl</a> (code) and <a
037 * href="http://prof.hti.bfh.ch/bie1">Emmanuel Benoist</a>, <a
038 * href="http://prof.hti.bfh.ch/arb1">Bernhard Anrig</a> (Javadoc)
039 * @version 1.0
040 *
041 * @param <E>
042 * The type of the elements contained in this
043 * {@link ch.bfh.algo.Container}.
044 */
045 public interface Container<E> extends Collection<E>{
046
047 /**
048 * <p>
049 * Inserts the specified <code>element</code> into this
050 * {@link ch.bfh.algo.Container}.
051 *
052 * @param element
053 * The <code>element</code> to be inserted into this
054 * {@link ch.bfh.algo.Container}.
055 * @return The {@link ch.bfh.algo.Position} of the inserted
056 * <code>element</code>.
057 */
058 public Position<E> insert(E element);
059
060
061 /**
062 * <p>
063 * This {@link ch.bfh.algo.Container} determines if
064 * it contains the <code>position</code> and -- if it
065 * is found -- the corresponding element is returned.
066 *
067 * @param position
068 * The <code>position</code> from which the
069 * element is to be returned.
070 * @return The element at the position <code>position</code>
071 * @throws InvalidAccessorException if the <code>position</code>
072 * does not belong to this {@link ch.bfh.algo.Container}
073 */
074 public E element(Position<?> position) throws InvalidAccessorException;
075
076 /**
077 * <p>
078 * Replaces the element at the specified <code>position</code> with
079 * the specified <code>element</code>.
080 *
081 * @param position
082 * The {@link ch.bfh.algo.Position} where the replacement is
083 * carried out.
084 * @param element
085 * The new <code>element</code> at the specified
086 * <code>position</code>.
087 * @return The old element (which is being replaced)
088 *
089 * @throws InvalidAccessorException if the <code>position</code>
090 * does not belong to this {@link ch.bfh.algo.Container}
091 */
092 public E replace(Position<?> position, E element) throws InvalidAccessorException;
093
094 /**
095 * <p>
096 * Tests if the specified <code>position</code> is
097 * contained in this {@code ch.bfh.algo.Container}.
098 *
099 * @param position
100 * This {@link ch.bfh.algo.Container} determines if
101 * it contains the <code>position</code>.
102 * @return True iff the <code>position</code> is contained in
103 * this {@link ch.bfh.algo.Container}, false otherwise
104 */
105 public boolean encloses(Position<?> position);
106
107 /**
108 * <p>
109 * Deletes the specified <code>position</code> and returns
110 * the corresponding element.
111 *
112 * @param position
113 * The {@link ch.bfh.algo.Position} to be deleted
114 * @return The element contained in the <code>position</code>
115 * being deleted
116 *
117 * @throws InvalidAccessorException if the <code>position</code>
118 * does not belong to this {@link ch.bfh.algo.Container}
119 */
120 public E delete(Position<?> position) throws InvalidAccessorException;
121
122 public void swap(Position<?> position0, Position<?> position1) throws InvalidAccessorException;
123
124 /**
125 * <p>
126 * An {@link java.util.Iterator} over all positions is created.
127 *
128 * @return an Iterator over all positions in this
129 * {@code ch.bfh.algo.Container}
130 */
131 public Iterator<Position<E>> positionIterator();
132 }