////
DO NOT EDIT THIS FILE. IT WAS GENERATED.
Manual changes to this file will be lost when it is generated again.
Edit the files in the src/main/asciidoc/ directory instead.
////

:jdkversion: 1.8

image::https://github.com/spring-cloud/spring-cloud-sleuth/workflows/Build/badge.svg?style=svg["Build",link="https://github.com/spring-cloud/spring-cloud-sleuth/actions"]
image::https://badges.gitter.im/spring-cloud/spring-cloud-sleuth.svg[Gitter,link="https://gitter.im/spring-cloud/spring-cloud-sleuth?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]

== Spring Cloud Sleuth

=== !!!! IMPORTANT !!!!

Spring Cloud Sleuth's last minor version is 3.1. You can check the https://github.com/spring-cloud/spring-cloud-sleuth/tree/3.1.x[3.1.x] branch for the latest commits.

WARNING: Spring Cloud Sleuth will not work with Spring Boot 3.x onward. The last major version of Spring Boot that Sleuth will support is 2.x.

The core of this project got moved to https://micrometer.io/docs/tracing[Micrometer Tracing] project and the instrumentations will be moved to https://micrometer.io/[Micrometer] and all respective projects (no longer all instrumentations will be done in a single repository.

You can check the https://github.com/micrometer-metrics/tracing/wiki/Spring-Cloud-Sleuth-3.1-Migration-Guide[Micrometer Tracing migration guide] to learn how to migrate from Spring Cloud Sleuth to Micrometer Tracing.

=== Introduction

Spring Cloud Sleuth provides Spring Boot auto-configuration for distributed tracing.

Sleuth configures everything you need to get started.
This includes where trace data (spans) are reported to, how many traces to keep (sampling), if remote fields (baggage) are sent, and which libraries are traced.

=== Quick Start

Add Spring Cloud Sleuth to the classpath of a Spring Boot application (together with a Tracer implementation) and you will see trace IDs in logs.
Example of Sleuth with Brave tracer:

[source,xml,indent=0,subs="verbatim,quotes,attributes"]
----
    <!-- Spring Cloud Sleuth requires a Spring Cloud BOM -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <!-- Provide the latest stable Spring Cloud release train version (e.g. 2020.0.0) -->
                <version>${release.train.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <!-- Boot's Web support -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- Sleuth with Brave tracer implementation -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-sleuth</artifactId>
        </dependency>
    </dependencies>
----

Consider the following HTTP handler:

[source,java,indent=0]
----
@RestController
public class DemoController {
    private static Logger log = LoggerFactory.getLogger(DemoController.class);

    @RequestMapping("/")
    public String home() {
        log.info("Handling home");
        return "Hello World";
    }
}
----

If you add that handler to a controller, you can see the calls to `home()`
being traced in the logs (notice the `0b6aaf642574edd3` ids).

[indent=0]
----
2020-10-21 12:01:16.285  INFO [,0b6aaf642574edd3,0b6aaf642574edd3,true] 289589 --- [nio-9000-exec-1] DemoController	          : Handling home!
----

NOTE: Instead of logging the request in the handler explicitly, you could set `logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG`.

NOTE: Set `spring.application.name=myService` (for instance) to see the service name as well as the trace and span IDs.

== Documentation

Please visit the https://docs.spring.io/spring-cloud-sleuth/docs/[documentation page] to read more about the project.

== Building

:jdkversion: 1.8

=== Basic Compile and Test

To build the source you will need to install JDK {jdkversion}.

Spring Cloud uses Maven for most build-related activities, and you
should be able to get off the ground quite quickly by cloning the
project you are interested in and typing

----
$ ./mvnw install
----

NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command
in place of `./mvnw` in the examples below. If you do that you also
might need to add `-P spring` if your local Maven settings do not
contain repository declarations for spring pre-release artifacts.

NOTE: Be aware that you might need to increase the amount of memory
available to Maven by setting a `MAVEN_OPTS` environment variable with
a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in
the `.mvn` configuration, so if you find you have to do it to make a
build succeed, please raise a ticket to get the settings added to
source control.

The projects that require middleware (i.e. Redis) for testing generally
require that a local instance of [Docker](https://www.docker.com/get-started) is installed and running.

=== Documentation

The spring-cloud-build module has a "docs" profile, and if you switch
that on it will try to build asciidoc sources from
`src/main/asciidoc`. As part of that process it will look for a
`README.adoc` and process it by loading all the includes, but not
parsing or rendering it, just copying it to `${main.basedir}`
(defaults to `${basedir}`, i.e. the root of the project). If there are
any changes in the README it will then show up after a Maven build as
a modified file in the correct place. Just commit it and push the change.

=== Working with the code
If you don't have an IDE preference we would recommend that you use
https://www.springsource.com/developer/sts[Spring Tools Suite] or
https://eclipse.org[Eclipse] when working with the code. We use the
https://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools
should also work without issue as long as they use Maven 3.3.3 or better.

==== Activate the Spring Maven profile
Spring Cloud projects require the 'spring' Maven profile to be activated to resolve
the spring milestone and snapshot repositories. Use your preferred IDE to set this
profile to be active, or you may experience build errors.

==== Importing into eclipse with m2eclipse
We recommend the https://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
marketplace".

NOTE: Older versions of m2e do not support Maven 3.3, so once the
projects are imported into Eclipse you will also need to tell
m2eclipse to use the right profile for the projects.  If you
see many different errors related to the POMs in the projects, check
that you have an up to date installation.  If you can't upgrade m2e,
add the "spring" profile to your `settings.xml`. Alternatively you can
copy the repository settings from the "spring" profile of the parent
pom into your `settings.xml`.

==== Importing into eclipse without m2eclipse
If you prefer not to use m2eclipse you can generate eclipse project metadata using the
following command:

[indent=0]
----
	$ ./mvnw eclipse:eclipse
----

The generated eclipse projects can be imported by selecting `import existing projects`
from the `file` menu.

== Contributing

:spring-cloud-build-branch: 3.1.x

Spring Cloud is released under the non-restrictive Apache 2.0 license,
and follows a very standard Github development process, using Github
tracker for issues and merging pull requests into master. If you want
to contribute even something trivial please do not hesitate, but
follow the guidelines below.

=== Sign the Contributor License Agreement
Before we accept a non-trivial patch or pull request we will need you to sign the
https://cla.pivotal.io/sign/spring[Contributor License Agreement].
Signing the contributor's agreement does not grant anyone commit rights to the main
repository, but it does mean that we can accept your contributions, and you will get an
author credit if we do.  Active contributors might be asked to join the core team, and
given the ability to merge pull requests.

=== Code of Conduct
This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/3.1.x/docs/src/main/asciidoc/code-of-conduct.adoc[code of
conduct]. By participating, you  are expected to uphold this code. Please report
unacceptable behavior to spring-code-of-conduct@pivotal.io.

=== Code Conventions and Housekeeping
None of these is essential for a pull request, but they will all help.  They can also be
added after the original pull request but before a merge.

* Use the Spring Framework code format conventions. If you use Eclipse
  you can import formatter settings using the
  `eclipse-code-formatter.xml` file from the
  https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/3.1.x/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring
  Cloud Build] project. If using IntelliJ, you can use the
  https://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter
  Plugin] to import the same file.
* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
  `@author` tag identifying you, and preferably at least a paragraph on what the class is
  for.
* Add the ASF license header comment to all new `.java` files (copy from existing files
  in the project)
* Add yourself as an `@author` to the .java files that you modify substantially (more
  than cosmetic changes).
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
* A few unit tests would help a lot as well -- someone has to do it.
* If no-one else is using your branch, please rebase it against the current master (or
  other target branch in the main project).
* When writing a commit message please follow https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions],
  if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
  message (where XXXX is the issue number).

=== Checkstyle

Spring Cloud Build comes with a set of checkstyle rules. You can find them in the `spring-cloud-build-tools` module. The most notable files under the module are:

.spring-cloud-build-tools/
----
└── src
    ├── checkstyle
    │   └── checkstyle-suppressions.xml <3>
    └── main
        └── resources
            ├── checkstyle-header.txt <2>
            └── checkstyle.xml <1>
----
<1> Default Checkstyle rules
<2> File header setup
<3> Default suppression rules

==== Checkstyle configuration

Checkstyle rules are *disabled by default*. To add checkstyle to your project just define the following properties and plugins.

.pom.xml
----
<properties>
<maven-checkstyle-plugin.failsOnError>true</maven-checkstyle-plugin.failsOnError> <1>
        <maven-checkstyle-plugin.failsOnViolation>true
        </maven-checkstyle-plugin.failsOnViolation> <2>
        <maven-checkstyle-plugin.includeTestSourceDirectory>true
        </maven-checkstyle-plugin.includeTestSourceDirectory> <3>
</properties>

<build>
        <plugins>
            <plugin> <4>
                <groupId>io.spring.javaformat</groupId>
                <artifactId>spring-javaformat-maven-plugin</artifactId>
            </plugin>
            <plugin> <5>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-checkstyle-plugin</artifactId>
            </plugin>
        </plugins>

    <reporting>
        <plugins>
            <plugin> <5>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-checkstyle-plugin</artifactId>
            </plugin>
        </plugins>
    </reporting>
</build>
----
<1> Fails the build upon Checkstyle errors
<2> Fails the build upon Checkstyle violations
<3> Checkstyle analyzes also the test sources
<4> Add the Spring Java Format plugin that will reformat your code to pass most of the Checkstyle formatting rules
<5> Add checkstyle plugin to your build and reporting phases

If you need to suppress some rules (e.g. line length needs to be longer), then it's enough for you to define a file under `${project.root}/src/checkstyle/checkstyle-suppressions.xml` with your suppressions. Example:

.projectRoot/src/checkstyle/checkstyle-suppresions.xml
----
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
		"-//Puppy Crawl//DTD Suppressions 1.1//EN"
		"https://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
<suppressions>
	<suppress files=".*ConfigServerApplication\.java" checks="HideUtilityClassConstructor"/>
	<suppress files=".*ConfigClientWatch\.java" checks="LineLengthCheck"/>
</suppressions>
----

It's advisable to copy the `${spring-cloud-build.rootFolder}/.editorconfig` and `${spring-cloud-build.rootFolder}/.springformat` to your project. That way, some default formatting rules will be applied. You can do so by running this script:

```bash
$ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/3.1.x/.editorconfig -o .editorconfig
$ touch .springformat
```

