net.sf.javagimmicks.collections.mapping.ValueMappings Maven / Gradle / Ivy
Show all versions of gimmicks Show documentation
package net.sf.javagimmicks.collections.mapping;
import java.util.Collection;
import java.util.Iterator;
import java.util.Map;
import java.util.Set;
import net.sf.javagimmicks.collections.mapping.ValueMappings.Mapping;
/**
* Represents a n:m relation between two sets of elements where each mapping can
* carry an additional value (in contradiction to {@link Mappings}) providing a
* backed {@link Map} view of each "side" of the relation as well as many
* analytic and modification operations.
*
* Example: Assume you have a set of persons - e.g. Alice,
* Bob and Charles as well as a set of hobbies - e.g.
* Astrology, Biking and Chess and you want to model any
* associations between persons and hobbies where each association should tell
* how much the person likes the hobby (e.g. Little or Much), this
* class is just the right thing for you:
*
* The code below shows how to create an appropriate instance and fill it with
* some mappings:
*
*
* final ValueMappings<Person, Hobby, Likes> m = DualMapValueMappings.<Person, Hobby, Likes> createTreeTreeInstance();
*
* // Alice has hobbies Biking and Chess
* m.put(Person.Alice, Hobby.Biking, Likes.Little);
* m.put(Person.Alice, Hobby.Chess, Likes.Much);
*
* // Bob has hobbies Astrology and Chess
* m.put(Person.Bob, Hobby.Astrology, Likes.Much);
* m.put(Person.Bob, Hobby.Chess, Likes.Little);
*
* // Charles has hobbies Astrology and Biking
* m.put(Person.Charles, Hobby.Astrology, Likes.Little);
* m.put(Person.Charles, Hobby.Biking, Likes.Much);
*
*
* Now you can get a "left view" (showing the hobbies for each person and how
* much the person likes the hobby) and a "right view" (showing the persons for
* each hobby and how much the person likes the hobby) from the {@link Mappings}
* object:
*
*
* {@code
* System.out.println(m.getLeftView());
* // Prints {Alice={Biking=Little, Chess=Much}, Bob={Astrology=Much, Chess=Little}, Charles={Astrology=Little, Biking=Much}}
*
* System.out.println(m.getRightView());
* // Prints {Astrology={Bob=Much, Charles=Little}, Biking={Alice=Little, Charles=Much}, Chess={Alice=Much, Bob=Little}}
* }
*
*
* For more things that you can do with {@link ValueMappings}, please consult
* the method descriptions.
*
* If you don't want to assign a value for each mapping but simply want to
* associate left and right elements without additional information,
* {@link Mappings} is the right choice for you.
*
* @see Mappings
* @param
* the type of left keys of the {@link ValueMappings}
* @param
* the type of right keys of the {@link ValueMappings}
* @param
* the type of values associated with the mappings
*/
public interface ValueMappings extends Iterable>
{
/**
* Adds a new or replaces an existing mapping (or association) between a
* given left key and right key with the given value.
*
* @param left
* the left key of the new mapping
* @param right
* the right key of the new mapping
* @param value
* the value to associate with the new or existing mapping
* @return the previous value associated with the mapping or {@code null} of
* the mapping is new
*/
E put(L left, R right, E value);
/**
* Bulk-adds a bunch of left key-value associations for a single given right
* key.
*
* @param right
* the right key to add a bunch of left key-value associations for
* @param map
* a {@link Map} containing the left keys to add for the given
* right key as well as the values to associate with the respective
* new mappings
*/
void putAllForRightKey(R right, Map map);
/**
* Bulk-adds a bunch of right key-value associations for a single given left
* key.
*
* @param left
* the left key to add a bunch of right key-value associations for
* @param map
* a {@link Map} containing the right keys to add for the given
* left key as well as the values to associate with the respective
* new mappings
*/
void putAllForLeftKey(L left, Map map);
/**
* Removes a given mapping specified by left and right key from this
* instance.
*
* @param left
* the left key of the mapping to remove
* @param right
* the right key of the mapping to remove
* @return the value that was associated with the removed mapping or
* {@code null} if no such mapping was contained
*/
E remove(L left, R right);
/**
* Completely removes a given right key together with all it's mappings from
* this instance.
*
* @param right
* the right key to remove
* @return the {@link Map} containing the left keys that were mapped to the
* given right key as well as the associated values
*/
Map removeRightKey(R right);
/**
* Completely removes a given left key together with all it's mappings from
* this instance.
*
* @param left
* the left key to remove
* @return the {@link Map} containing the right keys that were mapped to with
* the given left key as well as the associated values
*/
Map removeLeftKey(L left);
/**
* Removes all mappings from this instance
*/
void clear();
/**
* Checks if a given mapping specified by left and right key is contained in
* the current instance.
*
* @param left
* the left key of the mapping to remove
* @param right
* the right key of the mapping to remove
* @return if the specified mapping is contained in the current instance
*/
boolean containsMapping(L left, R right);
/**
* Check if any mappings are contained in this instance for a given left key.
*
* @param left
* the left key to check for any existing mappings
* @return if there is at least one mapping contained for the given left key
*/
boolean containsLeftKey(L left);
/**
* Check if any mappings are contained in this instance for a given right
* key.
*
* @param right
* the right key to check for any existing mappings
* @return if there is at least one mapping contained for the given right key
*/
boolean containsRightKey(R right);
/**
* Returns the number of mappings contained within the current instance.
*
* @return the number of mappings contained within the current instance
*/
int size();
/**
* Checks if the current instance contains no mappings.
*
* @return if the current instance contains no mappings
*/
boolean isEmpty();
/**
* Retrieve the value associated with the mapping specified by left and right
* key.
*
* @param left
* the left key of the mapping whose value should be retrieved
* @param right
* the right key of the mapping whose value should be retrieved
* @return the associated value or {@code null} if no such mapping was
* contained
*/
E get(L left, R right);
/**
* Returns all mappings contained within this instance as a {@link Set} of
* {@link Mapping} instances.
*
* @return all mappings contained within this instance
*/
Set> getMappingSet();
/**
* Returns a {@link Collection} of the values of all mappings contained
* within this instance.
*
* @return a {@link Collection} of the values of all mappings
*/
Collection getValues();
/**
* Return the "left view" of this instance - that is a {@link Map} that
* contains on the key side the left mapping keys and on the value side
* another {@link Map} which has on the key side the right mapping keys and
* on the value side the associated values.
*
* Have a look at the example with the {@link ValueMappings class
* documentation} to get a better understanding.
*
* @return the left view of this instance as {@link Map}
*/
Map> getLeftView();
/**
* Return the "right view" of this instance - that is a {@link Map} that
* contains on the key side the right mapping keys and on the value side
* another {@link Map} which has on the key side the left mapping keys and on
* the value side the associated values.
*
* Have a look at the example with the {@link ValueMappings class
* documentation} to get a better understanding.
*
* @return the right view of this instance as {@link Map}
*/
Map> getRightView();
/**
* Returns a {@link Map} of all left keys that are mapped to a given right
* key and the associated values.
*
* @param right
* the right key to get all mapped left keys for
* @return the {@link Map} of left keys mapped to the given right key
*/
Map getAllForRightKey(R right);
/**
* Returns a {@link Map} of all right keys that are mapped to a given left
* key and the associated values.
*
* @param left
* the left key to get all mapped right keys for
* @return the {@link Map} of right keys mapped to the given left key
*/
Map getAllForLeftKey(L left);
/**
* Returns an inverted view of this instance (left and right keys are
* exchanged).
*
* @return an inverted view of this instance
*/
ValueMappings invert();
/**
* Returns an {@link Iterator} of all contained {@link Mapping}s.
*
* @see #getMappingSet()
*/
@Override
Iterator> iterator();
/**
* Represents a single left-to-right mapping contained within a
* {@link ValueMappings} object.
*
* @param
* the type of left keys of the {@link Mapping}
* @param
* the type of right keys of the {@link Mapping}
* @param
* the type of values associated with the mappings
*/
interface Mapping
{
/**
* Returns the left key of the mapping.
*
* @return the left key of the mapping
*/
L getLeftKey();
/**
* Returns the right key of the mapping.
*
* @return the right key of the mapping
*/
R getRightKey();
/**
* Returns the value associated with the mapping.
*
* @return the value associated with the mapping
*/
E getValue();
/**
* Returns an inverted view of this instance (with exchanged left and
* right key).
*
* @return an inverted view of this instance
*/
Mapping invert();
}
}