org.helenus.commons.collections.DirectedGraph Maven / Gradle / Ivy
Show all versions of helenus-commons Show documentation
/*
* Copyright (C) 2015-2015 The Helenus Driver Project Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.helenus.commons.collections;
import java.io.Serializable;
import java.util.Comparator;
import java.util.NoSuchElementException;
import java.util.Set;
import java.util.stream.Stream;
/**
* The DirectedGraph interface provides a collection of nodes with
* outgoing edges to other nodes.
*
* @copyright 2015-2015 The Helenus Driver Project Authors
*
* @author The Helenus Driver Project Authors
* @version 1 - Jan 15, 2015 - paouelle - Creation
*
* @param the type of elements in this graph
*
* @since 2.0
*/
public interface DirectedGraph extends Set {
/**
* Gets a node from this graph given its value.
*
* @author paouelle
*
* @param val the value for the node to retrieve
* @return the corresponding node from this graph or null if the
* graph doesn't contain a node with the specified value
*/
public DirectedGraph.Node get(T val);
/**
* Gets a {@link Set} view of all the nodes contained in this directed graph.
*
* The set is backed by the graph, so changes to the graph are reflected in
* the set, and vice-versa. If the graph is modified while an iteration over
* the set is in progress (except through the iterator's own remove()
* operation, or through the addEdge() or removeEdge()
* operations on a graph node returned by the iterator) the results of the
* iteration are undefined. The set supports node removal, which removes the
* corresponding node from the graph, via the Iterator.remove(),
* Set.remove, removeAll, retainAll,
* and clear operations. It does not support the add
* or addAll operations.
*
* @author paouelle
*
* @return a set view of the nodes contained in this graph
*/
public Set> nodeSet();
/**
* Adds the specified nodes if they don't exist in the graph and build an arc
* from the starting node to the destination one.
*
* @param start the starting node
* @param dest the destination node
*/
public void add(T start, T dest);
/**
* Adds the specified nodes if they don't exist in the graph and build arcs
* from the starting node to all the destination ones.
*
* @param start the starting node
* @param dests the destination nodes
*/
public void add(T start, Stream dests);
/**
* Adds an arc from the starting node to the destination one. If an arc
* already exists, this operation is a no-op.
*
* @param start the starting node
* @param dest the destination node
* @throws NoSuchElementException if either nodes do not exist
*/
public void addEdge(T start, T dest);
/**
* Removes the edge from the specified starting node to the specified destination
* node from the graph.
*
* @param start the starting node
* @param dest the destination node
* @return true if an edge was removed; false
* otherwise
* @throws NoSuchElementException if either nodes do not exist
*/
public boolean removeEdge(T start, T dest);
/**
* Given two nodes in the graph, returns whether there is an edge from the
* first node to the second node.
*
* @param start the starting node
* @param dest the destination node
* @return true if an edge exists from start to
* dest; falseotherwise
* @throws NoSuchElementException if either nodes do not exist
*/
public boolean edgeExists(T start, T dest);
/**
* Given a node in the graph, returns a stream of the edges leaving that node.
*
* @param node the node whose edges should be queried
* @return a stream of the edges leaving that node
* @throws NoSuchElementException if the node does not exist
*/
public Stream edgesFrom(T node);
/**
* Given a node in the graph, returns an immutable view of the edges
* leaving that node as a set of endpoints.
*
* @param node the node whose edges should be queried
* @return an immutable view of the edges leaving that node
* @throws NoSuchElementException if the node does not exist
*/
public Set getEdgesFrom(T node);
/**
* The Node interface represents a specific node in this directed
* graph.
*
* @copyright 2015-2015 The Helenus Driver Project Authors
*
* @author The Helenus Driver Project Authors
* @version 1 - Jan 15, 2015 - paouelle - Creation
*
* @param the type of value
*
* @since 2.0
*/
public interface Node {
/**
* Gets a comparator that compares {@link DirectedGraph.Node} in natural
* order on value.
*
* The returned comparator is serializable and throws
* {@link NullPointerException} when comparing a node with a null value.
*
* @param the type of elements in this graph
*
* @return a comparator that compares {@link DirectedGraph.Node} in natural
* order on value
*
* @see Comparable
*/
public static > Comparator> comparingByValue() {
return (Comparator> & Serializable)
(c1, c2) -> c1.getValue().compareTo(c2.getValue());
}
/**
* Gets a comparator that compares {@link DirectedGraph.Node} by value using
* the given {@link Comparator}.
*
* The returned comparator is serializable if the specified comparator is
* also serializable.
*
* @param the type of elements in this graph
*
* @param cmp the value {@link Comparator}
* @return a comparator that compares {@link DirectedGraph.Node} by the value
*/
public static Comparator> comparingByValue(Comparator cmp) {
org.apache.commons.lang3.Validate.notNull(cmp, "invalid null comparator");
return (Comparator> & Serializable)
(c1, c2) -> cmp.compare(c1.getValue(), c2.getValue());
}
/**
* Gets the value for this node.
*
* @author paouelle
*
* @return this node's value
*/
public T getValue();
/**
* Checks if there this node has an edge to another node.
*
* @param dest the destination node
* @return true if an edge exists from this node to
* dest; falseotherwise
* @throws NoSuchElementException if the destination node does not exist
*/
public boolean edgeExists(T dest);
/**
* Gets an immutable view of the edge nodes leaving this node.
*
* @author paouelle
*
* @return an immutable view of the edge nodes leaving this node
*/
public Set> getEdges();
/**
* Gets a stream of the edge nodes leaving this node.
*
* @author paouelle
*
* @return a stream of the edge nodes leaving this node
*/
public Stream> edges();
/**
* Adds the specified destination node if missing and add an arc from this
* node to the destination one.
*
* @param dest the destination node
*/
public void add(T dest);
/**
* Adds the specified destination nodes if missing and add arcs from this
* node to all the destination ones.
*
* @param dests the destination nodes
*/
public void add(Stream dests);
/**
* Adds an arc from this node to the destination one. If an arc
* already exists, this operation is a no-op.
*
* @param dest the destination node
* @throws NoSuchElementException if the destination node does not exist
*/
public void addEdge(T dest);
/**
* Removes the edge from this node to the specified destination node from
* the graph.
*
* @param dest the destination node
* @return true if an edge was removed; false
* otherwise
* @throws NoSuchElementException if the destination node does not exist
*/
public boolean removeEdge(T dest);
/**
* {@inheritDoc}
*
* @author paouelle
*
* @see java.lang.Object#hashCode()
*/
@Override
public int hashCode();
/**
* {@inheritDoc}
*
* @author paouelle
*
* @see java.lang.Object#equals(java.lang.Object)
*/
@Override
public boolean equals(Object o);
}
}