=== IDE setup

==== Intellij IDEA

In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin.
The following files can be found in the https://github.com/spring-cloud/spring-cloud-build/tree/3.1.x/spring-cloud-build-tools[Spring Cloud Build] project.

.spring-cloud-build-tools/
----
└── src
    ├── checkstyle
    │   └── checkstyle-suppressions.xml <3>
    └── main
        └── resources
            ├── checkstyle-header.txt <2>
            ├── checkstyle.xml <1>
            └── intellij
                ├── Intellij_Project_Defaults.xml <4>
                └── Intellij_Spring_Boot_Java_Conventions.xml <5>
----
<1> Default Checkstyle rules
<2> File header setup
<3> Default suppression rules
<4> Project defaults for Intellij that apply most of Checkstyle rules
<5> Project style conventions for Intellij that apply most of Checkstyle rules

.Code style

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-code-style.png[Code style]

Go to `File` -> `Settings` -> `Editor` -> `Code style`. There click on the icon next to the `Scheme` section. There, click on the `Import Scheme` value and pick the `Intellij IDEA code style XML` option. Import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml` file.

.Inspection profiles

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-inspections.png[Code style]

Go to `File` -> `Settings` -> `Editor` -> `Inspections`. There click on the icon next to the `Profile` section. There, click on the `Import Profile` and import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml` file.

.Checkstyle

To have Intellij work with Checkstyle, you have to install the `Checkstyle` plugin. It's advisable to also install the `Assertions2Assertj` to automatically convert the JUnit assertions

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-checkstyle.png[Checkstyle]

Go to `File` -> `Settings` -> `Other settings` -> `Checkstyle`. There click on the `+` icon in the `Configuration file` section. There, you'll have to define where the checkstyle rules should be picked from. In the image above, we've picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build's GitHub repository (e.g. for the `checkstyle.xml` : `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/3.1.x/spring-cloud-build-tools/src/main/resources/checkstyle.xml`). We need to provide the following variables:

- `checkstyle.header.file` - please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/3.1.x/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` URL.
- `checkstyle.suppressions.file` - default suppressions. Please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/3.1.x/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` URL.
- `checkstyle.additional.suppressions.file` - this variable corresponds to suppressions in your local project. E.g. you're working on `spring-cloud-contract`. Then point to the `project-root/src/checkstyle/checkstyle-suppressions.xml` folder. Example for `spring-cloud-contract` would be: `/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml`.

IMPORTANT: Remember to set the `Scan Scope` to `All sources` since we apply checkstyle rules for production and test sources.

=== Duplicate Finder

Spring Cloud Build brings along the  `basepom:duplicate-finder-maven-plugin`, that enables flagging duplicate and conflicting classes and resources on the java classpath.

==== Duplicate Finder configuration

Duplicate finder is *enabled by default* and will run in the `verify` phase of your Maven build, but it will only take effect in your project if you add the `duplicate-finder-maven-plugin` to the `build` section of the projecst's `pom.xml`.

.pom.xml
[source,xml]
----
<build>
    <plugins>
        <plugin>
            <groupId>org.basepom.maven</groupId>
            <artifactId>duplicate-finder-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>
----

For other properties, we have set defaults as listed in the https://github.com/basepom/duplicate-finder-maven-plugin/wiki[plugin documentation].

You can easily override them but setting the value of the selected property prefixed with `duplicate-finder-maven-plugin`. For example, set `duplicate-finder-maven-plugin.skip` to `true` in order to skip duplicates check in your build.

If you need to add `ignoredClassPatterns` or `ignoredResourcePatterns` to your setup, make sure to add them in the plugin configuration section of your project:

[source,xml]
----
<build>
    <plugins>
        <plugin>
            <groupId>org.basepom.maven</groupId>
            <artifactId>duplicate-finder-maven-plugin</artifactId>
            <configuration>
                <ignoredClassPatterns>
                    <ignoredClassPattern>org.joda.time.base.BaseDateTime</ignoredClassPattern>
                    <ignoredClassPattern>.*module-info</ignoredClassPattern>
                </ignoredClassPatterns>
                <ignoredResourcePatterns>
                    <ignoredResourcePattern>changelog.txt</ignoredResourcePattern>
                </ignoredResourcePatterns>
            </configuration>
        </plugin>
    </plugins>
</build>

----


<!--

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        https://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

-->

# formatter-maven-plugin

[![mvn verify][ci_img]][ci_link]
[![Maven Central][maven_img]][maven_link]
[![Apache License][license_img]][license_link]

This project provides a mechanism to automatically (re)format your [Maven]
project during a Maven build, or to verify its formatting, so that your project
can converge on consistent code style regardless of user preferences, IDE
settings, etc.

It began following a post on the topic (which can be found [here][blog]; thanks
to John for writing such a helpful article). It now uses the [Eclipse] code
formatter for Java, and has grown to support formatting of other file types as
well.

For a companion [m2e] project configurator, see [formatter-m2e-configurator].

This software is provided WITHOUT ANY WARRANTY, and is available under the
Apache License, Version 2. Any code loss caused by using this plugin is not the
responsibility of the author(s). Be sure to use some source repository
management system such as GIT before using this plugin.

Contributions are welcome.

## How to use

View the Maven plugin documentation for the latest release [here][plugin-docs].

## Eclipse Compatibility

The primary use case of this plugin is to ensure consistent formatting for a
project, regardless of differences between IDE preferences or IDE versions that
developers use. Nevertheless, some users may find it useful to correlate
versions of this plugin to the version of Eclipse whose code is used as the
basis for this plugin's formatting. See [the project website][compat] for a
list of recent versions of this plugin and their corresponding Eclipse
versions.

## Integration Tests

mvn clean verify

## JDK Requirements
- 2.16.x requires jdk 8 as required by Eclipse binaries
- 2.17.x and later requires jdk 11 as required by Eclipse binaries
- 2.24.x and later requires jdk 17 as required by Eclipse binaries

## Changelog

The changelog was removed but now restored using a generated process.  To generate a change log update, run the following

```
mvn mavanagaiata:changelog -D"mavanagaiata.format=MARKDOWN" -D"mavanagaiata.changelog.outputFile=CHANGELOG.md"
```

[Eclipse]: https://eclipse.org
[Maven]: https://maven.apache.org
[blog]: https://ssscripting.wordpress.com/2009/06/10/how-to-use-the-eclipse-code-formatter-from-your-code/
[ci_img]: https://github.com/revelc/formatter-maven-plugin/workflows/mvn%20verify/badge.svg
[ci_link]: https://github.com/revelc/formatter-maven-plugin/actions
[compat]: https://code.revelc.net/formatter-maven-plugin/eclipse-versions.html
[formatter-m2e-configurator]: https://github.com/revelc/formatter-m2e-configurator
[license_img]: https://img.shields.io/badge/license-Apache%202.0-blue.svg
[license_link]: https://github.com/revelc/formatter-maven-plugin/blob/main/LICENSE
[m2e]: https://eclipse.org/m2e
[maven_img]: https://maven-badges.herokuapp.com/maven-central/net.revelc.code.formatter/formatter-maven-plugin/badge.svg
[maven_link]: https://maven-badges.herokuapp.com/maven-central/net.revelc.code.formatter/formatter-maven-plugin
[plugin-docs]: https://code.revelc.net/formatter-maven-plugin/
[related1]: https://wiki.eclipse.org/M2E_extension_development_environment
[related2]: https://wiki.eclipse.org/Submitting_M2E_marketplace_entries
[related3]: https://www.eclipse.org/forums/index.php/t/478639/0/unread/
[related4]: https://www.vogella.com/articles/EclipsePreferences/article.html


# Sortpom Maven Plugin ![Icon](https://raw.githubusercontent.com/Ekryd/sortpom/master/misc/Sortpom.png)

