diff --git a/README.md b/README.md index 8721fd10c3b..9305fc97f50 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -![Build Status](https://github.com/jgrapht/jgrapht/workflows/JGrapht%20Master%20build/badge.svg) +[![JGrapht Master build](https://github.com/jgrapht/jgrapht/actions/workflows/master-workflow.yaml/badge.svg)](https://github.com/jgrapht/jgrapht/actions/workflows/master-workflow.yaml) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.jgrapht/jgrapht/badge.svg)](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jgrapht%22) [![Snapshot](https://img.shields.io/nexus/s/https/oss.sonatype.org/org.jgrapht/jgrapht.svg)](https://oss.sonatype.org/content/repositories/snapshots/org/jgrapht/jgrapht-core/) -[![License](https://img.shields.io/badge/license-LGPL%202.1-blue.svg)](http://www.gnu.org/licenses/lgpl-2.1.html) -[![License](https://img.shields.io/badge/license-EPL%202.0-blue.svg)](http://www.eclipse.org/legal/epl-2.0) +[![License](https://img.shields.io/badge/license-LGPL%202.1-blue.svg)](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html) +[![License](https://img.shields.io/badge/license-EPL%202.0-blue.svg)](https://www.eclipse.org/legal/epl-2.0) [![Language](http://img.shields.io/badge/language-java-brightgreen.svg)](https://www.java.com/) # JGraphT @@ -25,16 +25,16 @@ JGraphT is a free Java class library that provides mathematical graph-theory obj JGraphT may be used under the terms of either the * GNU Lesser General Public License (LGPL) 2.1 - + or the * Eclipse Public License (EPL) - + As a recipient of JGraphT, you may choose which license to receive the code under. -For detailed information on the dual license approach, see . +For detailed information on the dual license approach, see . A copy of the [EPL license](license-EPL.txt) and the [LPGL license](license-LGPL.txt) is included in the download. @@ -82,7 +82,7 @@ The files below make up the table of contents for a release distribution archive ## Getting Started ## -The JGraphT [wiki](https://github.com/jgrapht/jgrapht/wiki) provides various helpful pages for new users, including a [How to use JGraphT in your projects](https://github.com/jgrapht/jgrapht/wiki/Users%3A-How-to-use-JGraphT-as-a-dependency-in-your-projects) page. +The JGraphT [wiki](https://github.com/jgrapht/jgrapht/wiki) provides various helpful pages for new users, including a [How to use JGraphT in your projects](https://github.com/jgrapht/jgrapht/wiki/Users:-How-to-use-JGraphT-as-a-dependency-in-your-projects) page. The package `org.jgrapht.demo` includes small demo applications to help you get started. If you spawn your own demo app and think others can use it, please send it to us and we will add it to that package. To run the graph visualization demo from the downloaded release, try executing this command in the lib directory: @@ -91,7 +91,7 @@ To run the graph visualization demo from the downloaded release, try executing t More information can be found on the [user pages](https://github.com/jgrapht/jgrapht/wiki#user-pages) of our wiki. Finally, all classes come with corresponding test classes. These test classes contain many examples. -To help us understand how you use JGraphT, and which features are important to you, [tell](https://github.com/jgrapht/jgrapht/wiki/Projects-Using-JGraphT) us how you are using JGraphT, and [cite](https://github.com/jgrapht/jgrapht/wiki/How-to-cite-JGraphT) the usage of JGraphT in your book, paper, website, or technical report. +To help us understand how you use JGraphT, and which features are important to you, [tell](https://github.com/jgrapht/jgrapht/wiki/Users:-Projects-Using-JGraphT) us how you are using JGraphT, and [cite](https://github.com/jgrapht/jgrapht/wiki/Users:-How-to-cite-JGraphT) the usage of JGraphT in your book, paper, website, or technical report. ## Using via Maven @@ -145,34 +145,34 @@ A local copy of the Javadoc HTML files is included in the distribution. The late ## Dependencies - JGraphT requires JDK 11 or later to build starting with version 1.5.0. -- [JHeaps](http://www.jheaps.org/) is a library with priority queues. JHeaps is licensed under the terms of the Apache License, Version 2.0. -- [JUnit](http://www.junit.org) is a unit testing framework. You need JUnit only if you want to run the unit tests. JUnit is licensed under the terms of the IBM Common Public License. The JUnit tests included with JGraphT have been created using JUnit 5. -- [XMLUnit](http://xmlunit.sourceforge.net) extends JUnit with XML capabilities. You need XMLUnit only if you want to run the unit tests. XMLUnit is licensed under the terms of the BSD License. +- [JHeaps](https://www.jheaps.org/) is a library with priority queues. JHeaps is licensed under the terms of the Apache License, Version 2.0. +- [JUnit](https://www.junit.org) is a unit testing framework. You need JUnit only if you want to run the unit tests. JUnit is licensed under the terms of the Eclipse Public License - v 2.0. The JUnit tests included with JGraphT have been created using JUnit 5. +- [XMLUnit](https://www.xmlunit.org/) extends JUnit with XML capabilities. You need XMLUnit only if you want to run the unit tests. XMLUnit is licensed under the terms of the BSD License. - [JGraphX](https://github.com/jgraph/jgraphx) is a graph visualizations and editing component (the successor to the older JGraph library). You need JGraphX only if you want to use the JGraphXAdapter to visualize the JGraphT graph interactively via JGraphX. JGraphX is licensed under the terms of the BSD license. -- [ANTLR](http://www.antlr.org) is a parser generator. It is used for reading text files containing graph representations, and is only required by the jgrapht-io module. ANTLR v4 is licensed under the terms of the [BSD license](http://www.antlr.org/license.html). -- [Guava](https://github.com/google/guava) is Google's core libraries for Java. You need Guava only if you are already using Guava's graph data-structures and wish to use our adapter classes in order to execute JGraphT's algorithms. Only required by the jgrapht-guava module. -- [Apache Commons Proper](http://commons.apache.org/components.html) is an Apache project containing reusable Java components. The packages [commons-text](https://commons.apache.org/proper/commons-text/) and [commons-lang3.](http://commons.apache.org/proper/commons-lang/) which provide additional utilities for String manipulation are only required by the jgrapht-io module. The package [commons-math](https://commons.apache.org/proper/commons-text/) is only required by the jgrapht-unimi-dsi module. +- [ANTLR](https://www.antlr.org) is a parser generator. It is used for reading text files containing graph representations, and is only required by the jgrapht-io module. ANTLR v4 is licensed under the terms of the [BSD license](https://www.antlr.org/license.html). +- [Guava](https://github.com/google/guava) is Google's core libraries for Java. You need Guava only if you are already using Guava's graph data-structures and wish to use our adapter classes in order to execute JGraphT's algorithms. Only required by the [jgrapht-guava](jgrapht-guava) module. +- [Apache Commons Proper](https://commons.apache.org/components.html) is an Apache project containing reusable Java components. The packages [commons-text](https://commons.apache.org/proper/commons-text/) and [commons-lang3.](https://commons.apache.org/proper/commons-lang/) which provide additional utilities for String manipulation are only required by the jgrapht-io module. The package [commons-math](https://commons.apache.org/proper/commons-text/) is only required by the jgrapht-unimi-dsi module. - [fastutil](http://fastutil.di.unimi.it/) provides a collection of type-specific maps, sets, lists and queues with a small memory footprint and fast access and insertion. Fastutil is only required by the jgrapht-opt module. -- [webgraph](http://webgraph.di.unimi.it/) provides a framework for graph compression enabling management of very large graphs. Webgraph is only required by the jgrapht-unimi-dsi module. -- [sux4j](http://sux.di.unimi.it/) provides implementations of basic succinct data structures. Sux4j is only required by the jgrapht-unimi-dsi module. -- [jsap](http://www.martiansoftware.com/jsap/) provides a simple argument parser. Jsap is only required by the jgrapht-unimi-dsi module. -- [apfloat](http://www.apfloat.org/apfloat_java/) provides support for high performance arbitrary precision arithmetic. Apfloat is licensed under the terms of the MIT license. +- [webgraph](https://webgraph.di.unimi.it/) provides a framework for graph compression enabling management of very large graphs. Webgraph is only required by the jgrapht-unimi-dsi module. +- [sux4j](https://sux.di.unimi.it/) provides implementations of basic succinct data structures. Sux4j is only required by the jgrapht-unimi-dsi module. +- [jsap](https://www.martiansoftware.com/jsap/) provides a simple argument parser. Jsap is only required by the jgrapht-unimi-dsi module. +- [apfloat](https://www.apfloat.org/apfloat_java/) provides support for high performance arbitrary precision arithmetic. Apfloat is licensed under the terms of the MIT license. ## Online Resources -The JGraphT website is at . You can use this site to: +The JGraphT website is at . You can use this site to: - **Obtain the latest version**: latest version and all previous versions of JGraphT are available online. - **Report bugs**: if you have any comments, suggestions or bugs you want to report. - **Get support**: if you have questions or need help with JGraphT. -There is also a [wiki](https://github.com/jgrapht/jgrapht/wiki) set up for everyone in the JGraphT community to share information about the project. For support, refer to our [support page](https://github.com/jgrapht/jgrapht/wiki/Getting-Support) +There is also a [wiki](https://github.com/jgrapht/jgrapht/wiki) set up for everyone in the JGraphT community to share information about the project. For support, refer to our [support page](https://github.com/jgrapht/jgrapht/wiki/Users:-Getting-Support) Source code is hosted on [github](https://github.com/jgrapht/jgrapht). You can send contributions as pull requests there. ## Your Improvements -If you add improvements to JGraphT please send them to us as [pull requests on github](https://github.com/jgrapht/jgrapht/wiki/How-to-make-your-first-%28code%29-contribution). We will add them to the next release so that everyone can enjoy them. You might also benefit from it: others may fix bugs in your source files or may continue to enhance them. +If you add improvements to JGraphT please send them to us as [pull requests on github](https://github.com/jgrapht/jgrapht/wiki/Dev-guide:-How-to-make-your-first-(code)-contribution). We will add them to the next release so that everyone can enjoy them. You might also benefit from it: others may fix bugs in your source files or may continue to enhance them. ## Thanks diff --git a/jgrapht-core/src/main/java/module-info.java b/jgrapht-core/src/main/java/module-info.java index 3f91b87f662..52b3453c4fa 100644 --- a/jgrapht-core/src/main/java/module-info.java +++ b/jgrapht-core/src/main/java/module-info.java @@ -1,3 +1,8 @@ +/** + * Defines the core APIs of the JGraphT library. + * + * @since 1.5.0 + */ module org.jgrapht.core { exports org.jgrapht; diff --git a/jgrapht-core/src/main/java/org/jgrapht/Graph.java b/jgrapht-core/src/main/java/org/jgrapht/Graph.java index a79c2b76853..6ea5a7c53c7 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/Graph.java +++ b/jgrapht-core/src/main/java/org/jgrapht/Graph.java @@ -154,9 +154,8 @@ public interface Graph * {@link #getEdgeSupplier()}). For the new edge to be added {@code e} must not be * equal to any other edge the graph (even if the graph allows edge-multiplicity). More * formally, the graph must not contain any edge {@code e2} such that - * {@code e2.equals(e)}. If such {@code - * e2} is found then the newly created edge {@code e} is abandoned, the method leaves - * this graph unchanged and returns {@code null}. + * {@code e2.equals(e)}. If such {@code e2} is found then the newly created edge + * {@code e} is abandoned, the method leaves this graph unchanged and returns {@code null}. * *

* If the underlying graph implementation's {@link #getEdgeSupplier()} returns @@ -166,12 +165,14 @@ public interface Graph * @param sourceVertex source vertex of the edge. * @param targetVertex target vertex of the edge. * - * @return The newly created edge if added to the graph, otherwise {@code - * null}. + * @return The newly created edge if added to the graph, otherwise {@code null}. * - * @throws IllegalArgumentException if source or target vertices are not found in the graph. + * @throws IllegalArgumentException if source or target vertices are not found in the graph + * or if there is a property of this graph that prevents the + * addition of the edge * @throws NullPointerException if any of the specified vertices is {@code null}. * @throws UnsupportedOperationException if the graph was not initialized with an edge supplier + * or if this graph disallows modification * * @see #getEdgeSupplier() */ @@ -179,19 +180,12 @@ public interface Graph /** * Adds the specified edge to this graph, going from the source vertex to the target vertex. - * More formally, adds the specified edge, {@code - * e}, to this graph if this graph contains no edge {@code e2} such that - * {@code e2.equals(e)}. If this graph already contains such an edge, the call leaves this - * graph unchanged and returns {@code false}. Some graphs do not allow edge-multiplicity. - * In such cases, if the graph already contains an edge from the specified source to the - * specified target, then this method does not change the graph and returns {@code - * false}. If the edge was added to the graph, returns {@code - * true}. - * - *

- * The source and target vertices must already be contained in this graph. If they are not found - * in graph IllegalArgumentException is thrown. - *

+ * More formally, adds the specified edge, {@code e}, to this graph if this graph contains + * no edge {@code e2} such that {@code e2.equals(e)}. If this graph already contains such + * an edge, the call leaves this graph unchanged and returns {@code false}. Some graphs + * do not allow edge-multiplicity. In such cases, if the graph already contains an edge + * from the specified source to the specified target, then this method does not change the + * graph and returns {@code false}. If the edge was added to the graph, returns {@code true}. * * @param sourceVertex source vertex of the edge. * @param targetVertex target vertex of the edge. @@ -199,11 +193,13 @@ public interface Graph * * @return {@code true} if this graph did not already contain the specified edge. * - * @throws IllegalArgumentException if source or target vertices are not found in the graph. + * @throws IllegalArgumentException if source or target vertices are not found in the graph + * or if there is a property of this graph that prevents the + * addition of the edge * @throws ClassCastException if the specified edge is not assignment compatible with the class * of edges produced by the edge factory of this graph. - * @throws NullPointerException if any of the specified vertices is {@code - * null}. + * @throws NullPointerException if any of the arguments is {@code null} + * @throws UnsupportedOperationException if this graph disallows modification * * @see #addEdge(Object, Object) * @see #getEdgeSupplier() @@ -217,9 +213,9 @@ public interface Graph * This method creates the new vertex {@code v} using this graph's vertex supplier (see * {@link #getVertexSupplier()}). For the new vertex to be added {@code v} must not * be equal to any other vertex in the graph. More formally, the graph must not contain any - * vertex {@code v2} such that {@code v2.equals(v)}. If such {@code - * v2} is found then the newly created vertex {@code v} is abandoned, the method - * leaves this graph unchanged and throws an {@link IllegalArgumentException}. + * vertex {@code v2} such that {@code v2.equals(v)}. If such {@code v2} is found then + * the newly created vertex {@code v} is abandoned, the method leaves this graph unchanged + * and throws an {@link IllegalArgumentException}. * *

* If the underlying graph implementation's {@link #getVertexSupplier()} returns @@ -237,7 +233,8 @@ public interface Graph * * @throws IllegalArgumentException if the graph supplier returns a vertex which is already in * the graph - * @throws UnsupportedOperationException if the graph was not initialized with a vertex supplier + * @throws UnsupportedOperationException if this graph was not initialized with a vertex supplier + * or if this graph disallows modification * * @see #getVertexSupplier() */ @@ -255,7 +252,9 @@ public interface Graph * * @return {@code true} if this graph did not already contain the specified vertex. * + * @throws IllegalArgumentException if there is a property that disallows adding the specified vertex * @throws NullPointerException if the specified vertex is {@code null}. + * @throws UnsupportedOperationException if this graph disallows modification */ boolean addVertex(V v); @@ -424,7 +423,8 @@ public interface Graph * * @return {@code true} if this graph changed as a result of the call * - * @throws NullPointerException if the specified edge collection is {@code null}. + * @throws NullPointerException if the specified edge collection is {@code null} + * @throws UnsupportedOperationException if this graph disallows modification * * @see #removeEdge(Object) * @see #containsEdge(Object) @@ -442,6 +442,8 @@ public interface Graph * @param targetVertex target vertex of the edge. * * @return the removed edges, or {@code null} if either vertex is not part of graph + * + * @throws UnsupportedOperationException if this graph disallows modification */ Set removeAllEdges(V sourceVertex, V targetVertex); @@ -455,6 +457,7 @@ public interface Graph * @return {@code true} if this graph changed as a result of the call * * @throws NullPointerException if the specified vertex collection is {@code null}. + * @throws UnsupportedOperationException if this graph disallows modification * * @see #removeVertex(Object) * @see #containsVertex(Object) @@ -469,23 +472,26 @@ public interface Graph * @param targetVertex target vertex of the edge. * * @return The removed edge, or {@code null} if no edge removed. + * + * @throws UnsupportedOperationException if this graph disallows modification */ E removeEdge(V sourceVertex, V targetVertex); /** * Removes the specified edge from the graph. Removes the specified edge from this graph if it - * is present. More formally, removes an edge {@code e2} such that {@code e2.equals(e)}, + * is present. More formally, removes an edge {@code e2} such that {@code e2.equals(e)}, * if the graph contains such edge. Returns {@code true} if the graph contained * the specified edge. (The graph will not contain the specified edge once the call returns). * *

- * If the specified edge is {@code null} returns {@code - * false}. + * If the specified edge is {@code null} returns {@code false}. *

* * @param e edge to be removed from this graph, if present. * * @return {@code true} if and only if the graph contained the specified edge. + * + * @throws UnsupportedOperationException if this graph disallows modification */ boolean removeEdge(E e); @@ -505,6 +511,8 @@ public interface Graph * * @return {@code true} if the graph contained the specified vertex; {@code false} * otherwise. + * + * @throws UnsupportedOperationException if this graph disallows modification */ boolean removeVertex(V v); @@ -565,6 +573,8 @@ public interface Graph * * @param e edge of interest * @return edge weight + * + * @throws NullPointerException if argument is {@code null} */ double getEdgeWeight(E e); @@ -573,7 +583,11 @@ public interface Graph * * @param e edge on which to set weight * @param weight new weight for edge + * + * @throws NullPointerException if {@code e} is {@code null} * @throws UnsupportedOperationException if the graph does not support weights + * or if there is a property of this graph that + * disallows modification of the weight */ void setEdgeWeight(E e, double weight); diff --git a/jgrapht-core/src/main/java/org/jgrapht/graph/AbstractBaseGraph.java b/jgrapht-core/src/main/java/org/jgrapht/graph/AbstractBaseGraph.java index fdaa890fd73..b37e2b2f511 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/graph/AbstractBaseGraph.java +++ b/jgrapht-core/src/main/java/org/jgrapht/graph/AbstractBaseGraph.java @@ -217,7 +217,9 @@ public E getEdge(V sourceVertex, V targetVertex) } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public E addEdge(V sourceVertex, V targetVertex) @@ -261,7 +263,8 @@ public E addEdge(V sourceVertex, V targetVertex) } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public boolean addEdge(V sourceVertex, V targetVertex, E e) @@ -301,6 +304,10 @@ public boolean addEdge(V sourceVertex, V targetVertex, E e) } } + /** + * @throws IllegalArgumentException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} + */ @Override public V addVertex() { @@ -318,7 +325,7 @@ public V addVertex() } /** - * {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public boolean addVertex(V v) @@ -411,7 +418,8 @@ public boolean containsVertex(V v) } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public int degreeOf(V vertex) @@ -430,7 +438,8 @@ public Set edgeSet() } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public Set edgesOf(V vertex) @@ -440,7 +449,8 @@ public Set edgesOf(V vertex) } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public int inDegreeOf(V vertex) @@ -450,7 +460,8 @@ public int inDegreeOf(V vertex) } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public Set incomingEdgesOf(V vertex) @@ -460,7 +471,8 @@ public Set incomingEdgesOf(V vertex) } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public int outDegreeOf(V vertex) @@ -470,7 +482,8 @@ public int outDegreeOf(V vertex) } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public Set outgoingEdgesOf(V vertex) @@ -547,7 +560,7 @@ public Set vertexSet() } /** - * {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public double getEdgeWeight(E e) @@ -559,11 +572,8 @@ public double getEdgeWeight(E e) } /** - * Set an edge weight. - * - * @param e the edge - * @param weight the weight - * @throws UnsupportedOperationException if the graph is not weighted + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public void setEdgeWeight(E e, double weight) diff --git a/jgrapht-core/src/main/java/org/jgrapht/graph/AbstractGraph.java b/jgrapht-core/src/main/java/org/jgrapht/graph/AbstractGraph.java index 012ba1639a9..c064dabccb6 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/graph/AbstractGraph.java +++ b/jgrapht-core/src/main/java/org/jgrapht/graph/AbstractGraph.java @@ -53,7 +53,8 @@ public boolean containsEdge(V sourceVertex, V targetVertex) } /** - * @see Graph#removeAllEdges(Collection) + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public boolean removeAllEdges(Collection edges) @@ -68,7 +69,7 @@ public boolean removeAllEdges(Collection edges) } /** - * @see Graph#removeAllEdges(Object, Object) + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public Set removeAllEdges(V sourceVertex, V targetVertex) @@ -83,7 +84,8 @@ public Set removeAllEdges(V sourceVertex, V targetVertex) } /** - * @see Graph#removeAllVertices(Collection) + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public boolean removeAllVertices(Collection vertices) @@ -139,6 +141,9 @@ protected boolean assertVertexExist(V v) * @param edges edges to be removed from this graph. * * @return {@code true} if this graph changed as a result of the call. + * + * @throws NullPointerException if argument is {@code null} + * @throws UnsupportedOperationException if this graph disallows modification * * @see Graph#removeEdge(Object) * @see Graph#containsEdge(Object) diff --git a/jgrapht-core/src/main/java/org/jgrapht/graph/AsGraphUnion.java b/jgrapht-core/src/main/java/org/jgrapht/graph/AsGraphUnion.java index 52356096718..d8363feb296 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/graph/AsGraphUnion.java +++ b/jgrapht-core/src/main/java/org/jgrapht/graph/AsGraphUnion.java @@ -59,6 +59,8 @@ public class AsGraphUnion * @param g1 the first graph * @param g2 the second graph * @param operator the weight combiner (policy for edge weight calculation) + * + * @throws NullPointerException if any of the arguments is {@code null} */ public AsGraphUnion(Graph g1, Graph g2, WeightCombiner operator) { @@ -93,6 +95,8 @@ public AsGraphUnion(Graph g1, Graph g2, WeightCombiner operator) * * @param g1 the first graph * @param g2 the second graph + * + * @throws NullPointerException if any of the arguments is {@code null} */ public AsGraphUnion(Graph g1, Graph g2) { diff --git a/jgrapht-core/src/main/java/org/jgrapht/graph/AsSubgraph.java b/jgrapht-core/src/main/java/org/jgrapht/graph/AsSubgraph.java index 7c48b92459a..cfb2044ac41 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/graph/AsSubgraph.java +++ b/jgrapht-core/src/main/java/org/jgrapht/graph/AsSubgraph.java @@ -267,6 +267,9 @@ public boolean addEdge(V sourceVertex, V targetVertex, E e) return edgeSet.add(e); } + /** + * @throws UnsupportedOperationException always + */ @Override public V addVertex() { @@ -280,7 +283,7 @@ public V addVertex() * * @return {@code true} if the vertex was added, otherwise {@code false}. * - * @throws NullPointerException if v is {@code null} + * @throws NullPointerException {@inheritDoc} * @throws IllegalArgumentException if the base graph does not contain the vertex * * @see AsSubgraph diff --git a/jgrapht-core/src/main/java/org/jgrapht/graph/AsUnmodifiableGraph.java b/jgrapht-core/src/main/java/org/jgrapht/graph/AsUnmodifiableGraph.java index 180a93ef82b..fb4ee011784 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/graph/AsUnmodifiableGraph.java +++ b/jgrapht-core/src/main/java/org/jgrapht/graph/AsUnmodifiableGraph.java @@ -50,7 +50,9 @@ public class AsUnmodifiableGraph /** * Creates a new unmodifiable graph based on the specified backing graph. * - * @param g the backing graph on which an unmodifiable graph is to be created. + * @param g the backing graph on which an unmodifiable graph is to be created + * + * @throws NullPointerException if argument is {@code null} */ public AsUnmodifiableGraph(Graph g) { @@ -58,7 +60,7 @@ public AsUnmodifiableGraph(Graph g) } /** - * @see Graph#addEdge(Object, Object) + * @throws UnsupportedOperationException always */ @Override public E addEdge(V sourceVertex, V targetVertex) @@ -67,7 +69,7 @@ public E addEdge(V sourceVertex, V targetVertex) } /** - * @see Graph#addEdge(Object, Object, Object) + * @throws UnsupportedOperationException always */ @Override public boolean addEdge(V sourceVertex, V targetVertex, E e) @@ -76,7 +78,7 @@ public boolean addEdge(V sourceVertex, V targetVertex, E e) } /** - * @see Graph#addVertex() + * @throws UnsupportedOperationException always */ @Override public V addVertex() @@ -85,7 +87,7 @@ public V addVertex() } /** - * @see Graph#addVertex(Object) + * @throws UnsupportedOperationException always */ @Override public boolean addVertex(V v) @@ -94,7 +96,7 @@ public boolean addVertex(V v) } /** - * @see Graph#removeAllEdges(Collection) + * @throws UnsupportedOperationException always */ @Override public boolean removeAllEdges(Collection edges) @@ -103,7 +105,7 @@ public boolean removeAllEdges(Collection edges) } /** - * @see Graph#removeAllEdges(Object, Object) + * @throws UnsupportedOperationException always */ @Override public Set removeAllEdges(V sourceVertex, V targetVertex) @@ -112,7 +114,7 @@ public Set removeAllEdges(V sourceVertex, V targetVertex) } /** - * @see Graph#removeAllVertices(Collection) + * @throws UnsupportedOperationException always */ @Override public boolean removeAllVertices(Collection vertices) @@ -121,7 +123,7 @@ public boolean removeAllVertices(Collection vertices) } /** - * @see Graph#removeEdge(Object) + * @throws UnsupportedOperationException always */ @Override public boolean removeEdge(E e) @@ -130,7 +132,7 @@ public boolean removeEdge(E e) } /** - * @see Graph#removeEdge(Object, Object) + * @throws UnsupportedOperationException always */ @Override public E removeEdge(V sourceVertex, V targetVertex) @@ -139,7 +141,7 @@ public E removeEdge(V sourceVertex, V targetVertex) } /** - * @see Graph#removeVertex(Object) + * @throws UnsupportedOperationException always */ @Override public boolean removeVertex(V v) diff --git a/jgrapht-core/src/main/java/org/jgrapht/graph/AsUnweightedGraph.java b/jgrapht-core/src/main/java/org/jgrapht/graph/AsUnweightedGraph.java index 443512ba8c3..77123612866 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/graph/AsUnweightedGraph.java +++ b/jgrapht-core/src/main/java/org/jgrapht/graph/AsUnweightedGraph.java @@ -62,6 +62,9 @@ public double getEdgeWeight(E e) return Graph.DEFAULT_EDGE_WEIGHT; } + /** + * @throws UnsupportedOperationException always + */ @Override public void setEdgeWeight(E e, double weight) { diff --git a/jgrapht-core/src/main/java/org/jgrapht/graph/AsWeightedGraph.java b/jgrapht-core/src/main/java/org/jgrapht/graph/AsWeightedGraph.java index c7d24b84653..e955f18fd37 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/graph/AsWeightedGraph.java +++ b/jgrapht-core/src/main/java/org/jgrapht/graph/AsWeightedGraph.java @@ -70,7 +70,8 @@ public class AsWeightedGraph * * @param graph the backing graph over which a weighted view is to be created. * @param weights the map containing the edge weights. - * @throws NullPointerException if the graph or the weights are null. + * + * @throws NullPointerException if either one of the arguments is {@code null} */ public AsWeightedGraph(Graph graph, Map weights) { @@ -85,7 +86,8 @@ public AsWeightedGraph(Graph graph, Map weights) * @param weights the map containing the edge weights * @param writeWeightsThrough if set to true, the weights will get propagated to the backing * graph in the {@code setEdgeWeight()} method. - * @throws NullPointerException if the graph or the weights are null + * + * @throws NullPointerException if either one of {@code graph} or {@code weight} is {@code null} * @throws IllegalArgumentException if {@code writeWeightsThrough} is set to true and * {@code graph} is not a weighted graph */ @@ -119,7 +121,8 @@ public AsWeightedGraph(Graph graph, Map weights, boolean writeW * weight function * @param writeWeightsThrough if set to {@code true}, the weight set directly by * the {@link #setEdgeWeight(Object, double)} method will be propagated to the backing graph. - * @throws NullPointerException if the graph or the weight function is {@code null} + * + * @throws NullPointerException if either one of {@code graph} or {@code weightFunction} is {@code null} * @throws IllegalArgumentException if {@code writeWeightsThrough} is set to true and * {@code graph} is not a weighted graph */ @@ -149,7 +152,8 @@ public AsWeightedGraph( * * @param e edge of interest * @return the edge weight - * @throws NullPointerException if the edge is {@code null} + * + * @throws NullPointerException {@inheritDoc} */ @Override public double getEdgeWeight(E e) @@ -180,7 +184,9 @@ public double getEdgeWeight(E e) * * @param e edge on which to set weight * @param weight new weight for edge - * @throws NullPointerException if the edge is null + * + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException if a weight function is used and caching is disabled */ @Override public void setEdgeWeight(E e, double weight) diff --git a/jgrapht-core/src/main/java/org/jgrapht/graph/GraphDelegator.java b/jgrapht-core/src/main/java/org/jgrapht/graph/GraphDelegator.java index 3d298a3561e..fe4cccb8b65 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/graph/GraphDelegator.java +++ b/jgrapht-core/src/main/java/org/jgrapht/graph/GraphDelegator.java @@ -73,6 +73,8 @@ public GraphDelegator(Graph graph) * backing graph vertex supplier will be used. * @param edgeSupplier edge supplier for the delegator. Can be null in which case the backing * graph edge supplier will be used. + * + * @throws NullPointerException if {@code graph} is {@code null} */ public GraphDelegator(Graph graph, Supplier vertexSupplier, Supplier edgeSupplier) { @@ -134,7 +136,10 @@ public E getEdge(V sourceVertex, V targetVertex) } /** - * {@inheritDoc} + * @throws ClassCastException {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public E addEdge(V sourceVertex, V targetVertex) @@ -150,7 +155,10 @@ public E addEdge(V sourceVertex, V targetVertex) } /** - * {@inheritDoc} + * @throws ClassCastException {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public boolean addEdge(V sourceVertex, V targetVertex, E e) @@ -159,7 +167,8 @@ public boolean addEdge(V sourceVertex, V targetVertex, E e) } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public V addVertex() @@ -175,7 +184,9 @@ public V addVertex() } /** - * {@inheritDoc} + * @throws IllegalArgumentException {@inheritDoc} + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public boolean addVertex(V v) @@ -267,7 +278,7 @@ public Set outgoingEdgesOf(V vertex) } /** - * {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public boolean removeEdge(E e) @@ -276,7 +287,7 @@ public boolean removeEdge(E e) } /** - * {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public E removeEdge(V sourceVertex, V targetVertex) @@ -285,7 +296,7 @@ public E removeEdge(V sourceVertex, V targetVertex) } /** - * {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public boolean removeVertex(V v) @@ -330,7 +341,7 @@ public V getEdgeTarget(E e) } /** - * {@inheritDoc} + * @throws NullPointerException {@inheritDoc} */ @Override public double getEdgeWeight(E e) @@ -339,7 +350,8 @@ public double getEdgeWeight(E e) } /** - * {@inheritDoc} + * @throws NullPointerException {@inheritDoc} + * @throws UnsupportedOperationException {@inheritDoc} */ @Override public void setEdgeWeight(E e, double weight) diff --git a/jgrapht-core/src/main/java/org/jgrapht/util/ArrayUtil.java b/jgrapht-core/src/main/java/org/jgrapht/util/ArrayUtil.java index 9a4eb49f089..fbdc767372a 100644 --- a/jgrapht-core/src/main/java/org/jgrapht/util/ArrayUtil.java +++ b/jgrapht-core/src/main/java/org/jgrapht/util/ArrayUtil.java @@ -36,6 +36,9 @@ private ArrayUtil() * @param arr the array * @param from the index of the first element (inclusive) inside the range to reverse * @param to the index of the last element (inclusive) inside the range to reverse + * + * @throws NullPointerException if {@code arr == null} + * @throws ArrayIndexOutOfBoundsException if either one of {@code from} or {@code to} is out of bounds */ public static final void reverse(V[] arr, int from, int to) { @@ -50,6 +53,9 @@ public static final void reverse(V[] arr, int from, int to) * @param arr the array * @param from the index of the first element (inclusive) inside the range to reverse * @param to the index of the last element (inclusive) inside the range to reverse + * + * @throws NullPointerException if {@code arr == null} + * @throws ArrayIndexOutOfBoundsException if either one of {@code from} or {@code to} is out of bounds */ public static final void reverse(int[] arr, int from, int to) { @@ -67,6 +73,9 @@ public static final void reverse(int[] arr, int from, int to) * @param arr the array * @param i the index of the first element * @param j the index of the second element + * + * @throws NullPointerException if {@code arr == null} + * @throws ArrayIndexOutOfBoundsException if either one of {@code i} or {@code j} is out of bounds */ public static final void swap(V[] arr, int i, int j) { @@ -82,6 +91,9 @@ public static final void swap(V[] arr, int i, int j) * @param i the index of the first element * @param j the index of the second element * + * @throws NullPointerException if {@code arr == null} + * @throws ArrayIndexOutOfBoundsException if either one of {@code i} or {@code j} is out of bounds + * * @since 1.5.3 */ public static void swap(double[] arr, int i, int j) @@ -98,6 +110,9 @@ public static void swap(double[] arr, int i, int j) * @param i the index of the first element * @param j the index of the second element * + * @throws NullPointerException if {@code arr == null} + * @throws ArrayIndexOutOfBoundsException if either one of {@code i} or {@code j} is out of bounds + * * @since 1.5.3 */ public static void swap(int[] arr, int i, int j) diff --git a/jgrapht-demo/src/main/java/module-info.java b/jgrapht-demo/src/main/java/module-info.java index 9b2e91c477d..cc4d9a8ef91 100644 --- a/jgrapht-demo/src/main/java/module-info.java +++ b/jgrapht-demo/src/main/java/module-info.java @@ -1,3 +1,8 @@ +/** + * Provides demo applications of the JGraphT library. + * + * @since 1.5.0 + */ module org.jgrapht.demo { exports org.jgrapht.demo; diff --git a/jgrapht-ext/src/main/java/module-info.java b/jgrapht-ext/src/main/java/module-info.java index 13bb7a6cb3d..7b911f91a73 100644 --- a/jgrapht-ext/src/main/java/module-info.java +++ b/jgrapht-ext/src/main/java/module-info.java @@ -1,3 +1,9 @@ +/** + * Provides adaptors for the JGraphT graphs to be used + * with external libraries. + * + * @since 1.5.0 + */ module org.jgrapht.ext { exports org.jgrapht.ext; diff --git a/jgrapht-guava/src/main/java/module-info.java b/jgrapht-guava/src/main/java/module-info.java index 947e8c2c579..463d92fa3ad 100644 --- a/jgrapht-guava/src/main/java/module-info.java +++ b/jgrapht-guava/src/main/java/module-info.java @@ -1,3 +1,9 @@ +/** + * Provides adaptors for the Google Guava graphs to be used with the + * JGraphT library. + * + * @since 1.5.0 + */ module org.jgrapht.guava { exports org.jgrapht.graph.guava; diff --git a/jgrapht-io/src/main/java/module-info.java b/jgrapht-io/src/main/java/module-info.java index e5ff1ea87b8..f31bc6bcd5c 100644 --- a/jgrapht-io/src/main/java/module-info.java +++ b/jgrapht-io/src/main/java/module-info.java @@ -1,3 +1,8 @@ +/** + * Provides I/O extensions for the JGraphT library. + * + * @since 1.5.0 + */ module org.jgrapht.io { exports org.jgrapht.nio; diff --git a/jgrapht-opt/src/main/java/module-info.java b/jgrapht-opt/src/main/java/module-info.java index 88d6e7abdc7..d997ae5867f 100644 --- a/jgrapht-opt/src/main/java/module-info.java +++ b/jgrapht-opt/src/main/java/module-info.java @@ -1,3 +1,8 @@ +/** + * Provides specialized graph implementations. + * + * @since 1.5.0 + */ module org.jgrapht.opt { exports org.jgrapht.opt.graph.fastutil; diff --git a/jgrapht-unimi-dsi/src/main/java/module-info.java b/jgrapht-unimi-dsi/src/main/java/module-info.java index 692cbe60922..41f49bcc0db 100644 --- a/jgrapht-unimi-dsi/src/main/java/module-info.java +++ b/jgrapht-unimi-dsi/src/main/java/module-info.java @@ -1,10 +1,15 @@ +/** + * Provides graph implementations using succinct data structures. + * + * @since 1.5.1 + */ module org.jgrapht.unimi.dsi { exports org.jgrapht.webgraph; - exports org.jgrapht.sux4j; + exports org.jgrapht.sux4j; requires transitive org.jgrapht.core; - requires transitive org.jgrapht.opt; + requires transitive org.jgrapht.opt; requires transitive it.unimi.dsi.fastutil; requires transitive it.unimi.dsi.webgraph; requires transitive it.unimi.dsi.big.webgraph;