gr.james.simplegraph.package-info Maven / Gradle / Ivy
Show all versions of simple-graph Show documentation
/**
* The graph interfaces and the respective implementations.
* Vertices, edges and weights
* For simplicity, vertices are, for each graph instance, represented using integers in the range {@code [0,V)}. There
* is no inherent edge value notion; all edges are anonymous but can have a weight assigned on weighted graph types.
* Weights can be of any {@link java.lang.Double} value except {@link java.lang.Double#NaN},
* {@link java.lang.Double#POSITIVE_INFINITY} and {@link java.lang.Double#NEGATIVE_INFINITY}. If the graph is mutable,
* attempts to assign an illegal weight will fail with {@link java.lang.IllegalArgumentException}.
* Mutable/Immutable/Unmodifiable graphs
* All interfaces have a {@code Mutable*} implementation that allows mutation of the object, like vertex/edge
* addition/removal etc. For example, the {@link gr.james.simplegraph.Graph} interface has the
* {@link gr.james.simplegraph.MutableGraph} implementation. The interfaces themselves do not have mutation methods.
* Mutable graphs have various copy constructors from compatible types. For
* example, {@link gr.james.simplegraph.MutableGraph#MutableGraph(WeightedGraph)} will construct a
* {@link gr.james.simplegraph.MutableGraph} from a copy of the argument.
*
* Instances of unmodifiable graphs can be created using the {@code asUnmodifiable()} method of the respective mutable
* graph. This method will return a decorator graph that throws {@link java.lang.UnsupportedOperationException} when
* mutation methods are invoked. It is recommended to use when the client does not have access to the original graph
* reference.
*
* Instances of immutable graphs can be created using the {@code toImmutable()} method, which will first copy the graph
* before decorating it. Due to the underlying copy, this method requires linear time. In essence, the
* {@code toImmutable()} method is equivalent to performing a deep copy of the graph and then calling the
* {@code asUnmodifiable()} method. Therefore, the graph produced by this method is completely independent of the
* original graph, whereas the {@code asUnmodifiable()} method merely returns a wrapper bound to the original graph.
*
Compliance
* All graph classes in this package implement the {@link java.io.Serializable} interface as well as the
* {@link java.lang.Object#equals(java.lang.Object)}, {@link java.lang.Object#hashCode()} and
* {@link java.lang.Object#toString()} methods in a semantically reasonable way.
* Exceptions
* Exceptions are used in a fail-fast approach when certain invocations don't make sense, for example trying to access
* the adjacent nodes of a vertex that doesn't exist or when an argument is {@code null}. These exceptions exist to
* augment the robustness of a client program and should not be catched.
* Primitive operations on graphs
* There is a class {@link gr.james.simplegraph.Graphs} with static helper methods that operate on graphs.
*/
package gr.james.simplegraph;