Hamcrest 4.0 Draft

.github/workflows/build.yml

@@ -14,17 +14,17 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        java: [ 8 ]
+        java: [ 17 ]
         experimental: [false]
         include:
-          - java: 17
+          - java: 21
             experimental: true
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - name: Set up JDK ${{ matrix.java }}
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           java-version: ${{ matrix.java }}
           distribution: 'temurin'

CHANGES.md

@@ -1,27 +1,34 @@
 # Hamcrest Changes
 
-## Version 3.1 (Unreleased)
+## Version 4.0 (Unreleased)
 
 ### Breaking Changes
 
+* The baseline version of Java required for Hamcrest 4.0 has been moved to Java 17. Developers who use Java 8-16 can still depend upon hamcrest-3.0.jar.
 * As a result of the bugfix to allow matching against polymorphic collections
 ([PR #422](https://github.com/hamcrest/JavaHamcrest/pull/422)), the signature of the
 `hasItem` and `hasItems` methods has changed. Code relying on the exact signature of
 these methods will need to be updated. The following methods are affected:
-  * `org.hamcrest.CoreMatchers.hasItem`
-  * `org.hamcrest.CoreMatchers.hasItems`
-  * `org.hamcrest.Matchers.hasItem`
-  * `org.hamcrest.Matchers.hasItems`
-  * `org.hamcrest.core.IsCollectionContaining.hasItem`
-  * `org.hamcrest.core.IsCollectionContaining.hasItems`
-  * `org.hamcrest.core.IsIterableContaining.hasItem`
-  * `org.hamcrest.core.IsIterableContaining.hasItems`
-  * TODO: decide if these breaking changes should trigger a major version upgrade (i.e v4.0)
+    * `org.hamcrest.CoreMatchers.hasItem`
+    * `org.hamcrest.CoreMatchers.hasItems`
+    * `org.hamcrest.Matchers.hasItem`
+    * `org.hamcrest.Matchers.hasItems`
+    * `org.hamcrest.core.IsCollectionContaining.hasItem`
+    * `org.hamcrest.core.IsCollectionContaining.hasItems`
+    * `org.hamcrest.core.IsIterableContaining.hasItem`
+    * `org.hamcrest.core.IsIterableContaining.hasItems`
 
 ### New Features
 
-* Optional matchers ([PR #421](https://github.com/hamcrest/JavaHamcrest/pull/421))
-* Matchers for thrown exceptions ([PR #423](https://github.com/hamcrest/JavaHamcrest/pull/423))
+* Optional matchers `emptyOptional()`, `optionalWithValue()` available in `org.hamcrest.Matchers` ([PR #421](https://github.com/hamcrest/JavaHamcrest/pull/421))
+* Matchers for thrown exceptions available through `throwsException()` in `org.hamcrest.Matchers` ([PR #423](https://github.com/hamcrest/JavaHamcrest/pull/423))
+* New `org.hamcrest.io.PathMatchers` class for matching `java.nio.files.Path` objects ([PR #442](https://github.com/hamcrest/JavaHamcrest/pull/442))
+* Create custom matchers more succinctly using `matcher()` static factory methods on `FeatureMatcher` and `TypeSafeDiagnosingMatcher` ([PR #441](https://github.com/hamcrest/JavaHamcrest/pull/441))
+* `org.hamcrest.beans` property matchers now support Java record naming conventions in addition to bean naming conventions ([PR #429](https://github.com/hamcrest/JavaHamcrest/pull/429))
+* `IsIterableContainingInAnyOrder.containsInAnyOrder()` matcher now supports custom `Comparator`s ([PR #404](https://github.com/hamcrest/JavaHamcrest/pull/404))
+* New `IsIterableContainingParallelRuns.containsParallelRunsOf()` matcher is a more general implementation of `containsInRelativeOrder()` ([PR #383](https://github.com/hamcrest/JavaHamcrest/pull/383))
+* New `IsUnmodifiable.isUnmodifiableCollection` matcher for testing if a collection is unmodifiable. ([PR #381](https://github.com/hamcrest/JavaHamcrest/pull/381))([PR #379](https://github.com/hamcrest/JavaHamcrest/pull/379))
+* New matchers for testing the content of files in `org.hamcrest.io.FileMatchers` and `org.hamcrest.io.PathMatchers` ([PR #345](https://github.com/hamcrest/JavaHamcrest/pull/345))
 
 ### Improvements
 

build.gradle

@@ -19,13 +19,14 @@ tasks.register("showVersion") {
 subprojects {
     apply plugin: 'checkstyle'
     apply plugin: 'java-library'
+	apply plugin: "eclipse"
 
     group = rootProject.group
     version = rootProject.version
 
     java {
-        sourceCompatibility = JavaVersion.VERSION_1_8
-        targetCompatibility = JavaVersion.VERSION_1_8
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
     }
 
     repositories {

docs/javadoc/4.0/allpackages-index.html

@@ -0,0 +1,112 @@
+<!DOCTYPE HTML>
+<html lang="en">
+<head>
+<!-- Generated by javadoc (23) -->
+<title>All Packages (Hamcrest 4.0 API)</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<meta name="description" content="package index">
+<meta name="generator" content="javadoc/AllPackagesIndexWriter">
+<link rel="stylesheet" type="text/css" href="resource-files/jquery-ui.min.css" title="Style">
+<link rel="stylesheet" type="text/css" href="resource-files/stylesheet.css" title="Style">
+<script type="text/javascript" src="script-files/script.js"></script>
+<script type="text/javascript" src="script-files/jquery-3.7.1.min.js"></script>
+<script type="text/javascript" src="script-files/jquery-ui.min.js"></script>
+</head>
+<body class="all-packages-index-page">
+<script type="text/javascript">const pathtoroot = "./";
+loadScripts(document, 'script');</script>
+<noscript>
+<div>JavaScript is disabled on your browser.</div>
+</noscript>
+<header role="banner">
+<nav role="navigation">
+<!-- ========= START OF TOP NAVBAR ======= -->
+<div class="top-nav" id="navbar-top">
+<div class="nav-content">
+<div class="nav-menu-button"><button id="navbar-toggle-button" aria-controls="navbar-top" aria-expanded="false" aria-label="Toggle navigation links"><span class="nav-bar-toggle-icon">&nbsp;</span><span class="nav-bar-toggle-icon">&nbsp;</span><span class="nav-bar-toggle-icon">&nbsp;</span></button></div>
+<div class="skip-nav"><a href="#skip-navbar-top" title="Skip navigation links">Skip navigation links</a></div>
+<ul id="navbar-top-firstrow" class="nav-list" title="Navigation">
+<li><a href="index.html">Overview</a></li>
+<li><a href="overview-tree.html">Tree</a></li>
+<li><a href="deprecated-list.html">Deprecated</a></li>
+<li><a href="index-all.html">Index</a></li>
+<li><a href="search.html">Search</a></li>
+<li><a href="help-doc.html#all-packages">Help</a></li>
+</ul>
+</div>
+</div>
+<div class="sub-nav">
+<div class="nav-content">
+<ol class="sub-nav-list"></ol>
+<div class="nav-list-search">
+<input type="text" id="search-input" disabled placeholder="Search" aria-label="Search in documentation" autocomplete="off">
+<input type="reset" id="reset-search" disabled value="Reset">
+</div>
+</div>
+</div>
+<!-- ========= END OF TOP NAVBAR ========= -->
+<span class="skip-nav" id="skip-navbar-top"></span></nav>
+</header>
+<div class="main-grid">
+<main role="main">
+<div class="header">
+<h1 title="All&amp;nbsp;Packages" class="title">All&nbsp;Packages</h1>
+</div>
+<div class="caption"><span>Package Summary</span></div>
+<div class="summary-table two-column-summary">
+<div class="table-header col-first">Package</div>
+<div class="table-header col-last">Description</div>
+<div class="col-first even-row-color"><a href="org/hamcrest/package-summary.html">org.hamcrest</a></div>
+<div class="col-last even-row-color">
+<div class="block">Top level matcher classes and interfaces.</div>
+</div>
+<div class="col-first odd-row-color"><a href="org/hamcrest/beans/package-summary.html">org.hamcrest.beans</a></div>
+<div class="col-last odd-row-color">
+<div class="block">Matchers of Java Bean properties and their values.</div>
+</div>
+<div class="col-first even-row-color"><a href="org/hamcrest/collection/package-summary.html">org.hamcrest.collection</a></div>
+<div class="col-last even-row-color">
+<div class="block">Matchers of arrays and collections.</div>
+</div>
+<div class="col-first odd-row-color"><a href="org/hamcrest/comparator/package-summary.html">org.hamcrest.comparator</a></div>
+<div class="col-last odd-row-color">
+<div class="block">Helper classes for building matcher comparators.</div>
+</div>
+<div class="col-first even-row-color"><a href="org/hamcrest/core/package-summary.html">org.hamcrest.core</a></div>
+<div class="col-last even-row-color">
+<div class="block">Fundamental matchers of objects and values, and composite matchers.</div>
+</div>
+<div class="col-first odd-row-color"><a href="org/hamcrest/exception/package-summary.html">org.hamcrest.exception</a></div>
+<div class="col-last odd-row-color">
+<div class="block">Matchers of exceptions.</div>
+</div>
+<div class="col-first even-row-color"><a href="org/hamcrest/io/package-summary.html">org.hamcrest.io</a></div>
+<div class="col-last even-row-color">
+<div class="block">Matchers that perform file comparisons.</div>
+</div>
+<div class="col-first odd-row-color"><a href="org/hamcrest/number/package-summary.html">org.hamcrest.number</a></div>
+<div class="col-last odd-row-color">
+<div class="block">Matchers that perform numeric comparisons.</div>
+</div>
+<div class="col-first even-row-color"><a href="org/hamcrest/object/package-summary.html">org.hamcrest.object</a></div>
+<div class="col-last even-row-color">
+<div class="block">Matchers that inspect objects and classes.</div>
+</div>
+<div class="col-first odd-row-color"><a href="org/hamcrest/optional/package-summary.html">org.hamcrest.optional</a></div>
+<div class="col-last odd-row-color">
+<div class="block">Matchers that perform comparisons on <a href="https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/Optional.html" title="class or interface in java.util" class="external-link"><code>Optional</code></a> instances.</div>
+</div>
+<div class="col-first even-row-color"><a href="org/hamcrest/text/package-summary.html">org.hamcrest.text</a></div>
+<div class="col-last even-row-color">
+<div class="block">Matchers that perform text comparisons.</div>
+</div>
+<div class="col-first odd-row-color"><a href="org/hamcrest/xml/package-summary.html">org.hamcrest.xml</a></div>
+<div class="col-last odd-row-color">
+<div class="block">Matchers of XML documents.</div>
+</div>
+</div>
+</main>
+</div>
+</body>
+</html>