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    /**
023     * The <code>Position</code> interface is used as a placeholder in all the containers (for instance <code>Sequence</code>, <code>Forest</code>, or <code>Graph</code>). It contains an element and does not have any other functionalities. It is passed as a parameter to the container for accessing its internal functionalities. One will use this interface to implement efficiently methods that could not be done without this feature.
024     *
025     * In the following example, we use two positions to visit a sequence
026     * 
027     * <pre>
028    Position&lt;Integer&gt; pos1 = seq.first();
029    while(pos1!=seq.last()){
030        pos2=seq.after(pos1);
031        if( pos1.element()> pos2.element()){
032            Integer tmp = pos1.element();
033            seq.replace(pos1,pos2.element());
034            seq.replace(pos2,tmp);
035        }
036    }
037      * </pre>
038      *
039      * We will also use Positions to visit a graph (we reverse all edges
040      * of the given graph):
041      *
042      * <pre>
043        public static void reverseAllEdges(Graph<Integer,String> g){
044            for(Position<Integer> e : g.edges(Direction.DIRECTED)){
045                g.reverse(e);
046            }
047        }
048      * </pre>
049      *
050      * @author <a href="http://www.iam.unibe.ch/til/staff/kraehenbuehl">Juerg
051      * Kraehenbuehl</a> (code) and <a href="http://prof.hti.bfh.ch/bie1">Emmanuel
052      * Benoist</a> (Javadoc)
053      * @version 1.0
054      */
055    public interface Position<E> {
056        /**
057         * The <code>locator</code> method is used to
058         * access the second level place holder (used only for complex data structures) such that ...
059         *
060         * 
061         * @return the <code>Locator&lt;E&gt;</code> contained in the
062         * <code>Position</code>
063         */
064        public Locator<E> locator();
065        
066        /**
067         * The method <code>element()</code> returns the
068         * element contained in the position.
069         * 
070         * @return E the element contained in the <code>Position</code>
071         */
072        public E element();
073    }