001/* Copyright (C) 2013 TU Dortmund
002 * This file is part of AutomataLib, http://www.automatalib.net/.
003 * 
004 * AutomataLib is free software; you can redistribute it and/or
005 * modify it under the terms of the GNU Lesser General Public
006 * License version 3.0 as published by the Free Software Foundation.
007 * 
008 * AutomataLib is distributed in the hope that it will be useful,
009 * but WITHOUT ANY WARRANTY; without even the implied warranty of
010 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
011 * Lesser General Public License for more details.
012 * 
013 * You should have received a copy of the GNU Lesser General Public
014 * License along with AutomataLib; if not, see
015 * http://www.gnu.de/documents/lgpl.en.html.
016 */
017package net.automatalib.commons.smartcollections;
018
019import java.util.Collection;
020import java.util.Comparator;
021
022/**
023 * A generalized priority queue which allows storing arbitrary elements that
024 * don't have to be comparable, neither by their natural ordering nor by a
025 * provided {@link Comparator}. Instead, keys can be assigned to the elements
026 * explicitly.
027 * 
028 * Since this interface extends the {@link SmartCollection} (and thus also
029 * the {@link Collection}) interface, it has to provide the
030 * {@link SmartCollection#referencedAdd(Object)} and
031 * {@link Collection#add(Object)} methods with no additional key parameters.
032 * This is handled by using a <i>default key</i>, which is implicitly used 
033 * for all elements inserted using the above methods. Initially, the default
034 * key is <code>null</code>, whereas the <code>null</code> key is by convention
035 * larger than any non-<code>null</code> key. The default key for consequent
036 * insertions can be changed by calling {@link #setDefaultKey(Comparable)}. 
037 * 
038 * @author Malte Isberner <malte.isberner@gmail.com>
039 *
040 * @param <E> element class.
041 * @param <K> key class.
042 */
043public interface SmartGeneralPriorityQueue<E, K extends Comparable<K>>
044        extends SmartPriorityQueue<E> {
045
046        /**
047         * Inserts an element with the specified key.
048         * 
049         * @param elem the element to insert.
050         * @param key the key for this element.
051         * @return the reference to the inserted element.
052         */
053        public abstract ElementReference add(E elem, K key);
054
055        /**
056         * Sets the default key, which is used for elements that are inserted
057         * with no explicit key specified. 
058         * @param defaultKey the new defualt key.
059         */
060        public abstract void setDefaultKey(K defaultKey);
061
062        /**
063         * Changes the key of an element in the priority key.
064         * @param ref reference to the element whose key is to be changed.
065         * @param newKey the new key of this element.
066         */
067        public abstract void changeKey(ElementReference ref, K newKey);
068}