[![Build Status](https://circleci.com/gh/Ekryd/sortpom.svg?style=svg)](https://app.circleci.com/pipelines/github/Ekryd/sortpom)
[![Coverage Status](https://coveralls.io/repos/github/Ekryd/sortpom/badge.svg?branch=master)](https://coveralls.io/github/Ekryd/sortpom?branch=master)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.ekryd.sortpom/sortpom-maven-plugin/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.ekryd.sortpom/sortpom-maven-plugin)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=com.github.ekryd.sortpom%3Asortpom-parent&metric=alert_status)](https://sonarcloud.io/dashboard?id=com.github.ekryd.sortpom%3Asortpom-parent)
[![Licence](https://img.shields.io/github/license/Ekryd/sortpom?color=success)](https://github.com/Ekryd/sortpom/blob/master/LICENSE.md)
[![Known Vulnerabilities](https://snyk.io/test/github/Ekryd/sortpom/badge.svg)](https://snyk.io/test/github/Ekryd/sortpom)

Maven plugin that helps the user sort pom.xml by formatting the XML and organizing XML sections in a predefined order.
The main advantages to have standardized sorted poms are that they become more readable and that comparisons between different module poms becomes much easier.

## Goals Overview ##
The SortPom Plugin has two goals.

  * **mvn sortpom:sort** sorts the current pom.xml file. This goal will always sort the pom.xml file.

  * **mvn sortpom:verify** only sorts the current pom.xml file if the xml elements are unsorted. This goal ignores text formatting (such as indentation and line breaks) when it verifies if the pom is sorted or not.

![Icon](https://raw.githubusercontent.com/Ekryd/sortpom/master/misc/sortpom.jpg)

## Usage ##

The Sortpom plugin will reorder the pom elements and format the xml structure in the pom-file. The plugin can be [configured](https://github.com/Ekryd/sortpom/wiki/Parameters) to sort by different standards or by a custom format. A backup file will be created by default, so that you can check how the pom-file has changed.

Sortpom works best if it is run every time during Maven compilation. [Configure](https://github.com/Ekryd/sortpom/wiki/Parameters) it once and then forget about it. Replace the plugin version with the latest one:
```xml
<build>
  <plugins>
    <plugin>
      <groupId>com.github.ekryd.sortpom</groupId>
      <artifactId>sortpom-maven-plugin</artifactId>
      <version>3.4.0</version>
      <executions>
        <execution>
          <goals>
            <goal>sort</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
</build>
```

If you just want to perform a simple test what the plugin does then open a command prompt in your project home and enter
```
mvn com.github.ekryd.sortpom:sortpom-maven-plugin:3.3.0:sort -Dsort.predefinedSortOrder=custom_1
```

Detailed example of how the plugin can be configured to run every time you build your project; see [recommended configuration](https://github.com/Ekryd/sortpom/wiki/Recommended-configuration) wiki page

The plugin will not change how your Maven project is compiled  ([Exception](https://github.com/Ekryd/sortpom/wiki/Parameters-that-can-affect-your-build))

## News ##
Added
  * 2024-05-19: Released version 4.0.0. **THIS IS A BREAKING CHANGE!** Indentation for attributes are now 2 * indent size [#413](/../../issues/413), and the parameter `indentSchemaLocation` has been deprecated in favor of `indentAttribute`. [#412](/../../issues/412).
  * 2024-03-10: Released version 3.4.1. Solves a bug, where whitespace was removed even if `xml:space="preserve"` was used [#402](/../../issues/402).
  * 2024-02-20: Released version 3.4.0. Added parameter for omitting newline at end of file [#399](/../../issues/399).
  * 2023-08-04: Received an [Open Source Licence](https://jb.gg/OpenSourceSupport) for IntelliJ Ultimate. Once again, thank you [JetBrains](http://www.jetbrains.com/idea/)!!
  * 2023-07-24: Released version 3.3.0. Added parameter for quiet output from the plugin [#338](/../../issues/338). Thanks, [gnodet](https://github.com/gnodet) for the PR!
  * 2023-01-29: Released version 3.2.1. Dependency updates. No new functionality
  * 2022-07-17: Released version 3.2.0. Added parameter `sortDependencyManagement` where dependency management can be sorted independently of dependencies [#210](/../../issues/210). Thanks, [Ssquan](https://github.com/ssquan) for the PR!
  * 2022-05-29: Released version 3.1.3. Fix formatting if text and other content is placed together in a xml tag [#209](/../../issues/209)
  * 2022-05-22: Released version 3.1.0. **THIS IS A BREAKING CHANGE!** Dropped support for Java 8. Updated underlying xml framework due to vulnerabilities. Updated other libraries and plugins.
  * 2021-04-20: Released version 3.0.0. **THIS IS A BREAKING CHANGE!** The predefined sort order is now according to the recommended pom order (as decided in 2008). Blank lines in the POM are now kept by default. If dependencies are sorted by SCOPE, then imported bom-files will be sorted towards the top. [#93](/../../issues/93) [#105](/../../issues/105)
  * 2020-02-24: Renewed Open Source Licence for Araxis Merge. Thank you [Araxis](https://www.araxis.com/merge/)!
  * 2015-03-31: Moved the SortPom plugin to GitHub.

## Versions ##
https://github.com/Ekryd/sortpom/wiki/Versions

## Plugin parameters ##
https://github.com/Ekryd/sortpom/wiki/Parameters

## Download ##
The plugin is hosted i [Maven Central](http://mvnrepository.com/artifact/com.github.ekryd.sortpom/sortpom-maven-plugin) and will be downloaded automatically if you include it as a plugin in your pom file.

## Donations ##
If you use it, then please consider some encouragement. ⭐ Star it in GitHub!

[![](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=JB25X84DDG5JW&lc=SE&item_name=Encourage%20the%20development&item_number=sortpom&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)


[![Maven Central](https://img.shields.io/maven-central/v/io.github.bonigarcia/webdrivermanager.svg)](https://search.maven.org/search?q=g:io.github.bonigarcia%20a:webdrivermanager)
[![Build Status](https://github.com/bonigarcia/webdrivermanager/workflows/build/badge.svg)](https://github.com/bonigarcia/webdrivermanager/actions)
[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=io.github.bonigarcia:webdrivermanager&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=io.github.bonigarcia%3Awebdrivermanager)
[![codecov](https://codecov.io/gh/bonigarcia/webdrivermanager/branch/master/graph/badge.svg)](https://codecov.io/gh/bonigarcia/webdrivermanager)
[![badge-jdk](https://img.shields.io/badge/jdk-8-green.svg)](https://www.oracle.com/java/technologies/javase-downloads.html)
[![License badge](https://img.shields.io/badge/license-Apache2-green.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Backers on Open Collective](https://opencollective.com/webdrivermanager/backers/badge.svg)](#backers)
[![Sponsors on Open Collective](https://opencollective.com/webdrivermanager/sponsors/badge.svg)](#sponsors)
[![Support badge](https://img.shields.io/badge/stackoverflow-webdrivermanager_java-green.svg?logo=stackoverflow)](https://stackoverflow.com/questions/tagged/webdrivermanager-java)
[![Twitter Follow](https://img.shields.io/twitter/follow/boni_gg.svg?style=social)](https://twitter.com/boni_gg)

# [![][Logo]][WebDriverManager]
[WebDriverManager] is an open-source Java library that carries out the management (i.e., download, setup, and maintenance) of the drivers required by [Selenium WebDriver] (e.g., chromedriver, geckodriver, msedgedriver, etc.) in a fully automated manner. In addition, WebDriverManager provides other relevant features, such as the capability to discover browsers installed in the local system, building WebDriver objects (such as `ChromeDriver`, `FirefoxDriver`, `EdgeDriver`, etc.), and running browsers in Docker containers seamlessly.

## Documentation
As of version 5, the documentation of WebDriverManager has moved [here][WebDriverManager]. This site contains all the features, examples, configuration, and advanced capabilities of WebDriverManager.

## Driver Management
The primary use of WebDriverManager is the automation of driver management. For using this feature, you need to select a given manager in the WebDriverManager API (e.g., `chromedriver()` for Chrome) and invoke the method `setup()`. The following example shows the skeleton of a test case using [JUnit 5], [Selenium WebDriver], and [WebDriverManager].

```java
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

import io.github.bonigarcia.wdm.WebDriverManager;

class ChromeTest {

    WebDriver driver;

    @BeforeAll
    static void setupAll() {
        WebDriverManager.chromedriver().setup();
    }

    @BeforeEach
    void setup() {
        driver = new ChromeDriver();
    }

    @AfterEach
    void teardown() {
        driver.quit();
    }

    @Test
    void test() {
        // Your test logic here
    }

}
```

Alternatively, you can use the method `create()` to manage automatically the driver and instantiate the `WebDriver` object in a single line. For instance, as follows:

```java
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

import io.github.bonigarcia.wdm.WebDriverManager;

class ChromeCreateTest {

    WebDriver driver;

    @BeforeEach
    void setup() {
        driver = WebDriverManager.chromedriver().create();
    }

    @AfterEach
    void teardown() {
        driver.quit();
    }

    @Test
    void test() {
        // Your test logic here
    }

}
```

For further information about the driver resolution algorithm implemented by WebDriverManager and configuration capabilities, read the [documentation][WebDriverManager].

## Browsers in Docker
Another relevant new feature available in WebDriverManager 5 is the ability to create browsers in [Docker] containers out of the box. The requirement to use this feature is to have installed a [Docker Engine] in the machine running the tests. To use it, we need to invoke the method `browserInDocker()` in conjunction with `create()` of a given manager. This way, WebDriverManager pulls the image from [Docker Hub], starts the container, and instantiates the WebDriver object to use it. The following test shows a simple example using Chrome in Docker. This example also enables the recording of the browser session and remote access using [noVNC]:

```java
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;

import io.github.bonigarcia.wdm.WebDriverManager;

class DockerChromeVncTest {

    WebDriver driver;

    WebDriverManager wdm = WebDriverManager.chromedriver().browserInDocker()
            .enableVnc().enableRecording();

    @BeforeEach
    void setup() {
        driver = wdm.create();
    }

    @AfterEach
    void teardown() {
        wdm.quit();
    }

    @Test
    void test() {
        // Your test logic here
    }

}
```

## Support
WebDriverManager is part of [OpenCollective], an online funding platform for open and transparent communities. You can support the project by contributing as a backer (i.e., a personal [donation] or [recurring contribution]) or as a [sponsor] (i.e., a recurring contribution by a company).

### Backers

### Sponsors

Alternatively, you can acknowledge my work by buying me a coffee:

## About
WebDriverManager (Copyright © 2015-2024) is a project created and maintained by [Boni Garcia] and licensed under the terms of the [Apache 2.0 License].

[Logo]: https://bonigarcia.github.io/img/wdm.png
[WebDriverManager]: https://bonigarcia.dev/webdrivermanager/
[Selenium WebDriver]: https://www.selenium.dev/documentation/webdriver/
[JUnit 5]: https://junit.org/junit5/
[Docker]: https://www.docker.com/
[Docker Engine]: https://docs.docker.com/engine/
[Docker Hub]: https://hub.docker.com/
[noVNC]: https://novnc.com/
[OpenCollective]: https://opencollective.com/webdrivermanager
[donation]: https://opencollective.com/webdrivermanager/donate
[recurring contribution]: https://opencollective.com/webdrivermanager/contribute/backer-8132/checkout
[sponsor]: https://opencollective.com/webdrivermanager/contribute/sponsor-8133/checkout
[Boni Garcia]: https://bonigarcia.dev/
[Apache 2.0 License]: https://www.apache.org/licenses/LICENSE-2.0


 [![Join the chat at https://gitter.im/bsorrentino/maven-confluence-plugin](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/bsorrentino/maven-confluence-plugin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

## What is
It is a **Maven plugin** that generates **project's documentation directly to confluence** allowing, in the same time, to **keep in-sync project evolution with its documentation**.
> Originally hosted to [google code](https://code.google.com/p/maven-confluence-plugin/) from release 4.0.0 has been moved to github

## Documentation
> The standard maven documentation is [here](http://bsorrentino.github.io/maven-confluence-plugin/)
> * [Goals](http://bsorrentino.github.io/maven-confluence-plugin/plugin-info.html)
> * [Usage](http://bsorrentino.github.io/maven-confluence-plugin/usage.html)
> * [Use YAML Site Definition](http://bsorrentino.github.io/maven-confluence-plugin/site_yaml_guide.html)
> * [Use XML Site Definition](http://bsorrentino.github.io/maven-confluence-plugin/site_xml_guide.html)
> * [Use JSON Site Definition](http://bsorrentino.github.io/maven-confluence-plugin/site_json_guide.html)
### Format
> * [Markdown Syntax Support](http://bsorrentino.github.io/maven-confluence-plugin/markdown_guide.html)
> * [Storage Format Support](http://bsorrentino.github.io/maven-confluence-plugin/storageformat_guide.html)
> * [Confluence Wiki Support](http://bsorrentino.github.io/maven-confluence-plugin/Notation%20Guide%20-%20Confluence.html)
### Processor
> * [Site Processor Usage](http://bsorrentino.github.io/maven-confluence-plugin/site_processor_guide.html)
> * [Markdown Processor usage](http://bsorrentino.github.io/maven-confluence-plugin/markdown_processor_guide.html)

## Examples

For practical samples refer to folder/module [test-publishing](https://github.com/bsorrentino/maven-confluence-plugin/tree/master/test-publishing)

## News

| Date             | Release                                                                                | Info                                                                                |
|------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Feb 29, 2024** | [Release 8.0-beta1](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v8.0-beta1) | move implementation on **java 11** [#296](https://github.com/bsorrentino/maven-confluence-plugin/issues/296)                                                                                |
| **Oct 12, 2023** | [Release 7.13](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.13)           | fix some links between markdown files point to non-existing pages [#294](https://github.com/bsorrentino/maven-confluence-plugin/issues/294). fix curly braces in table recognized as macro [#295](https://github.com/bsorrentino/maven-confluence-plugin/issues/295).                                                                                |
| **Jun 23, 2023** | [Release 7.12](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.12)           | Merged PR [#288](https://github.com/bsorrentino/maven-confluence-plugin/pull/288) that fix [#287](https://github.com/bsorrentino/maven-confluence-plugin/issue/287) "**Maven report generation breaks, if a new page was added with new attachments and references to it**". Thanks to [williamschey](https://github.com/williamschey) for contribution. |
| **Mar 23, 2023** | [Release 7.11](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.11)           | Support of Confluence `Excerpt` macro. Refer to [#285](https://github.com/bsorrentino/maven-confluence-plugin/issues/285)                                                                                |
| **Mar 4, 2023**  | [Release 7.10](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.10)           | Allow to skip html tags in markdown processing. Refer to [#284](https://github.com/bsorrentino/maven-confluence-plugin/issues/284)                                                                                |
| **Jan 4, 2023**  | [Release 7.9](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.9)             | Fix problem Problem parsing `%` character from markdown to wiki. Refer to [#282](https://github.com/bsorrentino/maven-confluence-plugin/issues/282)                                                                                |
| **Dec 9, 2022**  | [Release 7.8](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.8)             | Merged PR [#281](https://github.com/bsorrentino/maven-confluence-plugin/pull/281) that fix [#280](https://github.com/bsorrentino/maven-confluence-plugin/issue/280) "**allows specifying additional HTTP headers in the servers section of settings.xml**". Thanks to [DirkMahler](https://github.com/DirkMahler) for contribution.                      |
| **Jul 3, 2022**  | [Release 7.7](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.7)             | Merged PR [#266](https://github.com/bsorrentino/maven-confluence-plugin/pull/266) "**Adding JSON Support**". Thanks to [jksevend](https://github.com/jksevend) for contribution.                                                                                |
| **Jun 3, 2022**  | [Release 7.6](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.6)             | Merged PR [#267](https://github.com/bsorrentino/maven-confluence-plugin/pull/267) "**added function to define jira instance baseurl**", that fix issue [#136](https://github.com/bsorrentino/maven-confluence-plugin/issues/136). Thanks to [tspindler](https://github.com/tspindler) for contribution.                                                  |
| **Apr 1, 2022**  | [Release 7.5](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.5)             | Fix empty table cell not handled properly. Refer to [#264](https://github.com/bsorrentino/maven-confluence-plugin/issues/                                                                                |
| **Jan 10, 2022** | [Release 7.4](https://github.com/bsorrentino/maven-confluence-plugin/releases/tag/v7.4)             | Fix problem with **encoding**. Refer to [#261](https://github.com/bsorrentino/maven-confluence-plugin/issues/261).                                                                                |

### [Release History](HISTORY.md)


[![gradle-publish](https://github.com/IVCTool/IVCT_Framework/actions/workflows/gradle-publish.yml/badge.svg)](https://github.com/IVCTool/IVCT_Framework/actions/workflows/gradle-publish.yml) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/6e7de55a30f049fc917533292a2d35d4)](https://www.codacy.com/gh/IVCTool/IVCT_Framework?utm_source=github.com&utm_medium=referral&utm_content=IVCTool/IVCT_Framework&utm_campaign=Badge_Grade)

# IVCT README

The IVCT_Framework is software to support the **Integration**, **Verification** and **Certification** for HLA Federates. It consists of several core components and services compiled into one tool, called  the **IVCT**. The IVCT tool is a framework to run test cases against systems under test, in order to verify interoperability requirement.

## Installation and running the Software

The simplest way to install and use the software is a docker deployment. Docker is a software deployment framework for containerized components - see [Docker](https://www.docker.com/) for more information. To start the IVCT software you need a so called 'compose' file, and a running docker engine.

    docker-compose up

The compose files are currently maintained in the [IVCT_Operation](https://github.com/IVCTool/IVCT_Compositions) repository. Depending on your requirments, you might need additional components, like your own system under test (SuT) and a HLA-RTI.

The user interface comes in two flavors, a [web based user interface](docs/src/4-5-GUI.adoc), and a [command line interface](docs/src/4-3-commandlinetool.adoc). The web interface looks like this:

![IVCT Overview](docs/src/images/IVCTAnimation.gif)

## For Developers

The IVCT tool is a open source projects that invites developers to share and contribute software and experience. The IVCT components and concepts are explained in some detail in the [document section](docs/src/Home.adoc). Other ways to contribute is to provide test case implementations for existing or possibly new interoperability requirement.

There is a [tutorial to explain the concepts and the best practices for developing test cases](https://github.com/IVCTool/IVCT_TestSuiteDevelopment).

An important resource for building the IVCT tool is the [HLA Container](https://github.com/hlacontainers) project, donated by [TNO](https://www.tno.nl/en/). This project provides the docker images required for the various RTI connections, which are used by the test case engine.

## Futher Reading

  - The general concepts of [HLA Certification is explained by the NATO Modelling & Simulation Centre of Excellence](https://www.mscoe.org/nato-hla-certification-home/).
  - [IVCTool Release Notes](docs/src/0-1-ReleaseNotes.adoc)

## LICENCE

Copyright 2019 NATO/OTAN

Licensed under the Apache License, [Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)

### List of 3rd party libraries

[List of 3rd party libraries used in the IVCT project](docs/src/7-3rdparty-libraries.adoc)


# Gson

Gson is a Java library that can be used to convert Java Objects into their JSON representation. It can also be used to convert a JSON string to an equivalent Java object.
Gson can work with arbitrary Java objects including pre-existing objects that you do not have source-code of.

There are a few open-source projects that can convert Java objects to JSON. However, most of them require that you place Java annotations in your classes; something that you can not do if you do not have access to the source-code. Most also do not fully support the use of Java Generics. Gson considers both of these as very important design goals.

> [!NOTE]\
> Gson is currently in maintenance mode; existing bugs will be fixed, but large new features will likely not be added. If you want to add a new feature, please first search for existing GitHub issues, or create a new one to discuss the feature and get feedback.

> [!IMPORTANT]\
> Gson's main focus is on Java. Using it with other JVM languages such as Kotlin or Scala might work fine in many cases, but language-specific features such as Kotlin's non-`null` types or constructors with default arguments are not supported. This can lead to confusing and incorrect behavior.\
> When using languages other than Java, prefer a JSON library with explicit support for that language.

### Goals
  * Provide simple `toJson()` and `fromJson()` methods to convert Java objects to JSON and vice-versa
  * Allow pre-existing unmodifiable objects to be converted to and from JSON
  * Extensive support of Java Generics
  * Allow custom representations for objects
  * Support arbitrarily complex objects (with deep inheritance hierarchies and extensive use of generic types)

### Download

Gradle:
```gradle
dependencies {
  implementation 'com.google.code.gson:gson:2.11.0'
}
```

Maven:
```xml
<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.11.0</version>
</dependency>
```

[Gson jar downloads](https://maven-badges.herokuapp.com/maven-central/com.google.code.gson/gson) are available from Maven Central.

![Build Status](https://github.com/google/gson/actions/workflows/build.yml/badge.svg)

### Requirements
#### Minimum Java version
- Gson 2.9.0 and newer: Java 7
- Gson 2.8.9 and older: Java 6

Despite supporting older Java versions, Gson also provides a JPMS module descriptor (module name `com.google.gson`) for users of Java 9 or newer.

#### JPMS dependencies (Java 9+)
These are the optional Java Platform Module System (JPMS) JDK modules which Gson depends on.
This only applies when running Java 9 or newer.

- `java.sql` (optional since Gson 2.8.9)\
When this module is present, Gson provides default adapters for some SQL date and time classes.

- `jdk.unsupported`, respectively class `sun.misc.Unsafe` (optional)\
When this module is present, Gson can use the `Unsafe` class to create instances of classes without no-args constructor.
However, care should be taken when relying on this. `Unsafe` is not available in all environments and its usage has some pitfalls,
see [`GsonBuilder.disableJdkUnsafe()`](https://javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/GsonBuilder.html#disableJdkUnsafe()).

#### Minimum Android API level

- Gson 2.11.0 and newer: API level 21
- Gson 2.10.1 and older: API level 19

Older Gson versions may also support lower API levels, however this has not been verified.

### Documentation
  * [API Javadoc](https://www.javadoc.io/doc/com.google.code.gson/gson): Documentation for the current release
  * [User guide](UserGuide.md): This guide contains examples on how to use Gson in your code
  * [Troubleshooting guide](Troubleshooting.md): Describes how to solve common issues when using Gson
  * [Releases and change log](https://github.com/google/gson/releases): Latest releases and changes in these versions; for older releases see [`CHANGELOG.md`](CHANGELOG.md)
  * [Design document](GsonDesignDocument.md): This document discusses issues we faced while designing Gson. It also includes a comparison of Gson with other Java libraries that can be used for Json conversion

Please use the ['gson' tag on StackOverflow](https://stackoverflow.com/questions/tagged/gson), [GitHub Discussions](https://github.com/google/gson/discussions) or the [google-gson Google group](https://groups.google.com/group/google-gson) to discuss Gson or to post questions.

### Related Content Created by Third Parties
  * [Gson Tutorial](https://www.studytrails.com/java/json/java-google-json-introduction/) by `StudyTrails`
  * [Gson Tutorial Series](https://futurestud.io/tutorials/gson-getting-started-with-java-json-serialization-deserialization) by `Future Studio`
  * [Gson API Report](https://abi-laboratory.pro/java/tracker/timeline/gson/)

### Building

Gson uses Maven to build the project:
```
mvn clean verify
```

JDK 11 or newer is required for building, JDK 17 is recommended. Newer JDKs are currently not supported for building (but are supported when _using_ Gson).

### Contributing

See the [contributing guide](https://github.com/google/.github/blob/master/CONTRIBUTING.md).\
Please perform a quick search to check if there are already existing issues or pull requests related to your contribution.

Keep in mind that Gson is in maintenance mode. If you want to add a new feature, please first search for existing GitHub issues, or create a new one to discuss the feature and get feedback.

### License

Gson is released under the [Apache 2.0 license](LICENSE).

```
Copyright 2008 Google Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

### Disclaimer

This is not an officially supported Google product.


# Google Cloud Platform Java Samples

[![Build Status][java-11-badge]][java-11-link] [![Build
Status][java-17-badge]][java-17-link] [![Build Status][java-21-badge]][java-21-link]

This repository holds sample code written in Java that demonstrates the
[Google Cloud Platform](https://cloud.google.com/docs/).

Some samples have accompanying guides on <cloud.google.com>. See respective
README files for details.

## Google Cloud Samples

To browse ready to use code samples check [Google Cloud Samples](https://cloud.google.com/docs/samples?l=java).

## Set Up

1. [Set up your Java Development Environment](https://cloud.google.com/java/docs/setup)

1. Clone this repository:

        git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

1. Obtain authentication credentials.

    Create local credentials by running the following command and following the
    oauth2 flow (read more about the command [here][auth_command]):

        gcloud auth application-default login

    Or manually set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
    to point to a service account key JSON file path.

    Learn more at [Setting Up Authentication for Server to Server Production Applications][ADC].

    *Note:* Application Default Credentials is able to implicitly find the credentials as long as the application is running on Compute Engine, Kubernetes Engine, App Engine, or Cloud Functions.

## Contributing

* See the [Contributing Guide](CONTRIBUTING.md)

## Licensing

* See [LICENSE](LICENSE)

## Supported Java runtimes

Every submitted change has to pass all checks that run on the testing environments with Java 11 and Java 17 runtimes before merging the change to the main branch.
We run periodic checks on the environments with Java 8 and Java 21 runtimes but we don't enforce passing these tests at the moment.
Because Java 8 is a [supported Java runtime][supported_runtimes] in Google Cloud, please configure to build your code sample with Java 8.
In exceptional cases, configure to build your code sample using Java 11.

[supported_runtimes]: https://cloud.google.com/java/docs/supported-java-versions

## Source Code Headers

Every file containing source code must include copyright and license
information. This includes any JS/CSS files that you might be serving out to
browsers. (This is to help well-intentioned people avoid accidental copying that
doesn't comply with the license.)

Apache header:

    Copyright 2022 Google LLC

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        https://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

[ADC]: https://developers.google.com/identity/protocols/application-default-credentials
[auth_command]: https://cloud.google.com/sdk/gcloud/reference/beta/auth/application-default/login
[java-11-badge]:
https://storage.googleapis.com/cloud-devrel-kokoro-resources/java/badges/java-docs-samples-11.svg
[java-11-link]:
https://storage.googleapis.com/cloud-devrel-kokoro-resources/java/badges/java-docs-samples-11.html
[java-17-badge]:
https://storage.googleapis.com/cloud-devrel-kokoro-resources/java/badges/java-docs-samples-17.svg
[java-17-link]:
https://storage.googleapis.com/cloud-devrel-kokoro-resources/java/badges/java-docs-samples-17.html
[java-21-badge]:
https://storage.googleapis.com/cloud-devrel-kokoro-resources/java/badges/java-docs-samples-21.svg
[java-21-link]:
https://storage.googleapis.com/cloud-devrel-kokoro-resources/java/badges/java-docs-samples-21.html

Java is a registered trademark of Oracle and/or its affiliates.


# FAF Client
[![Checks](https://github.com/FAForever/downlords-faf-client/actions/workflows/checks.yml/badge.svg?branch=develop)](https://github.com/FAForever/downlords-faf-client/actions/workflows/checks.yml)
[![Coverage Status](https://coveralls.io/repos/github/FAForever/downlords-faf-client/badge.svg?branch=develop)](https://coveralls.io/github/FAForever/downlords-faf-client?branch=develop)

The official client for [Forged Alliance Forever (FAF)](https://www.faforever.com/)

## Support Development

Post a bounty on Issue Hunt. You can reward and financially help developers that solve the issue. For new features, it can be helpful to first ask whether other people also see your change as an improvement. This helps avoid feature requests that will not be accepted.

[![Issue hunt](https://github.com/BoostIO/issuehunt-materials/raw/master/v1/issuehunt-button-v1.svg?sanitize=true)](https://issuehunt.io/r/FAForever/downlords-faf-client)

## How To Run
1. Use [Temurin](https://adoptium.net/) 21 or Oracle JDK 21 (others might not work)
1. Clone the project with Git
    - using SSH: `git clone git@github.com:FAForever/downlords-faf-client.git`
    - using HTTPS: `https://github.com/FAForever/downlords-faf-client.git`
1. Open the project into [IntelliJ IDEA](https://www.jetbrains.com/idea/) Ultimate or Community (free)
1. Make sure you have `Enable annotation processing` enabled in the settings
1. Select `Main` as run configuration next to the hammer button in the top right
1. Compile and start the application by pressing the play button

A video tutorial is available [here](https://youtu.be/6gsHnt02I_Y). Don't forget to `Enable annotation processing`.

### Linux
Learn how to install the client on Linux [here](https://github.com/FAForever/downlords-faf-client/wiki/Install-on-Linux).

## Open Source Licenses
|                                                                                |                                                                                |
|----------------|-------------------------------|
|                                              | Thanks to [ej-technologies](https://www.ej-technologies.com) for their [open source license](https://www.ej-technologies.com/buy/install4j/openSource). We use Install4j to build installers. |
|            | Thanks to [bugsnag](https://www.bugsnag.com) for their [open source license](https://www.bugsnag.com/open-source/). We use bugsnag for our error reporting.                                   |
|| Thanks to [YourKit](https://www.yourkit.com) for their open source license.|
|  | Thanks to [Twemoji Twitter](https://twemoji.twitter.com/) for their open source license. We use and display emojis in the chats.                                                              |

## Contribute
Please take a look at the [contribution guidelines](https://github.com/FAForever/java-guidelines/wiki/Contribution-Guidelines) before creating a pull request.

Have a look at our [wiki](https://github.com/FAForever/downlords-faf-client/wiki).


# ReCiter
![Build Status](https://codebuild.us-east-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiVWFoRUNZQzBqMkJpTGQ4MHNNbUJkclE4OTRVV0Y0SzJBVTBVMmV5NVhyNUdpbXVDblkrcWZkWU9SQWFxV0dUand4d05iVFFlT0Z0bWJsamM1SnRaUFdFPSIsIml2UGFyYW1ldGVyU3BlYyI6ImkzMndTalROWWlXUC8yRW4iLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=master)
![version](https://img.shields.io/badge/version-1.0-blue.svg?maxAge=2592000)
[![codebeat badge](https://codebeat.co/badges/9845c96b-ed87-4b1a-b62c-1e0e8b51bbb8)](https://codebeat.co/projects/github-com-wcmc-its-reciter-master)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
[![Pending Pull-Requests](https://img.shields.io/github/issues-pr-raw/wcmc-its/reciter.svg?color=blue)](https://github.com/wcmc-its/ReCiter/pulls)
[![Closed Pull-Requests](https://img.shields.io/github/issues-pr-closed-raw/wcmc-its/reciter.svg?color=blue)](https://github.com/wcmc-its/ReCiter/pulls)
[![GitHub issues open](https://img.shields.io/github/issues-raw/wcmc-its/reciter.svg?maxAge=2592000)](https://github.com/wcmc-its/ReCiter/issues)
[![GitHub issues closed](https://img.shields.io/github/issues-closed-raw/wcmc-its/reciter.svg?maxAge=2592000)](https://github.com/wcmc-its/ReCiter/issues)
[![Tags](https://img.shields.io/github/tag/wcmc-its/reciter.svg?style=social)](https://github.com/wcmc-its/ReCiter/releases)
[![Github All Releases](https://img.shields.io/github/downloads/wcmc-its/ReCiter/total.svg)]()

- [Purpose](#purpose)
- [Technical](#technical)
  - [Prerequisites](#prerequisites)
  - [Technological stack](#technological-stack)
  - [Architecture](#architecture)
  - [Related code repositories](#related-code-repositories)
- [Installation](#installation)
  - [Local](#local)
  - [Amazon AWS](#amazon-aws)
- [Configuration](#configuration)
- [Functionality](#functionality)
  - [How ReCiter works](#how-reciter-works)
  - [Using the APIs](#using-the-apis)
  - [See also](#see-also)
- [Future work](#future-work)
- [Funding acknowledgment](#funding-acknowledgment)
- [Follow up](#follow-up)

![https://github.com/wcmc-its/ReCiter/blob/master/files/howreciterworks.png](https://github.com/wcmc-its/ReCiter/blob/master/files/howreciterworks.png)

## Purpose

ReCiter is a highly accurate system for guessing which publications in PubMed a given person has authored. ReCiter includes a Java application, a DynamoDB-hosted database, and a set of RESTful microservices which collectively allow institutions to maintain accurate and up-to-date author publication lists for thousands of people. This software is optimized for disambiguating authorship in PubMed and, optionally, Scopus.

ReCiter accurately identifies articles, including those at previous affiliations, by a given person. It does this by leveraging institutionally maintained identity data (e.g., departments, relationships, email addresses, year of degree, etc.) With the more complete and efficient searches that result from combining these types of data, you can save time and your institution can be more productive. If you run ReCiter daily, you can ensure that the desired users are the first to learn when a new publication has appeared in PubMed.

ReCiter is fast. It uses an advanced multi-threading strategy known as a [work stealing pool](https://en.wikipedia.org/wiki/Work_stealing) to make up to 10 retrieval requests at a time.

ReCiter is freely available and open source under the [Apache 2.0 license](https://opensource.org/licenses/Apache-2.0).

Please see the [ReCiter wiki](https://github.com/wcmc-its/ReCiter/wiki) for more information.

![https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-FeatureGenerator.gif](https://github.com/wcmc-its/ReCiter/blob/master/files/ReCiter-FeatureGenerator.gif)

## Technical

### Prerequisites
- Java 11
- Latest version of Maven. To install Maven navigate to the directory where ReCiter will be installed, execute `brew install maven` and then `mvn clean install`

If you want to use Java 8 then update `<java.version>1.8</java.version>` in [pom.xml](https://github.com/wcmc-its/ReCiter/blob/a3d5d4665e8692853ca69f2db0caba0eb56f557d/pom.xml#L49)

It is not necessary to install ReCiter in order to use the API.

### Technological stack
Key technologies include:
- ReCiter stores data about researchers and publications in **DynamoDB**, which can be hosted on Amazon AWS or installed locally.
- Its main computation logic is written in **Java**.
- It employs the **Spring Framework**, a Java-based application framework designed to manage RESTful web services and server requests.
- ReCiter uses **Swagger**, a toolset that provides a user interface with helpful cues for how to interact with the application's RESTful APIs.

You may choose to run ReCiter on either:
- **A server** - ReCiter will run on Linux, Mac OS X, and Windows versions 7 and higher. A minimum of 4GB of RAM is required; 16GB of RAM are recommended. An Internet connection is required to download article data from scholarly databases.
- **A local machine** - ReCiter's APIs may be run in a browser on any modern machine. The ReCiter server must be accessible to the local machine via a local area network or internet connection.

### Architecture

![https://github.com/wcmc-its/ReCiter/blob/master/files/ArchitecturalDiagram-NEW.png](https://github.com/wcmc-its/ReCiter/blob/master/files/ArchitecturalDiagram-NEW.png)

### Related code repositories

The ReCiter application depends on the following separate GitHub-hosted repositories:

- **[PubMed Retrieval Tool](https://github.com/wcmc-its/ReCiter-PubMed-Retrieval-Tool)**
- **[Scopus Retrieval Tool](https://github.com/wcmc-its/ReCiter-Scopus-Retrieval-Tool)** (optional)
- **Data models:**
  - [ReCiter-Identity-Model](https://github.com/wcmc-its/ReCiter-Identity-Model)
  - [ReCiter-Scopus-Model](https://github.com/wcmc-its/ReCiter-Scopus-Model)
  - [ReCiter-Article-Model](https://github.com/wcmc-its/ReCiter-Article-Model)
  - [ReCiter-Dynamodb-Model](https://github.com/wcmc-its/ReCiter-Dynamodb-Model)
  - [ReCiter-PubMed-Model](https://github.com/wcmc-its/ReCiter-PubMed-Model)

Optionally, users can install:
- [ReCiter Publication Manager](https://github.com/wcmc-its/ReCiter-Publication-Manager) - a powerful user interface / web application that streamlines the process of updating and reporting on the publications of an institution's scholars
- [ReCiterDB](https://github.com/wcmc-its/ReCiterDB) - the back end data store for Publication Manager; in addition to the schema and stored procedures, this repository contains a set of scripts that retrieve data from ReCiter and imports them into this MySQL database

## Installation

ReCiter can be installed to run locally or in AWS via a cloud formation template. A required dependency is the [PubMed Retrieval Tool](https://github.com/wcmc-its/ReCiter-PubMed-Retrieval-Tool/). The [Scopus Retrieval Tool](https://github.com/wcmc-its/ReCiter-Scopus-Retrieval-Tool/) is optional, but can improve overall accuracy by several percent.

### Local

1. Clone the repository to a local folder using `git clone https://github.com/wcmc-its/ReCiter.git`
2. Go to the folder where the repository has been cloned and navigate to src/main/resources/application.properties and change port and log location accordingly
- change `aws.DynamoDb.local=false` to `aws.DynamoDb.local=true`
- update location of DynamoDB database, e.g., `aws.DynamoDb.local.dbpath=/Users/Paul/Documents/ReCiter/dynamodb_local_latest`
- By default application security is turned on. If you wish to turn it off you must change the flag to false from `spring.security.enabled=true` to `spring.security.enabled=false`
- If you have the security as true you must include the following environment variables -
```
export ADMIN_API_KEY=<api-key>
export CONSUMER_API_KEY=<api-key>
```
- If you do not have scopus subscription you should mark this value to false. Change `use.scopus.articles=true` to `use.scopus.articles=false`.
3. Enter ports for server and services in command line. Note that the Scopus service is optional. You must have [Pubmed Service](https://github.com/wcmc-its/ReCiter-PubMed-Retrieval-Tool/) and optionally [Scopus Service](https://github.com/wcmc-its/ReCiter-Scopus-Retrieval-Tool/) setup before this step. Enter appropriate hostname and the port numbers.
```
export SERVER_PORT=5000
export SCOPUS_SERVICE=http://localhost:5001
export PUBMED_SERVICE=http://localhost:5002
```
4. Run `mvn spring-boot:run`. You can add additional options if you want like max and min java memory with `export MAVEN_OPTS=-Xmx1024m`
5. Go to `http://localhost:<port-number>/swagger-ui/index.html` or `http://localhost:<port-number>/swagger-ui/` (shorthand swagger url)  to test and run any API.

### Amazon AWS

The [ReCiter CDK](
https://github.com/wcmc-its/ReCiter-CDK) allows to install the entire infrastructure for ReCiter and its components and its highly configurable. There you will find instruction to install ReCiter and its components.

## Configuration

- **[PubMed API key](https://github.com/wcmc-its/ReCiter-PubMed-Retrieval-Tool/blob/master/README.md#configuring-the-api-key)** - Recommended for performance reasons and to prevent and limit the likelihood National Library of Medicine will throttle you, but otherwise not necessary.
- **[Scopus API key and instoken](https://github.com/wcmc-its/ReCiter-Scopus-Retrieval-Tool/blob/master/README.md#configuring-api-key)** - Use of Scopus is optional. It can improve overall accuracy by several percent; Scopus is helpful because it has disambiguated organizational affiliation and verbose first name, especially for earlier articles. Use of the Scopus API is available only for Scopus subscribers.
- **[Security](https://github.com/wcmc-its/ReCiter/wiki/Implementing-security)** - Each of ReCiter's APIs can be configured to restrict access to only those requests which provide the correct API key.
- **[Application.properties](https://github.com/wcmc-its/ReCiter/wiki/Configuring-application.properties)** - All remaining configurations are stored here.

## Functionality

### How ReCiter works

The wiki article, [How ReCiter works](https://github.com/wcmc-its/ReCiter/wiki/How-ReCiter-works), contains a more detailed description on the application works.

 - Populate identity information for target users
 - Optional: populate Gold Standard of already accepted or rejected publications; note that this system currently does not offer a user interface for collecting this feedback
 - Lookup candidate articles in PubMed and, optionally, Scopus
 - Compute suggestions
 - Retrieve suggestions

### Using the APIs

The wiki article, [Using the APIs](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs), contains a full description on how to use the ReCiter APIs.

|Category |Function |Relevant API(s) |
| ---- | ------------- | ------------- |
|Manage identity of target users | Add or update identity data for target user(s) from Identity table | [`/reciter/identity/`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#reciteridentity) or [`/reciter/save/identities/`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#recitersaveidentities) |
|Manage identity of target users | Retrieve identity data for target user(s) from Identity table | [`/reciter/find/identity/by/uid/`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#reciterfindidentitybyuid) or [`/reciter/find/identity/by/uids/`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#reciterfindidentitybyuids) or [`/reciter/find/all/identity`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#reciterfindallidentity) |
|Gold standard | Update the GoldStandard table (includes both accepted and rejected PMIDs) for single user | [`/reciter/goldstandard/`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs##recitergoldstandard-post) |
|Gold standard | Update the GoldStandard table (includes both accepted and rejected PMIDs) for mutliple users | [`/reciter/goldstandard/`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs##recitergoldstandard-put) |
|Gold standard | Read from the GoldStandard table (includes both accepted and rejected PMIDs) for target user(s) | [`/reciter/goldstandard/{uid}`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#recitergoldstandarduid)  |
| Look up candidate articles | Trigger look up of candidate articles for a given user | [`/reciter/retrieve/articles/by/uid`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#reciterretrievearticlesbyuid)  |
| Retrieve suggested articles  | Read suggested articles from the Analysis table for target user | [`/reciter/article-retrieval/by/uid`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#reciterarticle-retrievalbyuid)   |
| Retrieve suggested articles | Read suggested articles and see supporting evidence from the Analysis table for target user(s) | [`/reciter/feature-generator/by/uid`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#reciterfeature-generatorbyuid) or [`/reciter/feature-generator/by/group`](https://github.com/wcmc-its/ReCiter/wiki/Using-the-APIs#reciterfeature-generatorbygroup)  |

### See also

- [PubMed Retrieval Tool](https://github.com/wcmc-its/ReCiter-PubMed-Retrieval-Tool) - contains several ways you can search PubMed
- [Scopus Retrieval Tool](https://github.com/wcmc-its/ReCiter-Scopus-Retrieval-Tool) - contains several ways you can search Scopus

## Published articles

- Albert PJ, Dutta S, Lin J, Zhu Z, Bales M, Johnson SB, Mansour M, Wright D, Wheeler TR, Cole CL. (2021) ReCiter: An open source, identity-driven, authorship prediction algorithm optimized for academic institutions. PLoS ONE 16(4): e0244641. [https://doi.org/10.1371/journal.pone.0244641](https://doi.org/10.1371/journal.pone.0244641)

![https://github.com/wcmc-its/ReCiter/blob/master/files/plosone.png](https://github.com/wcmc-its/ReCiter/blob/master/files/plosone.png)

## Future work

Both the issue queue and the [Roadmap](https://github.com/wcmc-its/ReCiter/wiki/Roadmap) include some areas where we want to improve ReCiter.

## Funding acknowledgment

Various components in the ReCiter suite of applications has been funded by:
- The National Institutes of Health National Center for Advancing Translational Sciences through grant number UL1TR002384
- National Library of Medicine, National Institutes of Health under a cooperative agreement with Region 7
- Lyrasis through its Catalyst fund

## Follow up

Please submit any questions to [Paul Albert](mailto:paa2013@med.cornell.edu). You may expect a response within one to two business days.

We use GitHub issues to track bugs and feature requests. If you find a bug, please feel free to open an issue.

Contributions welcome!


# EqualsVerifier

[![Apache License 2.0](https://img.shields.io/:license-Apache%20License%202.0-blue.svg?style=shield)](https://github.com/jqno/equalsverifier/blob/master/LICENSE.md)
[![Maven Central](https://img.shields.io/maven-central/v/nl.jqno.equalsverifier/equalsverifier.svg?style=shield)](https://maven-badges.herokuapp.com/maven-central/nl.jqno.equalsverifier/equalsverifier/)
[![Javadoc](https://javadoc.io/badge/nl.jqno.equalsverifier/equalsverifier.svg?color=blue)](https://javadoc.io/doc/nl.jqno.equalsverifier/equalsverifier)

[![Build Status](https://github.com/jqno/equalsverifier/workflows/CI/badge.svg)](https://github.com/jqno/equalsverifier/actions)
[![SemVer stability](https://api.dependabot.com/badges/compatibility_score?dependency-name=nl.jqno.equalsverifier:equalsverifier&package-manager=maven&version-scheme=semver)](https://dependabot.com/compatibility-score/?dependency-name=nl.jqno.equalsverifier:equalsverifier&package-manager=maven&version-scheme=semver)
[![Issue resolution](https://isitmaintained.com/badge/resolution/jqno/equalsverifier.svg)](https://isitmaintained.com/project/jqno/equalsverifier "Average time to resolve an issue")

**EqualsVerifier** can be used in Java unit tests to verify whether the contract for the equals and hashCode methods in a class is met.

# Getting Started

EqualsVerifier's Maven coordinates are:

```xml
<dependency>
    <groupId>nl.jqno.equalsverifier</groupId>
    <artifactId>equalsverifier</artifactId>
    <version>3.16.1</version>
    <scope>test</scope>
</dependency>
```

(Note that there's also a 'fat' jar with no transitive dependencies with artifactId `equalsverifier-nodep`.)

Now you can write a test:

```java
import nl.jqno.equalsverifier.*;

@Test
public void equalsContract() {
    EqualsVerifier.forClass(Foo.class).verify();
}
```

EqualsVerifier is an opinionated library, which means that it can be quite strict. If you feel it's too much, you can make it more lenient:

```java
import nl.jqno.equalsverifier.*;

@Test
public void equalsContract() {
    EqualsVerifier.simple().forClass(Foo.class).verify();
}
```

This way, EqualsVerifier will throw less errors at you. However, it's usually better to just fix the errors: EqualsVerifier throws them for a reason!

For more information, please see the [project's website](https://www.jqno.nl/equalsverifier).

## Prefer to watch a short video?

[![EqualsVerifier getting started video by Tom Cools](video.png)](http://www.youtube.com/watch?v=ivRjf8yvVMk "Video Title")

<small>Video by [Tom Cools](https://twitter.com/TCoolsIT)</small>

# A note on equality

EqualsVerifier cares about bug-free equality, in Java and in real life. The place where a person happens to be born, the colour of their skin, their gender, or the person they happen to love, must not affect the way they are treated in life. If it does, that's a bug and it should throw an error.

Don't allow bugs in your equality.

🌈🧑🏻🤝🧑🏾🌍

# Contribution

Pull requests are welcome! If you plan to open one, please also [register an issue](https://code.google.com/p/equalsverifier/issues/list) or [send a message to the Google Group](https://groups.google.com/forum/?fromgroups#!forum/equalsverifier), so we can discuss it first. It would be a shame to put in a lot of work on something that isn't a good fit for the project. Also, I can help you by giving pointers on where to find certain things.

# Development

## Build

To build EqualsVerifier, you need [Maven](https://maven.apache.org/). Just call `mvn` from the command-line, without any parameters, and you're done. Alternatively, you can use any IDE with Maven support.

There are several Maven profiles that can be enabled or disabled:

| profile                | activation                                                             | purpose                                                                                |
| ---------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `modules-jdk8`         | JDK 8 up to but not including 11                                       | Build only the modules that are compatible with Java 8 and up.                                                                                |
| `modules-jdk11`        | JDK 11 up to but not including 16                                      | Build only the modules that are compatible with Java 11 and up.                                                                                |
| `modules-jdk16`        | JDK 16                                                                 | Build only the modules that are compatible with Java 16 and up.                                                                                |
| `modules-jdk17`        | JDK 17 and up                                                          | Build all modules and build releaseable artifacts.                                                                                |
| `static-analysis`      | JDK 17 and up, _and_ `disableStaticAnalysis` property must be off      | Run static analysis checks. This only happens on a recent JDK. Can be disabled by running `mvn verify -DdisableStaticAnalysis`                                 |
| `release-verification` | JDK 17 and up, _and_ `disableReleaseVerification` property must be off | Run release verification checks. This only happens on a recent JDK. Can be disabled by running `mvn verify -DdisableReleaseVerification`                       |
| `argline-preview`      | `preview` property must be on                                          | Enable Java preview features. Can be activated by running `mvn verify -Dpreview`                                                                               |
| `argline-experimental` | `experimental` property must be on                                     | Enables ByteBuddy experimental features; useful for testing EqualsVerifier on Early Access JDK builds. Can be activated by running `mvn verify -Dexperimental` |
| `pitest`               | `pitest` property must be on                                           | Used by PITest integration on GitHub. Can be activated by running `mvn verify -Dpitest`                                                                        |

## Formatting

EqualsVerifier uses [Prettier-Java](https://github.com/jhipster/prettier-java) through [prettier-maven-plugin](https://github.com/HubSpot/prettier-maven-plugin) to format Java files. You can call it using `mvn clean verify`, or run `mvn prettier:write` to only run the formatter.

## Modules

This project is a multi-module project to make it easier to deal with shading and multi-release jar files. See [this question on StackOverflow](https://stackoverflow.com/q/70541340/127863) for the rationale behind it.

Here's a description of the modules:

| module                        | purpose                                                               |
| ----------------------------- | --------------------------------------------------------------------- |
| docs                          | project's Jekyll website                                              |
| equalsverifier-core           | the actual EqualsVerifier code                                        |
| equalsverifier-11             | tests for Java 11 and up                                              |
| equalsverifier-16             | logic for records, and corresponding tests                            |
| equalsverifier-17             | logic for sealed classes, and corresponding tests                     |
| equalsverifier-21             | tests for record pattern matching                                     |
| equalsverifier-aggregator     | generic release assembly description, and shared jacoco configuration |
| equalsverifier-release-main   | release assembly for jar with dependencies                            |
| equalsverifier-release-nodep  | release assembly for fat jar (with dependencies shaded in)            |
| equalsverifier-release-verify | validation tests for the releases                                     |

## Signed JAR

The `lib/` folder in the `equalsverifier-test-core` module contains a local Maven repository containing a signed JAR, used to test potential ClassLoader issues. Here's how to install a JAR into it:

```sh
mvn org.apache.maven.plugins:maven-install-plugin:2.3.1:install-file \
                        -Dfile=<path-to-file> -DgroupId=<myGroup> \
                        -DartifactId=<myArtifactId> -Dversion=<myVersion> \
                        -Dpackaging=<myPackaging> -DcreateChecksum=true \
                        -DlocalRepositoryPath=equalsverifier-test-core/lib
```

The signed JAR itself can be found in [this repo](https://github.com/jqno/equalsverifier-signedjar-test).

## Website

To generate the website

-   Using Docker: start the server by running `docker-compose up` or `docker compose run jekyll serve`.
-   Using Jekyll: install the Ruby 3.x toolchain and run `bundle exec jekyll serve --watch`

Note that thepage uses the [TilburgsAns](https://www.tilburgsans.nl/) font but references it from the main site at [jqno.nl](https://jqno.nl). In development, it will fall back to a `sans-serif` font. See the font license [here](assets/tilburgsans/Ans%20Font%20License-AFL.pdf).

# Disclaimer

Copyright 2009-2024 Jan Ouwens


# react-native-video
🎬 `<Video>` component for React Native

> **Note:** version 5.2.1 won't have any updates. We are currently working on making a 6.0.0 fully stable

## Documentation
documentation is available at [react-native-video.github.io/react-native-video](https://react-native-video.github.io/react-native-video/)

> if you find some issue with new version, don't hesitate to open a ticket! Also Old version can be found [here](https://github.com/react-native-video/react-native-video/tree/v6.0.0-alpha.8)

## Usage

```javascript
// Load the module

import Video, {VideoRef} from 'react-native-video';

// Within your render function, assuming you have a file called
// "background.mp4" in your project. You can include multiple videos
// on a single screen if you like.

const VideoPlayer = () => {
 const videoRef = useRef<VideoRef>(null);
 const background = require('./background.mp4');

 return (
   <Video
    // Can be a URL or a local file.
    source={background}
    // Store reference
    ref={videoRef}
    // Callback when remote video is buffering
    onBuffer={onBuffer}
    // Callback when video cannot be loaded
    onError={onError}
    style={styles.backgroundVideo}
   />
 )
}

// Later on in your styles..
var styles = StyleSheet.create({
  backgroundVideo: {
    position: 'absolute',
    top: 0,
    left: 0,
    bottom: 0,
    right: 0,
  },
});
```

## Community support
We have an discord server where you can ask questions and get help. [Join the discord server](https://discord.gg/WXuM4Tgb9X)

## Enterprise Support

  📱 react-native-video is provided as it is. For enterprise support or other business inquiries, please contact us 🤝. We can help you with the integration, customization and maintenance. We are providing both free and commercial support for this project. let's build something awesome together! 🚀

  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/baners/twg-dark.png" />
    <source media="(prefers-color-scheme: light)" srcset="./docs/assets/baners/twg-light.png" />

  </picture>


[![CircleCI](https://circleci.com/gh/dockstore/dockstore.svg?style=svg)](https://circleci.com/gh/dockstore/dockstore)
[![codecov](https://codecov.io/gh/dockstore/dockstore/branch/develop/graph/badge.svg)](https://codecov.io/gh/dockstore/dockstore)
[![Website](https://img.shields.io/website/https/dockstore.org.svg)](https://dockstore.org)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7259426.svg)](https://doi.org/10.5281/zenodo.7259426)
[![Uptime Robot status](https://img.shields.io/uptimerobot/status/m779655940-a297af07d1cac2d6ad40c491.svg)]()
[![license](https://img.shields.io/hexpm/l/plug.svg?maxAge=2592000)](LICENSE)
[![Documentation Status](https://readthedocs.org/projects/dockstore/badge/?version=stable)](https://dockstore.readthedocs.io/en/stable/?badge=stable)

# Dockstore

Dockstore provides a place for users to share tools encapsulated in Docker and described with the Common
Workflow Language (CWL), WDL (Workflow Description Language), Nextflow, or Galaxy. This enables scientists to share analytical
workflows so that they are  machine readable as well as runnable in a variety of environments. While the
Dockstore is focused on serving researchers in the biosciences, the combination of Docker + workflow languages can be used by
anyone to describe the tools and services in their Docker images in a standardized, machine-readable way.
Dockstore is also a leading implementor of the GA4GH API standard for container registries, [TRS](https://www.ga4gh.org/news/tool-registry-service-api-enabling-an-interoperable-library-of-genomics-analysis-tools/). The usage of this is to enumerate the docker containers
(from quay.io and docker hub) and the workflows (from github/bitbucket/local) that are available
to users of Dockstore.org.

For the live site see [dockstore.org](https://dockstore.org)

This repo contains the web service component for Dockstore as well as collecting issues for the project as a whole.

For the related web UI see the [dockstore-ui](https://github.com/dockstore/dockstore-ui2) project.
For the related CLI see the [cli](https://github.com/dockstore/cli) project.

## For Dockstore Users

The following section is useful for users of Dockstore (e.g. those that want to browse, register, and
launch tools).

After registering at [dockstore.org](https://dockstore.org), you will be able to download the Dockstore
CLI at https://dockstore.org/onboarding

### Configuration File

A basic Dockstore configuration file is available/should be created in `~/.dockstore/config` and contains the following
at minimum:
```
token = <your token generated by the dockstore site>
server-url = https://www.dockstore.org/api
```

## For Dockstore Developers

The following section is useful for Dockstore developers (e.g. those that want to improve or fix the Dockstore web service and UI)

### Dependencies

The dependency environment for Dockstore is described by our
[CircleCI config](https://github.com/dockstore/dockstore/blob/develop/.circleci/config.yml) or [docker compose](docker-compose.yml). In addition to the dependencies for
Dockstore users, note the setup instructions for postgres. Specifically, you will need to have postgres installed
and setup with the database user specified in [.circleci/config.yml](https://github.com/dockstore/dockstore/blob/1.11.10/.circleci/config.yml#L279) (ideally, postgres is needed only for integration tests but not unit tests).

### Building

As an alternative to the following commands, if you do not have Maven installed you can use the maven wrapper as a substitute. For example:

    ./mvnw clean install
    # instead of
    mvn clean install

If you maven build in the root directory this will build all modules:

    mvn clean install
    # or
    mvn clean install -Punit-tests

Consider the following if you need to build a specific version (such as in preparation for creating a tag for a release):

    mvnw clean install  -Dchangelist=.0-beta.5 #or whatever version you need

If you're running tests on CircleCI (or otherwise have access to the confidential data bundle) Run them via:

    mvn clean install -Pintegration-tests

There are also certain categories for tests that they can be added to when writing new tests.
Categories include:

1. `ToilCompatibleTest` are tests that can be run with our default cwltool and with Toil
2. `ConfidentialTest` are tests that require access to our confidential testing bundle (ask a member of the development team if you're on the team)

### Running Locally

You can also run it on your local computer but will need to setup postgres separately.

1. Fill in the template dockstore.yml and stash it somewhere outside the git repo (like ~/.dockstore)
2. The dockstore.yml is mostly a standard [Dropwizard configuration file](https://www.dropwizard.io/en/release-2.0.x/manual/configuration.html).
Refer to the linked document to setup httpClient and database.
3. Start with `java -jar dockstore-webservice/target/dockstore-webservice-*.jar   server ~/.dockstore/dockstore.yml`
4. If you need integration with GitHub.com, Quay.io. or Bitbucket for your work, you will need to follow the appropriate
sections below and then fill out the corresponding fields in your
[dockstore.yml](https://github.com/dockstore/dockstore/blob/develop/dockstore-integration-testing/src/test/resources/dockstore.yml).

One alternative if you prefer running things in containers would be using [docker-compose](docker-compose.yml)

### View Swagger UI

The Swagger UI is reachable while the Dockstore webservice is running. This allows you to explore available web resources.

1. Browse to [http://localhost:8080/static/swagger-ui/index.html](http://localhost:8080/static/swagger-ui/index.html)

### Commits using `[skipTests]`
If you would like to save build minutes on CircleCI (particularly for changes that do not affect code), consider adding
the `[skipTests]` tag to your commit message. When included in the most recent commit, a partial CI pipeline will be run,
consisting of only the build and unit tests.

`[skipTests]` acts as an alternative to `[skip ci]`, which is provided by CircleCI. This is because our automatic
deployment process requires a build to be run on every tag.

## Development

### Coding Standards

[codestyle.xml](codestyle.xml) defines the coding style for Dockstore as an IntelliJ Code Style XML file that should be imported into IntelliJ IDE.
We also have a matching [checkstyle.xml](checkstyle.xml) that can be imported into other IDEs and is run during the build.

For users of Intellij or comparable IDEs, we also suggest loading the checkstyle.xml with a plugin in order to display warnings and errors while coding live rather than encountering them later when running a build.

#### Installing git-secrets

Dockstore uses git-secrets to help make sure that keys and private data stay out
of the source tree. For information on installing it on your platform check <https://github.com/awslabs/git-secrets#id6> .

If you're on mac with homebrew use `brew install git-secrets`.

### Dockstore Command Line

The dockstore command line should be installed in a location in your path.

  /dockstore-client/bin/dockstore

You then need to setup a `~/.dockstore/config` file with the following contents:

```
token: <dockstore_token_from_web_app>
server-url: http://www.dockstore.org:8080
```

If you are working with a custom-built or updated dockstore client you will need to update the jar in: `~/.dockstore/config/self-installs`.

### Swagger Client Generation

We use the swagger-codegen-maven-plugin to generate several sections of code which are not checked in.
These include
1. All of swagger-java-client (talks to our webservice for the CLI via Swagger 2.0)
2. All of openapi-java-client (talks to our webservice for the CLI, but in OpenAPI 3.0)
3. The Tool Registry Server components (serves up the TRS endpoints)

To update these, you will need to point at a new version of the swagger.yaml provided by a service. For example, update the equivalent of [inputSpec](https://github.com/dockstore/dockstore/blob/0afe35682bdfb6fa7285b2acab8f80648346e835/dockstore-webservice/pom.xml#L854) in your branch.

### Encrypted Documents for CircleCI

Encrypted documents necessary for confidential testing are decrypted via [decrypt.sh](scripts/decrypt.sh) with access being granted to developers at UCSC and OICR.

A convenience script is provided as [encrypt.sh](encrypt.sh) which will compress confidential files, encrypt them, and then update an encrypted archive on GitHub. Confidential files should also be added to .gitignore to prevent accidental check-in. The unencrypted secrets.tar should be privately distributed among members of the team that need to work with confidential data. When using this script you will likely want to alter the [CUSTOM\_DIR\_NAME](https://github.com/dockstore/dockstore/blob/0b59791440af6e3d383d1aede1774c0675b50404/encrypt.sh#L13). This is necessary since running the script will overwrite the existing encryption keys, instantly breaking existing builds using that key. Our current workaround is to use a new directory when providing a new bundle.

### Adding Copyright header to all files with IntelliJ

To add copyright headers to all files with IntelliJ

1. Ensure the Copyright plugin is installed (Settings -> Plugins)
2. Create a new copyright profile matching existing copyright header found on all files, name it Dockstore (Settings -> Copyright -> Copyright Profiles -> Add New)
3. Set the default project copyright to Dockstore (Settings -> Copyright)

[//]: # (DO_NOT_DELETE_START_MACOS_INSTRUCTIONS: This section is automatically generated by scripts/macos-instructions.sh)
### Setting up a Mac for Dockstore development
Install Docker (Be sure to click on 'Mac with Apple chip' if you have Apple silicon)
https://docs.docker.com/desktop/mac/install/

Install Brew
https://brew.sh/
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

Run 'git' to trigger the install of Xcode or the Command Line Tools which will install and or update git
https://developer.apple.com/forums/thread/672087?answerId=659036022#659036022
```
git
```
_(If that doesn't work install git manually https://git-scm.com/download/mac)_

Setup git user information
```
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
```
[Read about git token requirements](https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/)

[Setup personal access token for git CLI](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)

[It's helpful to cache your git personal access token](https://docs.github.com/en/get-started/getting-started-with-git/caching-your-github-credentials-in-git)

Install Hubflow
https://datasift.github.io/gitflow/TheHubFlowTools.html
```
git clone https://github.com/datasift/gitflow
cd gitflow
sudo ./install.sh
```

Install JDK 17
https://formulae.brew.sh/formula/openjdk@17
```
brew install openjdk@17
```
Download and install node.js
https://github.com/nvm-sh/nvm
```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
```
Install git secrets
https://github.com/awslabs/git-secrets
```
brew install git-secrets
```
Install wget
```
brew install wget
```

Install jq
```
brew install jq
```
#### Build the webservice
(cd to where you cloned the dockstore/dockstore repo)
```
./mvnw clean install
```

#### Build the UI
(cd to where you cloned the dockstore/dockstore-ui2 repo)

Set up UI requirements
NOTE: You must use the --legacy-peer-deps switch due to using npm version 8.11.0 (> npm 6)
for reasons mentioned in [this post](https://stackoverflow.com/questions/66239691/what-does-npm-install-legacy-peer-deps-do-exactly-when-is-it-recommended-wh)
```
npm ci --legacy-peer-deps
```

Run build
```
npm run build
```
#### Optional
Install IntelliJ _(if on Apple Silicon, select the .dmg (Apple Silicon), otherwise select .dmg(Intel)_

https://www.jetbrains.com/idea/download/#section=mac

Add the Scala plugin to IntelliJ
https://www.jetbrains.com/help/idea/managing-plugins.html

[//]: # (DO_NOT_DELETE_END_MACOS_INSTRUCTIONS: This section is automatically generated by scripts/macos-instructions.sh)

### Database Schema Documentation

This is autogenerated at [https://dockstore.github.io/dockstore/](https://dockstore.github.io/dockstore/)

### Legacy Material

Additional documentation on developing Dockstore is available at [legacy.md](https://github.com/dockstore/dockstore/blob/develop/legacy.md)