Merge remote-tracking branch 'origin/release/1-1-0'

Author: remikey

.gitlab-ci.yml

@@ -39,6 +39,15 @@ run-unit-tests:
   - java -version
   - ./gradlew lib:cleans lib:tests
   artifacts:
+    reports:
+      junit:
+        - lib/jbotsim-core/build/test-results/test/TEST-*.xml
+        - lib/jbotsim-extras-common/build/test-results/test/TEST-*.xml
+        - lib/jbotsim-extras-swing/build/test-results/test/TEST-*.xml
+        - lib/jbotsim-icons/build/test-results/test/TEST-*.xml
+        - lib/jbotsim-ui-common/build/test-results/test/TEST-*.xml
+        - lib/jbotsim-ui-swing/build/test-results/test/TEST-*.xml
+        - lib/jbotsim-serialization-common/build/test-results/test/TEST-*.xml
     paths:
     - lib/jbotsim-core/build/test-results
     - lib/jbotsim-extras-common/build/test-results

.travis.yml

@@ -1,3 +1,4 @@
+dist: trusty
 language: java
 script: ./gradlew lib:cleans lib:jars lib:tests
 jdk:

CHANGELOG.md

@@ -2,12 +2,331 @@
 
 This file lists modifications introduced by each version.
 
-As of version 1.0.0, the project will try and follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
 ## [Unreleased]
 
 * empty
 
