From 0f9a4eed12e3bb4af31d86484ccac86e22a3a183 Mon Sep 17 00:00:00 2001 From: Mark Raynsford Date: Sat, 4 May 2024 14:55:07 +0000 Subject: [PATCH] Eliminate jstructural Affects: https://github.com/io7m-com/.github/issues/2 --- README.in | 33 ++ README.md | 34 ++ com.io7m.jequality.documentation/pom.xml | 214 ----------- .../src/main/assembly/documentation.xml | 21 -- .../documentation/EDocumentation.java | 52 --- .../jequality/documentation/package-info.java | 22 -- .../src/main/java/module-info.java | 29 -- .../io7m/jequality/documentation/brand.xml | 9 - .../jequality/documentation/documentation.css | 63 ---- .../jequality/documentation/documentation.xml | 349 ------------------ pom.xml | 12 +- src/site/resources/documentation.xml | 7 +- 12 files changed, 74 insertions(+), 771 deletions(-) create mode 100644 README.in delete mode 100644 com.io7m.jequality.documentation/pom.xml delete mode 100644 com.io7m.jequality.documentation/src/main/assembly/documentation.xml delete mode 100644 com.io7m.jequality.documentation/src/main/java/com/io7m/jequality/documentation/EDocumentation.java delete mode 100644 com.io7m.jequality.documentation/src/main/java/com/io7m/jequality/documentation/package-info.java delete mode 100644 com.io7m.jequality.documentation/src/main/java/module-info.java delete mode 100644 com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/brand.xml delete mode 100644 com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/documentation.css delete mode 100644 com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/documentation.xml diff --git a/README.in b/README.in new file mode 100644 index 0000000..02d4e6c --- /dev/null +++ b/README.in @@ -0,0 +1,33 @@ + +## jequality + +The `jequality` package provides functions to compare floating-point numbers, +annotations to mark classes as using specific types of equality, and a validator +for equality methods. + +## Status + +As the Java platform evolves, libraries that may have been necessary in the +past can become unnecessary due to new platform features. If you were already +using `jequality`, then you know what it does and why you were using it. If +you aren't already using `jequality`, then you should not start. + +This package is in maintenance mode and will not see any new functionality. + +Use [equalsverifier](https://jqno.nl/equalsverifier/) as a replacement for +the `jequality` validator. + +Use JDK 17 record types to eliminate a lot of the issues with `equals()` and +`hashCode()`. + +Use JUnit 5 assertions to perform approximate equality checks of floating-point +values in unit tests. Outside of unit tests, find some other way to compare +numbers. + +## Features + +* High coverage test suite. +* Written in pure Java 21. +* [OSGi-ready](https://www.osgi.org/) +* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System) +* ISC license. diff --git a/README.md b/README.md index f3d8017..f5d357d 100644 --- a/README.md +++ b/README.md @@ -13,3 +13,37 @@ jequality | OpenJDK (Temurin) LTS | Linux | [![Build (OpenJDK (Temurin) LTS, Linux)](https://img.shields.io/github/actions/workflow/status/io7m-com/jequality/main.linux.temurin.lts.yml)](https://www.github.com/io7m-com/jequality/actions?query=workflow%3Amain.linux.temurin.lts)| | OpenJDK (Temurin) Current | Windows | [![Build (OpenJDK (Temurin) Current, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/jequality/main.windows.temurin.current.yml)](https://www.github.com/io7m-com/jequality/actions?query=workflow%3Amain.windows.temurin.current)| | OpenJDK (Temurin) LTS | Windows | [![Build (OpenJDK (Temurin) LTS, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/jequality/main.windows.temurin.lts.yml)](https://www.github.com/io7m-com/jequality/actions?query=workflow%3Amain.windows.temurin.lts)| + +## jequality + +The `jequality` package provides functions to compare floating-point numbers, +annotations to mark classes as using specific types of equality, and a validator +for equality methods. + +## Status + +As the Java platform evolves, libraries that may have been necessary in the +past can become unnecessary due to new platform features. If you were already +using `jequality`, then you know what it does and why you were using it. If +you aren't already using `jequality`, then you should not start. + +This package is in maintenance mode and will not see any new functionality. + +Use [equalsverifier](https://jqno.nl/equalsverifier/) as a replacement for +the `jequality` validator. + +Use JDK 17 record types to eliminate a lot of the issues with `equals()` and +`hashCode()`. + +Use JUnit 5 assertions to perform approximate equality checks of floating-point +values in unit tests. Outside of unit tests, find some other way to compare +numbers. + +## Features + +* High coverage test suite. +* Written in pure Java 21. +* [OSGi-ready](https://www.osgi.org/) +* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System) +* ISC license. + diff --git a/com.io7m.jequality.documentation/pom.xml b/com.io7m.jequality.documentation/pom.xml deleted file mode 100644 index fe51b9b..0000000 --- a/com.io7m.jequality.documentation/pom.xml +++ /dev/null @@ -1,214 +0,0 @@ - - - - 4.0.0 - - com.io7m.jequality - com.io7m.jequality - 3.0.1-SNAPSHOT - - com.io7m.jequality.documentation - - jar - com.io7m.jequality.documentation - Equality handling (Documentation) - https://www.io7m.com/software/jequality - - - true - - - - - ${project.groupId} - com.io7m.jequality.core - ${project.version} - - - - org.osgi - org.osgi.annotation.bundle - provided - - - org.osgi - org.osgi.annotation.versioning - provided - - - - com.io7m.primogenitor - com.io7m.primogenitor.support - - - - - - - - org.apache.maven.plugins - maven-resources-plugin - - - copy-documentation-resources - - copy-resources - - generate-resources - - ${project.build.directory}/documentation/ - - - src/main/resources/com/io7m/jequality/documentation/ - true - - - - - - - - - - org.apache.maven.plugins - maven-dependency-plugin - - - unpack-sources - package - - unpack-dependencies - - - module-info.java - ${project.groupId} - sources - false - ${project.build.directory}/javadoc-sources - - - - make-classpath - package - - build-classpath - - - ${project.build.directory}/javadoc-classpath - - - - - - - - com.io7m.jstructural - io7m-jstructural-maven-plugin - - - make-documentation-single - prepare-package - - transform - - - ${project.build.directory}/documentation/documentation.xml - ${project.build.directory}/documentation/ - ${project.build.directory}/documentation/brand.xml - XHTML_SINGLE - - - - make-documentation-multi - prepare-package - - transform - - - ${project.build.directory}/documentation/documentation.xml - ${project.build.directory}/documentation/ - ${project.build.directory}/documentation/brand.xml - XHTML_MULTI - - - - - - - - org.codehaus.mojo - exec-maven-plugin - - - javadoc - - java - - package - - com.io7m.primogenitor.support.TrivialJavadoc - - ${project.build.directory}/javadoc-sources - ${project.build.directory}/javadoc-classpath - ${project.build.directory}/documentation/apidocs - ${project.build.directory}/javadoc-log.txt - ${project.build.directory}/javadoc-options - - - - - - - - - org.apache.maven.plugins - maven-assembly-plugin - - - src/main/assembly/documentation.xml - - - - - make-assembly - package - - single - - - false - - - - - - - - - org.codehaus.mojo - truezip-maven-plugin - false - - - copy-site-documentation - - copy - - site - - true - - ${project.build.directory}/${project.name}-${project.version}.zip/${project.name}-${project.version}/ - ${project.parent.build.directory}/minisite/documentation/ - - - - - - - - - diff --git a/com.io7m.jequality.documentation/src/main/assembly/documentation.xml b/com.io7m.jequality.documentation/src/main/assembly/documentation.xml deleted file mode 100644 index 0b5d459..0000000 --- a/com.io7m.jequality.documentation/src/main/assembly/documentation.xml +++ /dev/null @@ -1,21 +0,0 @@ - - documentation - ${project.name}-${project.version} - - zip - - - - ${project.build.directory}/documentation - / - - - ${project.build.directory}/site/apidocs - /apidocs - - - - diff --git a/com.io7m.jequality.documentation/src/main/java/com/io7m/jequality/documentation/EDocumentation.java b/com.io7m.jequality.documentation/src/main/java/com/io7m/jequality/documentation/EDocumentation.java deleted file mode 100644 index f211beb..0000000 --- a/com.io7m.jequality.documentation/src/main/java/com/io7m/jequality/documentation/EDocumentation.java +++ /dev/null @@ -1,52 +0,0 @@ -/* - * Copyright © 2014 Mark Raynsford https://www.io7m.com - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY - * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR - * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -package com.io7m.jequality.documentation; - -import java.net.URI; -import java.net.URISyntaxException; -import java.net.URL; - -/** - * Functions for retrieving the documentation. - */ - -public final class EDocumentation -{ - private EDocumentation() - { - - } - - /** - * @return The documentation URI - */ - - public static URI getDocumentationXMLLocation() - { - try { - final URL url = - EDocumentation.class - .getResource("/com/io7m/jequality/documentation/documentation.xml"); - assert url != null; - final URI uri = url.toURI(); - assert uri != null; - return uri; - } catch (final URISyntaxException e) { - throw new AssertionError(e); - } - } -} diff --git a/com.io7m.jequality.documentation/src/main/java/com/io7m/jequality/documentation/package-info.java b/com.io7m.jequality.documentation/src/main/java/com/io7m/jequality/documentation/package-info.java deleted file mode 100644 index b0e6538..0000000 --- a/com.io7m.jequality.documentation/src/main/java/com/io7m/jequality/documentation/package-info.java +++ /dev/null @@ -1,22 +0,0 @@ -/* - * Copyright © 2014 Mark Raynsford https://www.io7m.com - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY - * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR - * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -/** - * Documentation. - */ - -package com.io7m.jequality.documentation; - diff --git a/com.io7m.jequality.documentation/src/main/java/module-info.java b/com.io7m.jequality.documentation/src/main/java/module-info.java deleted file mode 100644 index 2407e81..0000000 --- a/com.io7m.jequality.documentation/src/main/java/module-info.java +++ /dev/null @@ -1,29 +0,0 @@ -/* - * Copyright © 2014 Mark Raynsford https://www.io7m.com - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY - * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR - * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -/** - * Documentation. - */ - -module com.io7m.jequality.documentation -{ - requires static org.osgi.annotation.bundle; - requires static org.osgi.annotation.versioning; - - requires com.io7m.jequality.core; - - exports com.io7m.jequality.documentation; -} diff --git a/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/brand.xml b/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/brand.xml deleted file mode 100644 index c391a15..0000000 --- a/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/brand.xml +++ /dev/null @@ -1,9 +0,0 @@ - -
-
- io7m -
-
- ${project.parent.name} ${project.version} -
-
\ No newline at end of file diff --git a/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/documentation.css b/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/documentation.css deleted file mode 100644 index 2b9cd43..0000000 --- a/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/documentation.css +++ /dev/null @@ -1,63 +0,0 @@ -.brand -{ - font-size: 75%; - font-family: monospace; -} - -.brand_left -{ - float: left; -} - -.brand_right -{ - text-align: right; -} - -.package -{ - font-family: monospace; - font-weight: bold; -} - -.attribute, -.class, -.command, -.constant, -.element, -.file, -.function, -.keyword, -.type -{ - font-family: monospace; -} - -.example, .license, .terminal -{ - font-family: monospace; - border: 1px solid #ccc; - padding-top: 1.0em; - padding-left: 1.0em; - padding-bottom: 1.0em; - margin-top: 1.2em; - overflow: auto; -} - -.dependencies table td -{ - padding-right: 3.0em; - font-family: monospace; - font-size: 9pt; -} - -.platforms table td -{ - padding-right: 2.0em; -} -.platforms table tbody, -.platforms table thead -{ - font-size: 8pt; - font-family: monospace; -} diff --git a/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/documentation.xml b/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/documentation.xml deleted file mode 100644 index 9893b45..0000000 --- a/com.io7m.jequality.documentation/src/main/resources/com/io7m/jequality/documentation/documentation.xml +++ /dev/null @@ -1,349 +0,0 @@ - - - - - - ${project.parent.name} ${project.version} Documentation - documentation.css - - - - Package Information - - - Orientation - - Overview - - The ${project.parent.name} package - implements a set of functions and types for dealing with equality in Java. - - - - - - Installation - - Source compilation - - The project can be compiled and installed with - Maven: - - - - - - - - Maven - - Regular releases are made to the - Central Repository, - so it's possible to use the ${project.parent.name} - package in your projects with the following Maven dependency: - - - - ${project.groupId} - ${project.parent.artifactId}-core - ${project.version} -]]> - - - All io7m.com - packages use Semantic Versioning - - http://semver.org - , which implies that it is always safe to use version ranges - with an exclusive upper bound equal to the next major version - the API of - the package will not change in a backwards-incompatible manner before the - next major version. - - - - - - Platform Specific Issues - - There are currently no known platform-specific issues. - - - - - License - - All files distributed with the ${project.parent.name} - package are placed under the following license: - http://io7m.com - -Permission to use, copy, modify, and/or distribute this software for any -purpose with or without fee is hereby granted, provided that the above -copyright notice and this permission notice appear in all copies. - -THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.]]> - - - - - - - Usage - - - Annotations - - Overview - - In Java, if a class does not override the - equals - method provided by the standard - java.lang.Object - type, then the class effectively has reference equality. - That is, the equals method simply compares - the addresses of the operands. In some cases this is desirable; in most - cases it is not. It is very easy to forget to override an - equals method, leading to extremely - subtle and dangerous bugs. - - - The ${project.parent.name} package - provides a set of annotations and a validator to check that classes - conform to their annotations. Essentially, the programmer annotates a - class with an annotation that states that the class is expected to - implement either structural or - reference equality. A class is assumed - to implement structural equality iff - it overrides equals. The provided - validator checks that classes are annotated, and that they implement - the type of equality that their annotations claim. As an extra safety - check, the validator checks that if equals - is overridden, then hashCode is - also overridden in the same class. The validator is not capable of checking that an - overridden equals actually does - implement structural equality (and does not, - for example, simply delegate to java.lang.Object). - Solving this problem is undecidable in general. - - - - Validation - - Validation of classes is expected to occur in the test suite of - the project using the ${project.parent.name} package. - - - As an example: - - - Validation (RefEquality) - - - - The RefEquality class uses the - EqualityReference - annotation to indicate that that it implements reference equality. - The validator checks that this is indeed the case. The following - test fails: - - - Validation (RefEqualityWrong) - - - - The RefEqualityWrong class claims that - it implements reference equality, and yet overrides - equals. The validator will catch - this and the test will fail. - - - Validation (StructuralEquality) - - - - The StructuralEquality class claims - to implement structural equality and does appear to override - equals (even though the equality - relation it defines is not correct). The validator assumes that this - class is correct. - - - - - Complaints - - Handling of equality in Java is usually considered to be one of the - worst design mistakes of the language. The problems are manifold. Firstly, - the equals method is defined on the - java.lang.Object - type from which all Java classes are forced to inherit. This means that - equality must be defined for all types, - even those that do not have sensible equality relations - - Consider the required equality relation for function types. - . If an object forgets to override equals, - then the object is given reference equality by default. - Secondly, the argument to the - equals method is of type - java.lang.Object, meaning that it's - perfectly possible to query the equality of values of different types - (which almost never makes logical sense). Thirdly, the - equals method must be consistent - with the associated - hashCode - method in order for the standard library collections to behave correctly. - - - Had Java been designed today, the correct way to design - equals, assuming that - java.lang.Object still existed, - would be for java.lang.Object - to declare neither equals - nor hashCode. A static - method same would be defined - in java.lang.Object in order - to compare the addresses of two values. The following interface - types would be provided by the standard library: - - - Interfaces - -{ - boolean equals(A x); -} - -public interface Hashable> -{ - int hashCode(); -}]]> - - - Effectively, equality is only defined for objects that - explicitly implement Equals. The - Equals type implies structural - equality. - Objects can only be placed into collections that require - hashing if they explicitly implement Hashable - - The constraint on the generic parameter of Hashable - is intended to imply that all Hashable - objects also have a defined equality relation. This could arguably - be removed. - . - The invariance of generic parameters means that - comparing objects that are of different types is statically prevented. - - - This is the approach taken by far safer languages such as - Haskell. - Unfortunately, it is too late to fix these major design flaws in Java. - - - - Floating point - - The ${project.parent.name} package - implements the floating point comparison functions described in - Comparing floating point numbers, 2012 edition. - - - - - - API Reference - - - Javadoc - - API documentation for the package is provided via the - included Javadoc. - - - - - diff --git a/pom.xml b/pom.xml index 9b31312..6229af7 100644 --- a/pom.xml +++ b/pom.xml @@ -19,7 +19,6 @@ com.io7m.jequality.core - com.io7m.jequality.documentation com.io7m.jequality.tests @@ -66,6 +65,10 @@ sonatype-nexus-staging https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/ + + sonatype-nexus-snapshots + https://s01.oss.sonatype.org/content/repositories/snapshots/ + @@ -110,13 +113,6 @@ - - - com.io7m.jstructural - io7m-jstructural-maven-plugin - 5.0.0 - - com.github.spotbugs diff --git a/src/site/resources/documentation.xml b/src/site/resources/documentation.xml index 5c0c663..138f68d 100644 --- a/src/site/resources/documentation.xml +++ b/src/site/resources/documentation.xml @@ -2,8 +2,7 @@

User documentation

- +

+ See the README. +