Module org.cicirello.core

Copyright (C) 2019-2024 Vincent A. Cicirello.

Website: https://core.cicirello.org/

API documentation: https://core.cicirello.org/api

Packages and Releases
Build Status
JaCoCo Test Coverage
Security
Other Information
Support

Overview

The Java module org.cicirello.core provides some of the core utilities and data structures used in several of our other libraries and projects, including but not limited to Chips-n-Salsa and JavaPermutationTools, as well as various applications that use those libraries.

Java 17+

The org.cicirello.core currently supports Java 17+. See the following table for mapping between library version and minimum supported Java version.

version	Java requirements
2.x.y	Java 17+
1.x.y	Java 11+

Versioning Scheme

org.cicirello.core uses Semantic Versioning with version numbers of the form: MAJOR.MINOR.PATCH, where differences in MAJOR correspond to incompatible API changes, differences in MINOR correspond to introduction of backwards compatible new functionality, and PATCH corresponds to backwards compatible bug fixes.

Examples

Some of our other projects use this module. You may consult the source code of JavaPermutationTools and/or Chips-n-Salsa for code examples.

Java Modules

This library provides a Java module, org.cicirello.core. If you are using in a project that uses the Java Platform Module System, then add the following to your module-info.java:

module your.module.name.here {
	requires org.cicirello.core;
}

Importing from Package Repositories

Prebuilt artifacts are regularly published to Maven Central and GitHub Packages. In most cases, you'll want to use Maven Central. Releases are published to GitHub Packages mainly as a fall-back in the unlikely scenario that Maven Central is unavailable.

Importing from Maven Central

Add this to the dependencies section of your pom.xml, replacing x.y.z with the version number that you want to use.

<dependency>
  <groupId>org.cicirello</groupId>
  <artifactId>core</artifactId>
  <version>x.y.z</version>
</dependency>

Importing from GitHub Packages

If you'd prefer to import from GitHub Packages, rather than Maven Central, then: (1) add the dependency as indicated in previous section above, and (2) add the following to the repositories section of your pom.xml:

<repository>
  <id>github</id>
  <name>GitHub cicirello Apache Maven Packages</name>
  <url>https://maven.pkg.github.com/cicirello/core</url>
</repository>

Note that GitHub Packages requires authenticating to GitHub.

Downloading Jar Files

If you don't use a dependency manager that supports importing from Maven Central or other package repositories, or if you simply prefer to download manually, prebuilt jars are also attached to each GitHub Release.

Building the Library (with Maven)

The org.cicirello.core module is built using Maven. The root of the repository contains a Maven pom.xml. To build the library, execute mvn package at the root of the repository, which will compile all classes, run all tests, run javadoc, and generate jar files of the library, the sources, and the javadocs. The file names make this distinction explicit. All build outputs will then be found in the directory target.

To include generation of a code coverage report during the build, execute mvn package -Pcoverage at the root of the repository to enable a Maven profile that executes JaCoCo during the test phase.

To run all static analysis tools (i.e., SpotBugs, Find Security Bugs, refactor-first), execute mvn package -Panalysis to enable a Maven profile that executes the various static analysis tools that we are using. The SpotBugs html report will be found in the target directory, or you can use the SpotBugs GUI with: mvn spotbugs:gui -Panalysis. The refactor-first report will be found in the target/site directory.

To run all of the above: mvn package -P "analysis,coverage".

License

The org.cicirello.core module is licensed under the GNU General Public License 3.0.

Contribute

If you would like to contribute in any way, such as reporting bugs, suggesting new functionality, or code contributions such as bug fixes or implementations of new functionality, then start by reading the contribution guidelines. This project has adopted the Contributor Covenant Code of Conduct.