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}