001    /*
002     *  Licensed to the Apache Software Foundation (ASF) under one or more
003     *  contributor license agreements.  See the NOTICE file distributed with
004     *  this work for additional information regarding copyright ownership.
005     *  The ASF licenses this file to You under the Apache License, Version 2.0
006     *  (the "License"); you may not use this file except in compliance with
007     *  the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     *  Unless required by applicable law or agreed to in writing, software
012     *  distributed under the License is distributed on an "AS IS" BASIS,
013     *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     *  See the License for the specific language governing permissions and
015     *  limitations under the License.
016     */
017    package org.apache.commons.collections;
018    
019    /**
020     * Defines a map that allows bidirectional lookup between key and values
021     * and retains and provides access to an ordering.
022     * <p>
023     * Implementations should allow a value to be looked up from a key and
024     * a key to be looked up from a value with equal performance.
025     * 
026     * @since Commons Collections 3.0
027     * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
028     *
029     * @author Stephen Colebourne
030     */
031    public interface OrderedBidiMap extends BidiMap, OrderedMap {
032    
033        /**
034         * Gets a view of this map where the keys and values are reversed.
035         * <p>
036         * Changes to one map will be visible in the other and vice versa.
037         * This enables both directions of the map to be accessed equally.
038         * <p>
039         * Implementations should seek to avoid creating a new object every time this
040         * method is called. See <code>AbstractMap.values()</code> etc. Calling this
041         * method on the inverse map should return the original.
042         * <p>
043         * Implementations must return an <code>OrderedBidiMap</code> instance,
044         * usually by forwarding to <code>inverseOrderedBidiMap()</code>.
045         *
046         * @return an inverted bidirectional map
047         */
048        public BidiMap inverseBidiMap();
049        
050        /**
051         * Gets a view of this map where the keys and values are reversed.
052         * <p>
053         * Changes to one map will be visible in the other and vice versa.
054         * This enables both directions of the map to be accessed equally.
055         * <p>
056         * Implementations should seek to avoid creating a new object every time this
057         * method is called. See <code>AbstractMap.values()</code> etc. Calling this
058         * method on the inverse map should return the original.
059         *
060         * @return an inverted bidirectional map
061         */
062        public OrderedBidiMap inverseOrderedBidiMap();
063        
064    }