001/*
002 * JPPF.
003 * Copyright (C) 2005-2018 JPPF Team.
004 * http://www.jppf.org
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.jppf.utils.collections;
020
021import java.io.Serializable;
022import java.util.*;
023import java.util.concurrent.locks.Lock;
024
025/**
026 * Interface for maps whose values are collections of a given component type.
027 * @param <K> the type of keys in the map.
028 * @param <V> the type of values in the collections mapped to the keys.
029 * @author Laurent Cohen
030 */
031public interface CollectionMap<K, V> extends Iterable<V>, Serializable
032{
033  /**
034   * Add a value for the specified key.
035   * @param key the key for which to add a value.
036   * @param value the value to add.
037   */
038  void putValue(final K key, final V value);
039
040  /**
041   * Remove a value from the specified key.
042   * @param key the key from which to remove a value.
043   * @param value the value to remove.
044   * @return <code>true</code> if an element was removed, <code>false</code> otherwise.
045   */
046  boolean removeValue(final K key, final V value);
047
048  /**
049   * Add the specified values to the specified key. This is a bulk operation.
050   * @param key the key to which to add the values.
051   * @param values the values to add to the key.
052   */
053  void addValues(final K key, final Collection<V> values);
054
055  /**
056   * Add the specified values to the specified key. This is a bulk operation.
057   * @param key the key to which to add the values.
058   * @param values the values to add to the key.
059   */
060  void addValues(final K key, @SuppressWarnings("unchecked") final V... values);
061
062  /**
063   * Remove the specified values from the specified key. This is a bulk operation.
064   * @param key the key for which to rmeove the values.
065   * @param values the values to remove.
066   * @return the number of values that were actually removed, possibly zero.
067   */
068  int removeValues(final K key, @SuppressWarnings("unchecked") final V... values);
069
070  /**
071   * Remove the specified key from this map.
072   * @param key the key to remove.
073   * @return collection of values that were removed, possibly <code>null</code>.
074   */
075  Collection<V> removeKey(final K key);
076
077  /**
078   * Get the collection of values maped to the specified key.
079   * @param key the key to lookup.
080   * @return a collection of values that mapped to the key, or <code>null</code> if no mapping exists for the key.
081   */
082  Collection<V> getValues(final K key);
083
084  /**
085   * Get the total number of elements in this collection map.
086   * Note that the cost of the {@code size()} operation will be in O(n).
087   * @return the number of elements as an int value.
088   */
089  int size();
090
091  /**
092   * Determine whether this map is empty.
093   * @return <code>true</code> if the map is empty, <code>false</code> otherwise.
094   */
095  boolean isEmpty();
096
097  /**
098   * Determine whether this map contains the specified key.
099   * @param key the key to lookup.
100   * @return <code>true</code> if there is a mapping for the key, <code>false</code> otherwise.
101   */
102  boolean containsKey(final K key);
103
104  /**
105   * Determine whether the collection mapped to the specified key contains the specified value.
106   * @param key the key whose mapped collection is looked up^.
107   * @param value the value to look in the collection.
108   * @return <code>true</code> if the map contains the key and the corresponding collection contains the value, <code>false</code> otehrwise.
109   */
110  boolean containsValue(final K key, final V value);
111
112  /**
113   * Determine whether at least one of the collections in the map contains the specified value.
114   * @param value the value to look up in the entire map.
115   * @return <code>true</code> if the map contains the value, <code>false</code> otehrwise.
116   */
117  boolean containsValue(final V value);
118
119  /**
120   * Get an iterator which uses the specified lock.
121   * @param lock the lock used to synchronize access to the map.
122   * @return an iterator on the values of the map.
123   */
124  Iterator<V> iterator(final Lock lock);
125
126  /**
127   * Get the set of keys in the map.
128   * @return a {@link Set} of all keys.
129   */
130  Set<K> keySet();
131
132  /**
133   * Get the set map entries.
134   * @return a {@link Set} of all map entries.
135   */
136  Set<Map.Entry<K, Collection<V>>> entrySet();
137
138  /**
139   * Clear the map.
140   */
141  void clear();
142
143  /**
144   * Get a collection of all the values for all keys.
145   * @return a collection of all values in this map.
146   */
147  List<V> allValues();
148}