+## [1.1.0] - 2019/09/10
+
+### Topology, Node and Link classes modifications
+
+**Links handling clarification:**
+
+[[issue 49]][issue: #49]
+
+* The `Link.Type` enum has been **renamed** as `Link.Orientation`
+* The `Link.DEFAULT_TYPE` enum has been **renamed** into `Link.DEFAULT_ORIENTATION`
+* The `Topology` class is augmented with an instance variable `orientation` that contains the default orientation of 
+the topology
+
+  Accessors/Actuators have been added as `Topology.setOrientation()` and `Topology.getOrientation()`.
+* A new `Topology.isDirected()` helper method has been added
+ 
+  It is a simple test of the value returned by `Topology.getOrientation()`.  
+* Accessors to links `Topology.getLinks()`, `Topology.getLink()` and `Node.getLinks()` now return links whose type is 
+determined with respect to `Topology.getOrientation()`
+* Accessors to links based on a `Boolean` specification of the orientation i.e., `Topology.getLinks(boolean)`, 
+`Topology.getLink(Node,Node,boolean)` and `Node.getLinks(boolean)` are marked **deprecated** and replaced by methods 
+where the `Boolean` is replaced by a `Link.Orientation` parameter
+* The method `Topology.hasDirectedLinks()` is marked as **deprecated**; `Topology.isDirected()` should be used instead
+* The implementation of `Node.getCommonLinkWith()` and `Node.getNeighbors()` is changed to explicitly request undirected 
+links
+* A test suite has been added to check behaviors of `Topology.getLinks()` w.r.t. topology orientation
+
+[issue: #49]: https://github.com/jbotsim/JBotSim/issues/49
+
+
+**Bug fix in Link:**
+
+* Fixed a `NullPointerException` when calling `Link.equals(null)` [[issue 65]][issue: #65]
+
+[issue: #65]: https://github.com/jbotsim/JBotSim/issues/65
+
+###  MessageEngine class modifications
+
+[[issue 58]][issue: #58]
+
+**Fix in MessageEngine:**
+
+* A call to the now **deprecated** `MessageEngine.setSpeed()` (now `MessageEngine.setDelay()`) method does not duplicate
+  messages delivery anymore
+
+**Behavior modifications in MessageEngine:**
+
+* The delay feature from the former `DelayMessageEngine` has finally been integrated in the `MessageEngine`
+
+  Modifying the `MessageEngine`'s delay (`setDelay()`) will only affect messages sent during this round and the 
+  following ones. Already queued messages retain their counters. 
+
+* A message will now be dropped if the link between its sender and destination is broken, while the message is queued
+
+  In order for a message to be delivered, a link from the sender to the destination must be present during each round,
+  while the message is queued. If at some point the `MessageEngine` can't find such a link, the message will be dropped.
+   
+  Note that if `Message.retryMode` is set to `true`, the `MessageEngine` will try requeue it, with a new delay.
+
+* Concurrent messages delivery is now consistent with insertion order 
+
+  When several messages between a sender and a destination are supposed to be delivered during the same round (they 
+  have possibly been queued during different rounds, but with different delays), they will now consistently be delivered
+  according to their queuing order.
+    
+
+**New symbols in MessageEngine:**
+
+* The `MessageEngine.setDelay(int)` and `MessageEngine.getDelay()` have been created
+
+  These methods allow you to control the delay (in rounds) applied before actually trying to deliver a message.
+
+* The `MessageEngine.DELAY_INSTANT` constant has been added
+
+  This constant sets the value of the delay use for the quickest possible delivery.
+
+* The `MessageEngine.DEFAULT_DELAY` constant has been added
+
+  This constant sets the delay's default value. It actually matches `MessageEngine.DELAY_INSTANT`.
+
+* The explicit constructors `MessageEngine(Topology)` and `MessageEngine(Topology, int)` have been created
+
+  * It is thus now mandatory to provide at least a `Topology` when creating a `MessageEngine`.
+  * `MessageEngine.setTopology(Topology)` has however been kept.
+  * No default constructor is available. Please check that your code do not use it (reflection calls included).
+
+**Deprecations in MessageEngine:**
+
+* The `MessageEngine.setSpeed(int)` method has been deprecated
+
+  Please use `MessageEngine.setDelay(int)` instead.
+
+###  DelayMessageEngine/RandomMessageEngine class modifications
+
+[[issue 58]][issue: #58]
+
+Since the base `MessageEngine` now handles the _delay_ feature:
+
+* `DelayMessageEngine` has been renamed to `RandomMessageEngine`
+   
+   `jbotsim-extras-common`/`io.jbotsim.contrib.messaging.DelayMessageEngine` -> `io.jbotsim.contrib.messaging.RandomMessageEngine`
+   
+* The `RandomMessageEngine` inherits from all delay-related improvements in `MessageEngine`:
+  
+  * The delay applied to message delivery is now modifiable during the object's lifecycle
+  * Concurrent messages delivery is now consistent with insertion order
+  * A broken link leads to message dropping
+  * `Message.retryMode` is now taken into account
+    
+###  AsyncMessageEngine class modifications
+
+[[issue 58]][issue: #58]
+
+**Behavior modifications in AsyncMessageEngine:**
+
+* The _average_ feature is now better handled and documented
+
+  In non-FIFO cases, the delay is drawn randomly according to an exponential law with average value 
+    `AsyncMessageEngine.getAverageDuration()`.
+    
+  In FIFO cases, the theoretical random delay is drawn the same way as for non-FIFO cases, but also taking care that the 
+  new message won't be delivered before a pre-existing one.
+
+
+**New symbols in AsyncMessageEngine:**
+
+* The `AsyncMessageEngine.setAverageDuration(int)` and `AsyncMessageEngine.getAverageDuration()` have been created
+
+  These methods allow you to control the delay (in rounds) applied before actually trying to deliver a message.
+
+* The `AsyncMessageEngine.DEFAULT_TYPE` constant has been added
+
+  This constant sets the default queue type value: `AsyncMessageEngine.Type.FIFO`.
+
+* The `AsyncMessageEngine.DEFAULT_AVERAGE_DURATION` constant has been added
+
+  This constant sets the desired average delivery duration's default value: `10` rounds.
+  
+* The explicit constructors `AsyncMessageEngine(Topology, double, Type)` and `AsyncMessageEngine(Topology)` have been created
+
+**Removals in AsyncMessageEngine:**
+
+* The explicit constructor `AsyncMessageEngine(double, Type)` has been removed
+
+  Please use  `AsyncMessageEngine(Topology, double, Type)` instead.
+
+[issue: #58]: https://github.com/jbotsim/JBotSim/issues/58
+
+###  JViewer class modifications
+
+**Bug fix in JViewer:**
+
+* Fixed a truncation issue when importing a Topology via the *Load Topology* command [[issue 60]][issue: #60]
+
+[issue: #60]: https://github.com/jbotsim/JBotSim/issues/60
+
+**Behavior modifications in JViewer:**
+
+* The `JViewer` now also detects `.gv` and `.xdot` files as to be handled with the `DotTopologySerializer` [[issue 48]][issue: #48]
+* The `JViewer` now detects `.d6` and `.g6` files as to be handled with the new `Graph6TopologySerializer` [[issue 28]][issue: #28]
+ 
+###  DotTopologySerializer class modifications
+
+[[issue 48]][issue: #48]
+
+**Behavior modifications in DotTopologySerializer:**
+
+* `DotTopologySerializer.exportToString(Topology)` is now implemented (`null` was knowingly returned in the previous 
+  version)
+
+  Amongst other implementation points:
+  * Node positions are output with the `pos = "x, y!"` syntax
+  * The Y-coordinates are exported flipped, to be consistent with `DotTopologySerializer.importFromString()`
+  * The exportation is done without respect to the `scale` member
+
+* By default, the `DotTopologySerializer.importFromString(Topology , String)` does not scale anymore (it formerly 
+  doubled distances).
+     
+  The former behavior can be achieved by either:
+  * using the `DotTopologySerializer(double scale, int margin, boolean reorganize)` constructor or
+  * using `TopologyLayouts.autoscale()`.
+
+**Method symbols in DotTopologySerializer:**
+
+  * `DotTopologySerializer.DEFAULT_SCALE` has been added
+   
+     The previous default scale factor was `2.0`. It is now set to `1.0`. 
+ 
+  * `DotTopologySerializer.DEFAULT_MARGIN` has been added
+   
+     The default value is unchanged: `50`.
+  
+  * `DotTopologySerializer.DOT_FILENAME_EXTENSIONS` has been added
+  
+    This array contains known extensions for DOT files. It currently contains `"gv"`, `"dot"` and  `"xdot"`.
+    Please [prefer][graphviz-gv-extension] the `.gv` extension.
+    
+[graphviz-gv-extension]: https://marc.info/?l=graphviz-devel&m=129418103126092
+[issue: #48]: https://github.com/jbotsim/JBotSim/issues/48
+
+### DotTopologySerializer new parser implementation
+
+[[issue 55]][issue: #55]
+
+* The replacement of the parser removes the dependency to [com.paypal.digraph.digraph-parser](https://github.com/paypal/digraph-parser)
+
+* The new parser has been written from the ANTLR grammar used by digraph-parser package 
+(actually it is the grammar given in "The definitive ANTLR 4 Reference" book by T. Parr)
+ 
+* ANTLR runtime classes are still required to run the parser
+
+* The parser builds a graph structure (`DotGraph`, `DotNode`, `DotEdge`) that is translated into a topology
+
+* The new parser permits to distinguish directed and undirected graphs
+
+[issue: #55]: https://github.com/jbotsim/JBotSim/issues/55
+
+### Graph6 file format support 
+
+[[issue 28]][issue: #28]
+
+* A new serializer `Graph6TopologySerializer` is added to `jbotsim-serialization-common`/`io.jbotsim.io.format.graph6`.
+
+* Extensions `.d6` and `.g6` have been registered in client classes of `TopologySerializerFilenameMatcher`: 
+    * `examples.tools.JBotSimConvert` 
+    * `examples.tools.JBotSimViewer`
+    * `io.jbotsim.ui.JViewer` 
+
+[issue: #28]: https://github.com/jbotsim/JBotSim/issues/28
+
+### TopologySerializerFilenameMatcher
+
+* An helper method has been added in `TopologySerializerFilenameMatcher` that associates a set of filename extensions 
+  with a single `TopologySerializer`
+
+###  Color class modifications
+
+* Some internal fixes have been provided, and unit tests added, to better match AWT's implementation regarding 
+  constructors and the alpha component
+  
+* `Color.getColor()` variants now better match their AWT counter parts
+
+  JBotSim's implementations used to directly consider the provided String as a RGB value, instead of trying to get the 
+  said value from a system property.  
+
+* General documentation effort
+
+### JBackgroundPainter, JLinkPainter, JNodePainter classes modifications
+
+In order to ease behavior modifications by inheritance, `JBackgroundPainter`, `JLinkPainter` and `JNodePainter` have 
+been modified so that they all expose a `protected` variant of:
+* `setColor()`: this method is called by the object when it needs to set the AWT `Color` of the element
+* `setStroke()`: this method is called by the object when it needs to set the AWT `Stroke` used to draw the element
+* `setRenderingHints()`: this method is called by the object when it needs to set the AWT `RenderingHints` used to draw 
+the element
+
+Overriding these methods should be fairly straightforward.
+
+The behaviors associated to each class stay unchanged.
+
+###  JDirectedLinkPainter creation
+
+* `JDirectedLinkPainter` is added to `jbotsim-extras-swing`/`io.jbotsim.ui.painting` [[issue 71]][issue: #71]
+  
+  It provides arrow-tips to directed links. Its implementation uses the reusable  
+  `jbotsim-extras-common`/`io.jbotsim.ui.painting.ArrowTipPathGenerator` class.
+
+[issue: #71]: https://github.com/jbotsim/JBotSim/issues/71
+
+###  TopologyLayouts class modifications
+
+**Method modifications in TopologyLayouts:**
+* `TopologyLayouts.autoscale(Topology)` is now `public` [[issue 51]][issue: #51]
+
+
+**New methods in TopologyLayouts:**
+* `TopologyLayouts.autoscale(Topology, AutoScaleParams)` created [[issue 52]][issue: #52]
+
+  This method allows to control the scaling process more precisely than the previous default, thanks to the 
+  `AutoScaleParams` object.
+  The parameters used with the default method are:
+  * *margin ratios*: `0.1`
+  * *centering*: enabled
+  * *communication ranges scaling*: enabled
+  * *sensing ranges scaling*: enabled
+  
+* `TopologyLayouts.center(Topology)` created [[issue 52]][issue: #52]
+
+  This method centers the content of the `Topology` inside its boundaries (without scaling it).
+  
+* `TopologyBoundaries TopologyLayouts.computeBoundaries(Topology)` created [[issue 52]][issue: #52]
+
+  This method computes the boundaries of a `Topology`. These are represented by `TopologyBoundaries` object, with 
+  minimum and maximum coordinates on 3 axes.
+  
+
+[issue: #51]: https://github.com/jbotsim/JBotSim/issues/51
+[issue: #52]: https://github.com/jbotsim/JBotSim/issues/52
+
+### New icon in the jbotsim-icons module
+
+`jbotsim-icons`/`io.jbotsim.ui.icons`
+
+* A new icon suitable for servers/mainframes has been added [[issue 59]][issue: #59] 
+  * `jbotsim-icons`/`io/jbotsim/ui/icons/server.png` 
+
+  As usual, it's path can be accessed using the corresponding constant `Icons.SERVER`. 
+
+
+[issue: #59]: https://github.com/jbotsim/JBotSim/issues/59
+
+
+### Javadoc modifications 
+
+* Link JSE8 javadoc from javadoc [[issue 62]][issue: #62]
+* Prevent some errors in javadoc compilation by specifying UTF-8 encoding for javac and javadoc [[issue 66]][issue: #66]
+* Also remove some invalid tags (i.e. \<tt\>) from comments [[issue 66]][issue: #66]
+
+[issue: #62]: https://github.com/jbotsim/JBotSim/issues/62
+[issue: #66]: https://github.com/jbotsim/JBotSim/issues/66
+
 ## [1.0.0] - 2019/02/28
 
 This first official version introduces several changes. They are listed here.
@@ -445,5 +764,6 @@ have executed their onStart() method before that, you may simply call start()
 on your topology immediately followed by a call to pause().
 (Eventually we will provide an atomic call to this effect.)
 
-[Unreleased]: https://github.com/acasteigts/JBotSim/compare/v1.0.0...develop
-[1.0.0]: https://github.com/acasteigts/JBotSim/compare/v1.0.0-beta03...v1.0.0
+[Unreleased]: https://github.com/acasteigts/JBotSim/compare/v1.1.0...develop
+[1.1.0]: https://github.com/acasteigts/JBotSim/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/acasteigts/JBotSim/compare/v1.0.0-beta03...v1.0.0

CONTRIBUTING.md

@@ -163,11 +163,12 @@ Here is what happens during a release:
 1. The `release/x-y-z` release branch from `develop` by the release manager when it contains all features for next 
 release (*e.g.* `release/1-0-0`).
    * The `x-y-z` version number is decided upon creation of the release branch. 
-2. All tests, debugging, etc. are done on branch `release/x-y-z`.
+2. The new version number is applied to the project (with the [`bump-version.sh`](bump-version.sh) script).
+3. All tests, debugging, etc. are done on branch `release/x-y-z`.
    * This allows for new features to be merged into `develop` without interfering with the release.
-3. Branch `release/x-y-z` is merged into `master` after version `x-y-z` is officially published on Maven Central.
-4. The merge commit on the `master` branch is tagged `vx.y.z` (*e.g.* `v1.0.0`).
-5. After release, the new content of `master` is merged into `develop`.
+4. Branch `release/x-y-z` is merged into `master` after version `x-y-z` is officially published on Maven Central.
+5. The merge commit on the `master` branch is tagged `vx.y.z` (*e.g.* `v1.0.0`).
+6. After release, the new content of `master` is merged into `develop`.
    * This allows for developers on `develop` to benefit from fixes made during the release.
 
 ## Pull / Merge requests