# Google NIO Filesystem Provider for Google Cloud Storage Client for Java

Java idiomatic client for [NIO Filesystem Provider for Google Cloud Storage][product-docs].

[![Maven][maven-version-image]][maven-version-link]
![Stability][stability-image]

- [Product Documentation][product-docs]
- [Client Library Documentation][javadocs]

> Note: This client is a work-in-progress, and may occasionally
> make backwards-incompatible changes.

## Quickstart

If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file

```xml
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>22.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-nio</artifactId>
  </dependency>
</dependencies>

```

If you are using Maven without BOM, add this to your dependencies:

```xml
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-nio</artifactId>
  <version>0.123.10</version>
</dependency>

```

If you are using Gradle 5.x or later, add this to your dependencies

```Groovy
implementation platform('com.google.cloud:libraries-bom:23.0.0')

implementation 'com.google.cloud:google-cloud-nio'
```
If you are using Gradle without BOM, add this to your dependencies

```Groovy
implementation 'com.google.cloud:google-cloud-nio:0.123.10'
```

If you are using SBT, add this to your dependencies

```Scala
libraryDependencies += "com.google.cloud" % "google-cloud-nio" % "0.123.10"
```

## Authentication

See the [Authentication][authentication] section in the base directory's README.

## Authorization

The client application making API calls must be granted [authorization scopes][auth-scopes] required for the desired NIO Filesystem Provider for Google Cloud Storage APIs, and the authenticated principal must have the [IAM role(s)][predefined-iam-roles] required to access GCP resources using the NIO Filesystem Provider for Google Cloud Storage API calls.

## Getting Started

### Prerequisites

You will need a [Google Cloud Platform Console][developer-console] project with the NIO Filesystem Provider for Google Cloud Storage [API enabled][enable-api].

[Follow these instructions][create-project] to get your project set up. You will also need to set up the local development environment by
[installing the Google Cloud SDK][cloud-sdk] and running the following commands in command line:
`gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`.

### Installation and setup

You'll need to obtain the `google-cloud-nio` library.  See the [Quickstart](#quickstart) section
to add `google-cloud-nio` as a dependency in your code.

## About NIO Filesystem Provider for Google Cloud Storage

[NIO Filesystem Provider for Google Cloud Storage][product-docs] provides a Google Cloud Storage extension for Java's NIO Filesystem.

See the [NIO Filesystem Provider for Google Cloud Storage client library docs][javadocs] to learn how to
use this NIO Filesystem Provider for Google Cloud Storage Client Library.

#### About Google Cloud Storage

[Google Cloud Storage](https://cloud.google.com/storage/) is a durable and highly available
object storage service. Google Cloud Storage is almost infinitely scalable
and guarantees consistency: when a write succeeds, the latest copy of the
object will be returned to any GET, globally.

See the [Google Cloud Storage docs](https://cloud.google.com/storage/docs/signup?hl=en) for more details
on how to activate Cloud Storage for your project.

#### About Java NIO Providers

Java NIO Providers is an extension mechanism that is part of Java and allows
third parties to extend Java's [normal File API](https://docs.oracle.com/javase/7/docs/api/java/nio/file/Files.html) to support
additional filesystems.

#### Accessing files

The simplest way to get started is with `Paths` and `Files`:

```java
Path path = Paths.get(URI.create("gs://bucket/lolcat.csv"));
List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
```

If you know the paths will point to Google Cloud Storage, you can also use the
direct formulation:

```java
try (CloudStorageFileSystem fs = CloudStorageFileSystem.forBucket("bucket")) {
  Path path = fs.getPath("lolcat.csv");
  List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
}
```

Once you have a `Path` you can use it as you would a normal file. For example
you can use `InputStream` and `OutputStream` for streaming:

```java
try (InputStream input = Files.openInputStream(path)) {
  // ...
}
```

You can also set various attributes using CloudStorageOptions static helpers:

```java
Files.write(csvPath, csvLines, StandardCharsets.UTF_8,
    withMimeType(MediaType.CSV_UTF8),
    withoutCaching());
```

#### Limitations

This library is usable, but not yet complete. The following features are not
yet implemented:
 * Resuming upload or download
 * Generations
 * File attributes
 * (more - list is not exhaustive)

Some features are not on the roadmap: this library would be a poor choice to
mirror a local filesystem onto the cloud because Google Cloud Storage has a
different set of features from your local disk. This library, by design,
does not mask those differences. Rather, it aims to expose the common
subset via a familiar interface.

**NOTE:** Cloud Storage uses a flat namespace and therefore doesn't support real
directories. So this library supports what's known as "pseudo-directories". Any
path that includes a trailing slash, will be considered a directory. It will
always be assumed to exist, without performing any I/O. Paths without the trailing
slash will result in an I/O operation to check a file is present in that "directory".
This allows you to do path manipulation in the same manner as you would with the normal UNIX file
system implementation. Using this feature with buckets or "directory" paths that do not exist
is not recommended, as at the time I/O is performed the failure may not be handled gracefully.
You can disable this feature with `CloudStorageConfiguration.usePseudoDirectories()`.

#### Complete source code

There are examples in [google-cloud-nio-examples](google-cloud-nio-examples/src/main/java/com/google/cloud/examples/nio/)
for your perusal.

## Troubleshooting

To get help, follow the instructions in the [shared Troubleshooting document][troubleshooting].

## Supported Java Versions

Java 7 or above is required for using this client.

Google's Java client libraries,
[Google Cloud Client Libraries][cloudlibs]
and
[Google Cloud API Libraries][apilibs],
follow the
[Oracle Java SE support roadmap][oracle]
(see the Oracle Java SE Product Releases section).

### For new development

In general, new feature development occurs with support for the lowest Java
LTS version covered by  Oracle's Premier Support (which typically lasts 5 years
from initial General Availability). If the minimum required JVM for a given
library is changed, it is accompanied by a [semver][semver] major release.

Java 11 and (in September 2021) Java 17 are the best choices for new
development.

### Keeping production systems current

Google tests its client libraries with all current LTS versions covered by
Oracle's Extended Support (which typically lasts 8 years from initial
General Availability).

#### Legacy support

Google's client libraries support legacy versions of Java runtimes with long
term stable libraries that don't receive feature updates on a best efforts basis
as it may not be possible to backport all patches.

Google provides updates on a best efforts basis to apps that continue to use
Java 7, though apps might need to upgrade to current versions of the library
that supports their JVM.

#### Where to find specific information

The latest versions and the supported Java versions are identified on
the individual GitHub repository `github.com/GoogleAPIs/java-SERVICENAME`
and on [google-cloud-java][g-c-j].

## Versioning

This library follows [Semantic Versioning](http://semver.org/).

It is currently in major version zero (``0.y.z``), which means that anything may change at any time
and the public API should not be considered stable.

## Contributing

Contributions to this library are always welcome and highly encouraged.

See [CONTRIBUTING][contributing] for more information how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in
this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more
information.

## License

Apache 2.0 - See [LICENSE][license] for more information.

## CI Status

Java Version | Status
------------ | ------
Java 7 | [![Kokoro CI][kokoro-badge-image-1]][kokoro-badge-link-1]
Java 8 | [![Kokoro CI][kokoro-badge-image-2]][kokoro-badge-link-2]
Java 8 OSX | [![Kokoro CI][kokoro-badge-image-3]][kokoro-badge-link-3]
Java 8 Windows | [![Kokoro CI][kokoro-badge-image-4]][kokoro-badge-link-4]
Java 11 | [![Kokoro CI][kokoro-badge-image-5]][kokoro-badge-link-5]

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

[product-docs]: https://cloud.google.com/storage/docs
[javadocs]: https://googleapis.dev/java/google-cloud-nio/latest
[kokoro-badge-image-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java7.svg
[kokoro-badge-link-1]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java7.html
[kokoro-badge-image-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java8.svg
[kokoro-badge-link-2]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java8.html
[kokoro-badge-image-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java8-osx.svg
[kokoro-badge-link-3]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java8-osx.html
[kokoro-badge-image-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java8-win.svg
[kokoro-badge-link-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java8-win.html
[kokoro-badge-image-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java11.svg
[kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java11.html
[stability-image]: https://img.shields.io/badge/stability-beta-yellow
[maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-nio.svg
[maven-version-link]: https://search.maven.org/search?q=g:com.google.cloud%20AND%20a:google-cloud-nio&core=gav
[authentication]: https://github.com/googleapis/google-cloud-java#authentication
[auth-scopes]: https://developers.google.com/identity/protocols/oauth2/scopes
[predefined-iam-roles]: https://cloud.google.com/iam/docs/understanding-roles#predefined_roles
[iam-policy]: https://cloud.google.com/iam/docs/overview#cloud-iam-policy
[developer-console]: https://console.developers.google.com/
[create-project]: https://cloud.google.com/resource-manager/docs/creating-managing-projects
[cloud-sdk]: https://cloud.google.com/sdk/
[troubleshooting]: https://github.com/googleapis/google-cloud-common/blob/main/troubleshooting/readme.md#troubleshooting
[contributing]: https://github.com/googleapis/java-storage-nio/blob/main/CONTRIBUTING.md
[code-of-conduct]: https://github.com/googleapis/java-storage-nio/blob/main/CODE_OF_CONDUCT.md#contributor-code-of-conduct
[license]: https://github.com/googleapis/java-storage-nio/blob/main/LICENSE

[enable-api]: https://console.cloud.google.com/flows/enableapi?apiid=storage.googleapis.com
[libraries-bom]: https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM
[shell_img]: https://gstatic.com/cloudssh/images/open-btn.png

[semver]: https://semver.org/
[cloudlibs]: https://cloud.google.com/apis/docs/client-libraries-explained
[apilibs]: https://cloud.google.com/apis/docs/client-libraries-explained#google_api_client_libraries
[oracle]: https://www.oracle.com/java/technologies/java-se-support-roadmap.html
[g-c-j]: http://github.com/googleapis/google-cloud-java


# TAG: [Tabletop Games Framework](http://www.tabletopgames.ai/)

[![license](https://img.shields.io/github/license/GAIGResearch/TabletopGames)](LICENSE)
![top-language](https://img.shields.io/github/languages/top/GAIGResearch/TabletopGames)
![code-size](https://img.shields.io/github/languages/code-size/GAIGResearch/TabletopGames)
[![twitter](https://img.shields.io/twitter/follow/gameai_qmul?style=social)](https://twitter.com/intent/follow?screen_name=gameai_qmul)
[![](https://img.shields.io/github/stars/GAIGResearch/TabletopGames.svg?label=Stars&style=social)](https://github.com/GAIGResearch/TabletopGames)

The [Tabletop Games Framework (TAG)](http://tabletopgames.ai) is a Java-based benchmark for developing modern board games for AI research.  TAG provides a common skeleton for implementing tabletop games based on a common API for AI agents, a set of components and classes to easily add new games and an import module for defining data in JSON format. At present, this platform includes the implementation of seven different tabletop games that can also be used as an example for further developments. Additionally, TAG also incorporates logging functionality that allows the user to perform a detailed analysis of the game, in terms of action space, branching factor, hidden information, and other measures of interest for Game AI research.
![Pandemic](data/imgs/Pandemic.png)
*Example GUI for Pandemic*

## Games
Currently implemented games:
- [x] Battlelore: Second Edition (Richard Borg and Robert A Kouba, 2013)
- [x] Blackjack (Uncredited, circa 1700)
- [x] Can't Stop (Sid Sackson, 1980)
- [x] Colt Express (Christophe Raimbault, 2014)
- [x] Connect 4 (Ned Strongin and Howard Wexler, 1974)
- [x] Diamant (Bruno Faidutti and Alan R. Moon, 2005)
- [x] Dominion (Donald X. Vaccarino, 2008)
- [x] Dots and Boxes (Edouard Lucas, 1889)
- [x] Exploding Kittens (Inman and others, 2015)
- [x] Love Letter (Seiji Kanai, 2012)
- [x] Pandemic (Matt Leacock, 2008)
- [x] Poker Texas Hold'em (Uncredited, 1810)
- [x] Settlers of Catan (Klaus Teuber, 2008)
- [x] Stratego (Jacques Johan Mogendorff, 1946)
- [x] Terraforming Mars (Jacob Fryxelius, 2016)
- [x] Tic-Tac-Toe (Uncredited, Unknown)
- [x] Uno (Merle Robbins, 1971)
- [x] Virus! (Cabrero and others, 2015)

Games in progress:
- [ ] Descent (Jesper Ejsing, John Goodenough, Frank Walls 2005)
- [ ] Hanabi (Antoine Bauza 2010)
- [ ] 7 Wonders (Antoine Bauza 2010)

## Setting up
The project requires Java with minimum version 8. In order to run the code, you must either download the repository, or clone it. If you are looking for a particular release, you can find all listed [here](https://github.com/GAIGResearch/TabletopGames/releases).

The simplest way to run the code is to create a new project in [IntelliJ IDEA](https://www.jetbrains.com/idea/) or a similar IDE. In IntelliJ, create a new project from existing sources, pointing to the code downloaded or cloned and selecting the **Maven** framework for import. This process should automatically set up the environment and add any project libraries as well.

Alternatively, open the code directly in your IDE of choice, right click the pom.xml file and setup the project with the Maven framework. Make sure src/main/java is marked as sources root. You can run the `core.Game.java` class to test if all is set up properly and compiling. [This video](https://youtu.be/-U7SCGNOcsg) includes the steps of loading the project correctly in IntelliJ.

## Getting started

To get started the [website](http://tabletopgames.ai) provides various guides and descriptions of the framework.
Another good resource is our paper ["Design and Implementation of TAG: A Tabletop Games Framework"](https://arxiv.org/abs/2009.12065).

## Citing Information

To cite TAG in your work, please cite this paper:
```
@inproceedings{gaina2020tag,
         author= {Raluca D. Gaina and Martin Balla and Alexander Dockhorn and Raul Montoliu and Diego Perez-Liebana},
         title= {{TAG: A Tabletop Games Framework}},
         year= {2020},
         booktitle= {{Experimental AI in Games (EXAG), AIIDE 2020 Workshop}},
         abstract= {Tabletop games come in a variety of forms, including board games, card games, and dice games. In recent years, their complexity has considerably increased, with many components, rules that change dynamically through the game, diverse player roles, and a series of control parameters that influence a game's balance. As such, they also encompass novel and intricate challenges for Artificial Intelligence methods, yet research largely focuses on classical board games such as chess and Go. We introduce in this work the Tabletop Games (TAG) framework, which promotes research into general AI in modern tabletop games, facilitating the implementation of new games and AI players, while providing analytics to capture the complexities of the challenges proposed. We include preliminary results with sample AI players, showing some moderate success, with plenty of room for improvement, and discuss further developments and new research directions.},
    }
```

## Other Materials

### Visual materials
V1 – Edited programming video (see below)

V2 – Uncut programming video (see below)

V3 – PowerPoint slides: https://tinyurl.com/tag-exag-ppt

V5 – Transcript A1: https://tinyurl.com/tag-exag-tr1

V6 – Transcript A2: https://tinyurl.com/tag-exag-tr2

### Audio materials
A1 – Framework presentation (see below)

A2 – Programming (see below)

### Full videos available
EXAG 2020 presentation (A1 + V1): https://youtu.be/M81elk-NmKM

EXAG alternative presentation (A1 + V3): https://youtu.be/ST_2Q40pzjc

TAG introduction tutorial (A2 + V1): https://youtu.be/-U7SCGNOcsg

TAG full programming tutorial (V2): https://youtu.be/m7DAFdViywY

## Contact
The main method to contribute to our repository directly with code, or to suggest new features, point out bugs or ask questions about the project is through [creating new Issues on this github repository](https://github.com/GAIGResearch/TabletopGames/issues) or [creating new Pull Requests](https://github.com/GAIGResearch/TabletopGames/pulls). Alternatively, you may contact the authors of the papers listed above.

You can also find out more about the [QMUL Game AI Group](http://gameai.eecs.qmul.ac.uk/).

## Acknowledgements

This work was partly funded by the EPSRC CDT in Intelligent Games and Game Intelligence (IGGI)  EP/L015846/1 and EPSRC research grant EP/T008962/1.


# Java API for [Twitch](https://www.twitch.tv/)

Support:

[![Discord Server](https://discordapp.com/api/guilds/143001431388061696/embed.png?style=banner2)](https://discord.gg/FQ5vgW3)
[![Twitch API Server](https://discordapp.com/api/guilds/325552783787032576/embed.png?style=banner2)](https://discord.gg/8NXaEyV)

Badges:

[![Latest](https://img.shields.io/github/release/twitch4j/twitch4j/all.svg?style=flate&label=latest)](https://search.maven.org/search?q=g:com.github.twitch4j)
[![Docs](https://img.shields.io/badge/documentation-github%20pages-8A2BE2)](https://twitch4j.github.io/)
[![Javadoc](https://javadoc.io/badge/com.github.twitch4j/twitch4j.svg)](https://twitch4j.github.io/javadoc/)

--------

## A quick note:

This project implements client modules to interact with all of Twitch's APIs.

## Quick Start

Check out the [Documentation](https://twitch4j.github.io/getting-started/installation)!

--------

## Modules

**Project**

| Module             | Description                                  |
|--------------------|----------------------------------------------|
| chat               | Chat (IRC)                                   |
| eventsub-common    | EventSub (can be used for Webhook-Transport) |
| eventsub-websocket | EventSub (WebSocket & Conduits)              |
| helix              | REST-API                                     |
| pubsub             | PubSub                                       |
| graphql            | GraphQL (unofficial)                         |
| kotlin             | Kotlin Extensions                            |

**Shared**

| Module                                              | Description                        |
|-----------------------------------------------------|------------------------------------|
| [cache-api](https://github.com/Xanthic/cache-api)   | In-Memory Cache API                |
| [event4j](https://github.com/PhilippHeuer/events4j) | Event Publication and Subscription |

> The shared libraries offer standardized functionality in an abstracted manner, allowing you to select from a variety of implementations (or bring your own).

## Problems

If you have problems using the *Twitch Java API*, then you are welcome to join the [discord server](https://discord.gg/FQ5vgW3) to talk about it.

If you discover any issues/have feature requests, then please [open an issue here](https://github.com/twitch4j/twitch4j/issues/new).

## Contributing

We welcome contributions to the library, be it new features, bug fixes, or even small enhancements.
Please do read the [contributing guide](https://twitch4j.github.io/contribution/) on the documentation site as it provides code guidelines and helpful tips for getting started.
By contributing, you are expected to abide by our [code of conduct](https://github.com/twitch4j/.github/blob/main/CODE_OF_CONDUCT.md) and agree to the license below.
Thank you again for your interest in improving Twitch4J!

## License

Released under the [MIT license](./LICENSE).


# Ballerina Docker Extension

Annotation based docker extension implementation for ballerina.

![Daily build](https://github.com/ballerina-platform/module-ballerina-docker/workflows/Daily%20build/badge.svg)
![Build](https://github.com/ballerina-platform/module-ballerina-docker/actions/workflows/build-timestamped-master.yml/badge.svg)
![Trivy Scan](https://github.com/ballerina-platform/module-ballerina-docker/workflows/Trivy%20Docker%20Image%20Scan/badge.svg)
[![codecov](https://codecov.io/gh/ballerina-platform/module-ballerina-docker/branch/master/graph/badge.svg)](https://codecov.io/gh/ballerina-platform/module-ballerina-docker)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

## Features:
- Dockerfile generation.
- Docker image generation.
- Docker based ballerina debug support.
- Copy file support.

## How to run

### Prerequisites

1. Download and install JDK 17
1. Get a clone or download the source from [this repository](https://github.com/ballerina-platform/module-ballerina-docker).
1. Export github personal access token & user name as environment variables.
   ```bash
       export packagePAT=<Token>
       export packageUser=<username>
   ```
1. (optional) Specify the Java home path for JDK 17 ie;
    ```bash
        export JAVA_HOME=/Library/Java/JavaVirtualMachines/adoptopenjdk-17.jdk/Contents/Home/
    ```
1. (optional) Ensure Docker daemon is running (used for building tests).

### Building

1. Run the corresponding Gradle command from within the `module-ballerina-docker` directory.
```bash
#To build the module:
./gradlew clean build

#To build the module without the tests:
./gradlew clean build -x test
```
1. Copy `docker-extension/build/docker-generator-***.jar` file to `<BALLERINA_HOME>/bre/lib` directory.

### Enable building for Windows Platform
Use the "BAL_DOCKER_WINDOWS=true" environment variable to enable building docker images supporting Windows platform.

### Enabling debug logs
Use the "BAL_DOCKER_DEBUG=true" environment variable to enable docker related debug logs when building the ballerina
source file.


# Aurelium Skills
[![Release](https://jitpack.io/v/Archy-X/AureliumSkills.svg?style=flat-square)](https://jitpack.io/#Archy-X/AureliumSkills)

[![Downloads](https://badges.spiget.org/resources/downloads/Downloads-blue-81069.svg)](https://www.spigotmc.org/resources/81069/)
[![Rating](https://badges.spiget.org/resources/rating/Rating-blue-81069.svg)](https://www.spigotmc.org/resources/81069/)

AureliumSkills is an advanced, feature-rich skills, stats, and abilities plugin, great for a variety of server gamemodes.

Learn more and download here: https://www.spigotmc.org/resources/81069/

### Support Discord:

https://discord.gg/Bh2EZfB (Join for support/suggestions/discussion)

### Wiki
The AureliumSkills wiki can be viewed [here](https://wiki.aurelium.dev/skills).
The wiki contains documentation on how to use and configure the plugin. The wiki may not be always up to date.

## Developer API

Aurelium Skills provides a developer API to interact with the plugin.

### Maven
```xml
<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

<dependency>
    <groupId>com.github.Archy-X</groupId>
    <artifactId>AureliumSkills</artifactId>
    <version>{version}</version>
    <scope>provided</scope>
</dependency>
```

### Gradle
```gradle
repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.Archy-X:AureliumSkills:{version}'
}
```
**Replace `{version}` with the version of the plugin you are targeting**, see [releases](https://github.com/Archy-X/AureliumSkills/releases) for the most updated list of version names.

The main class to use for the API is AureliumAPI, which has many static methods for skills, xp, stats, and mana.
There are also a few events, including ManaRegenerateEvent, SkillLevelUpEvent, XpGainEvent, PlayerLootDropEvent, and ManaAbilityActivateEvent

## Contributing
Contributions are welcome! Open a pull request, and I will review it.


[![](https://img.shields.io/github/actions/workflow/status/TeamGalacticraft/Galacticraft/build.yml?style=flat-square&logo=github)](https://github.com/TeamGalacticraft/Galacticraft/actions/workflows/build.yml?query=branch%3Amain)
[![](https://img.shields.io/github/issues/TeamGalacticraft/Galacticraft?style=flat-square&logo=github)](https://github.com/TeamGalacticraft/Galacticraft/issues)
[![](https://img.shields.io/github/issues-pr/TeamGalacticraft/Galacticraft?logo=github&style=flat-square)](https://github.com/TeamGalacticraft/Galacticraft/pulls)
[![](https://img.shields.io/discord/775251052517523467.svg?colorB=5865F2&label=discord&style=flat-square&logo=discord&logoColor=azure)](https://discord.gg/n3QqhMYyFK)
[![](https://img.shields.io/twitch/status/galacticraftdev.svg?style=flat-square&logo=twitch&logoColor=azure)](https://twitch.tv/galacticraftdev)

# Galacticraft 5
The classic Minecraft space mod, rewritten from the ground up for modern versions of the game.

## Common Questions
Here we answer a few common questions we get regarding the release of the mod.\
More information can be found in the `#faq` channel in [our Discord](https://discord.gg/n3QqhMYyFK).

**When will Galacticraft 5 for 1.20+ be released?**\
There is currently no ETA for a release.
Keep an eye out on [our Discord server](https://discord.gg/n3QqhMYyFK) for an alpha release announcement.

**Will Galacticraft 5 be on Forge?**\
Yes, Forge development will start *after* we have a survival-playable alpha build out for Fabric.

**Will Galacticraft 5 work with Galacticraft 4 addons?**\
No, Galacticraft 5 is a complete rewrite, and does not have backwards compatibility with the old addon api.

## Pre-Alpha Builds
Pre-alpha builds are available for each commit to the `main` branch of this repository in the [Actions tab](https://github.com/TeamGalacticraft/Galacticraft/actions/workflows/build.yml?query=branch%3Amain) on GitHub.
These builds are not production ready or survival playable, they exist solely for testing.\
Please note that ***NO SUPPORT*** will be provided for the use of these builds and asking for such may result in a ban or mute,
consider this your one and only warning.

## Contributing
We welcome and encourage community contributions,
but before you start please read our [contributing guidelines](https://github.com/TeamGalacticraft/Galacticraft/blob/main/.github/CONTRIBUTING.md).\
Pull requests require at least one team member's approving review, and a successful build before they will be merged.


![logo300_mzmine.png](mzmine-community%2Flogo%2Flogo300_mzmine.png)

![GitHub all releases](https://img.shields.io/github/downloads/mzmine/mzmine3/total)
![GitHub all releases](https://img.shields.io/github/downloads/mzmine/mzmine3/latest/total)
![GitHub contributors](https://img.shields.io/github/contributors/mzmine/mzmine3)
[![Development Build Release](https://github.com/mzmine/mzmine3/actions/workflows/dev_build_release.yml/badge.svg)](https://github.com/mzmine/mzmine3/actions/workflows/dev_build_release.yml)
![Static Badge](https://img.shields.io/badge/JDK%20version-21-blue)
![Static Badge](https://img.shields.io/badge/JavaFX%20version-21-%2391219c)

mzmine is an open-source software for mass-spectrometry data processing. The goals of the project is
to provide a user-friendly, flexible and easily extendable software with a complete set of modules
covering the entire MS data analysis workflow.

More information about the software can be found on the [mzmine](http://mzmine.github.io) website.

Getting started with the [Documentation](https://mzmine.github.io/mzmine_documentation/index.html) and our [YouTube channel](https://www.youtube.com/@mzmineproject/playlists?view=1&sort=lad&flow=grid)

## License

mzmine is a free software; you can redistribute it and/or modify it under the terms of the MIT license.

mzmine is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## Releases

[Releases](https://github.com/mzmine/mzmine3/releases?q=&expanded=true) are split into [stable releases](https://github.com/mzmine/mzmine3/releases/latest)
and
the [latest development build](https://github.com/mzmine/mzmine3/releases/tag/Development-release)
which reflects the current state of the master branch and is meant for testing purposes. Download
options include portable versions and installers for the Window, macOS, and Linux.

## Development

### Tutorial

Please read our brief [tutorial](http://mzmine.github.io/development.html) on how to contribute new
code to mzmine.

### Java version

mzmine development requires Java Development Kit (JDK) version 21 or newer (http://jdk.java.net).

### Moving old codebase to new modular build system

If there are still changes pending apply those moves first and then create a PR. Create a backup branch.

```bash
git mv -k -v ./src ./mzmine-community/
git mv -v ./log ./mzmine-community/
git mv -v ./logo ./mzmine-community/
git mv -v ./Ontologies ./mzmine-community/
```

### Building

To build the mzmine package from the sources, run the following command:

    ./gradlew

or

    gradlew.bat

The final mzmine distribution will be placed in build/jpackage

If you encounter any problems, please contact the developers by posting an issue:
https://github.com/mzmine/mzmine3/issues

### Contribute code (or documentation)
Guides and more information is in the mzmine documentation:
https://mzmine.github.io/mzmine_documentation/contribute_intellij.html


# Docker Client

[![Build Status](https://github.com/dmandalidis/docker-client/actions/workflows/ci.yml/badge.svg)](https://github.com/dmandalidis/docker-client/actions/workflows/ci.yml/badge.svg)
[![codecov](https://codecov.io/github/dmandalidis/docker-client/coverage.svg?branch=master)](https://codecov.io/github/dmandalidis/docker-client?branch=master)
[![Maven Central](https://img.shields.io/maven-central/v/org.mandas/docker-client.svg)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.mandas%22%20docker-client)
[![License](https://img.shields.io/github/license/dmandalidis/docker-client.svg)](LICENSE)

This is a [Docker](https://github.com/docker/docker) client written in Java.
It was used in many critical production systems at Spotify until its
[fork](https://github.com/dmandalidis/docker-client/blob/master/FORK.md) on September 2019.

The `docker-client` is built and tested against the latest `docker-ce` major release.

* [Download](#download)
* [Usage Example](#usage-example)
* [Getting Started](#getting-started)
* [Prerequisites](#prerequisites)
* [Testing](#testing)
* [Releasing](#releasing)
* [User Manual](https://github.com/dmandalidis/docker-client/blob/master/docs/user_manual.md)

## Download

Download the latest JAR or grab [via Maven][maven-search]

```xml
<dependency>
  <groupId>org.mandas</groupId>
  <artifactId>docker-client</artifactId>
  <version>LATEST-VERSION</version>
</dependency>
```

Since multiple JAX-RS client implementations cannot coexist in a flat classpath,
you need to choose either one of Jersey or RESTeasy, or create your implementation
of `DockerClientBuilder` for something completely different.

### Jersey

For using Jersey, you will have to pull the following dependencies (versions are indicative):

```xml
<dependency>
  <groupId>org.glassfish.jersey.core</groupId>
  <artifactId>jersey-client</artifactId>
  <version>3.1.0</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.inject</groupId>
  <artifactId>jersey-hk2</artifactId>
  <version>3.1.0</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.connectors</groupId>
  <artifactId>jersey-apache-connector</artifactId>
  <version>3.1.0</version>
</dependency>
<dependency>
  <groupId>org.glassfish.jersey.media</groupId>
  <artifactId>jersey-media-json-jackson</artifactId>
  <version>3.1.0</version>
</dependency>
```

### RESTeasy

For using RESTeasy, you will have to pull the following dependencies (versions are indicative):
```xml
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-client</artifactId>
  <version>6.1.0.Final</version>
</dependency>
<dependency>
  <groupId>org.jboss.resteasy</groupId>
  <artifactId>resteasy-core</artifactId>
  <version>6.1.0.Final</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.jakarta.rs</groupId>
  <artifactId>jackson-jakarta-rs-json-provider</artifactId>
  <version>2.13.1</version>
</dependency>
```

## Usage Example

```java
// Create a client based on DOCKER_HOST and DOCKER_CERT_PATH env vars
final DockerClient docker = new JerseyDockerClientBuilder().fromEnv().build(); // For Jersey
final DockerClient docker = new ResteasyDockerClientBuilder().fromEnv().build(); // For RESTeasy

// Pull an image
docker.pull("busybox");

// Bind container ports to host ports
final String[] ports = {"80", "22"};
final Map<String, List<PortBinding>> portBindings = new HashMap<>();
for (String port : ports) {
    List<PortBinding> hostPorts = new ArrayList<>();
    hostPorts.add(PortBinding.of("0.0.0.0", port));
    portBindings.put(port, hostPorts);
}

// Bind container port 443 to an automatically allocated available host port.
List<PortBinding> randomPort = new ArrayList<>();
randomPort.add(PortBinding.randomPort("0.0.0.0"));
portBindings.put("443", randomPort);

final HostConfig hostConfig = HostConfig.builder().portBindings(portBindings).build();

// Create container with exposed ports
final ContainerConfig containerConfig = ContainerConfig.builder()
    .hostConfig(hostConfig)
    .image("busybox").exposedPorts(ports)
    .cmd("sh", "-c", "while :; do sleep 1; done")
    .build();

final ContainerCreation creation = docker.createContainer(containerConfig);
final String id = creation.id();

// Inspect container
final ContainerInfo info = docker.inspectContainer(id);

// Start container
docker.startContainer(id);

// Exec command inside running container with attached STDOUT and STDERR
final String[] command = {"sh", "-c", "ls"};
final ExecCreation execCreation = docker.execCreate(
    id, command, DockerClient.ExecCreateParam.attachStdout(),
    DockerClient.ExecCreateParam.attachStderr());
final LogStream output = docker.execStart(execCreation.id());
final String execOutput = output.readFully();

// Kill container
docker.killContainer(id);

// Remove container
docker.removeContainer(id);

// Close the docker client
docker.close();
```

## Getting Started

If you're looking for how to use docker-client, see the [User Manual][1].
If you're looking for how to build and develop it, keep reading.

## Prerequisites

docker-client should be buildable on any platform with Docker 1.6+, JDK8+, and a recent version of
Maven 3.

### A note on using Docker for Mac

If you are using Docker for Mac and `DefaultDockerClient.fromEnv()`, it might not be clear
what value to use for the `DOCKER_HOST` environment variable. The value you should use is
`DOCKER_HOST=unix:///var/run/docker.sock`, at least as of version 1.11.1-beta11.

As of version 4.0.8 of docker-client, `DefaultDockerClient.fromEnv()` uses
`unix:///var/run/docker.sock` on OS X by default.

## Testing

If you're running a recent version of docker (>= 1.12), which contains native swarm support, please
ensure that you run `docker swarm init` to initialize the docker swarm.

Make sure Docker daemon is running and that you can do `docker ps`.

You can run tests on their own with `mvn test`. Note that the tests start and stop a large number of
containers, so the list of containers you see with `docker ps -a` will start to get pretty long
after many test runs. You may find it helpful to occasionally issue `docker rm $(docker ps -aq)`.

## Releasing

Commits to the master branch will trigger our continuous integration agent to build the jar and
release by uploading to Sonatype. If you are a project maintainer with the necessary credentials,
you can also build and release locally by running the below.

```sh
mvn clean [-DskipTests -Darguments=-DskipTests] -Dgpg.keyname=<key ID used for signing artifacts> release:prepare release:perform
```

  [1]: docs/user_manual.md

[maven-search]: https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.mandas%22%20docker-client


# Modern Industrialization
_Modern Industrialization is a standalone tech mod, where the ultimate objective is total automation.
Have machines generate and process all your resources while you are flying around doing anything you could possibly
dream of! Of course, there is a long way to go before getting there. Can you do it?_

More information and downloads on CurseForge: https://www.curseforge.com/minecraft/mc-mods/modern-industrialization.
Or Modrinth if you prefer: https://modrinth.com/mod/modern-industrialization.

## Modpack developer information
Please refer to the [Developer-facing Documentation](docs/README.md) for more information.

## Filing bug reports
Feel free to open an issue for bug reports!
Don't forget to post the *complete* log on a website like Pastebin or Gist.

## Suggestions for the mod
The best way to give suggestions is to come have a chat on our Discord server. Link on CurseForge!

## Contributing translations
All translations must go in `src/main/resources/assets/modern_industrialization/lang/`,
except the reference `en_us` translation which is autogenerated and can be found [here](src/generated/resources/assets/modern_industrialization/lang/en_us.json).

### For a new language
Copy the reference `en_us` file and rename it to the language code of your language.
Then, translate all the strings.

### For an existing language
Missing or unused translations for existing languages can be found [here](src/generated/resources/assets/modern_industrialization/lang/untranslated).
To add missing and remove unused translations for your language,
copy the relevant file from that folder to the main language folder,
and modify it to remove the erroring entries.

## Creating an addon for Modern Industrialization
Everything in the `aztechmc.modern_industrialization.api` package is the stable public API.
It will not change during a major Minecraft version, except for members marked as `@ApiStatus.Internal`.

The API is still a bit rough, and we are open to suggestions.
If you need more things to be exposed please come discuss the features you need on our Discord.
The link is on CurseForge.

## License
The code is under the MIT license.

The assets are all under CC0. Many textures are original, and for many we adjusted the work of others. Thanks go to:
- GregoriusT for the original GregTech textures,
- Falkory for redoing many textures,
- Spool for some of the crafting component textures,
- VirtualLilith for the rotary blade texture.


# The Algorithms - Java

[![Build](https://github.com/TheAlgorithms/Java/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/TheAlgorithms/Java/actions/workflows/build.yml)
[![codecov](https://codecov.io/gh/TheAlgorithms/Java/graph/badge.svg?token=XAdPyqTIqR)](https://codecov.io/gh/TheAlgorithms/Java)
[![Discord chat](https://img.shields.io/discord/808045925556682782.svg?logo=discord&colorB=7289DA&style=flat-square)](https://discord.gg/c7MnfGFGa6)
[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/TheAlgorithms/Java)

You can run and edit the algorithms, or contribute to them using Gitpod.io (a free online development environment) with a single click.

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/TheAlgorithms/Java)

### All algorithms are implemented in Java (for educational purposes)
These implementations are intended for learning purposes. As such, they may be less efficient than the Java standard library.

## Contribution Guidelines
Please read our [Contribution Guidelines](CONTRIBUTING.md) before you contribute to this project.

## Algorithms
Our [directory](DIRECTORY.md) has the full list of applications.


jMonkeyEngine
=============

[![Build Status](https://github.com/jMonkeyEngine/jmonkeyengine/workflows/Build%20jMonkeyEngine/badge.svg)](https://github.com/jMonkeyEngine/jmonkeyengine/actions)

jMonkeyEngine is a 3-D game engine for adventurous Java developers. It’s open-source, cross-platform, and cutting-edge.
v3.6.1 is the latest stable version of the engine.

The engine is used by several commercial game studios and computer-science courses. Here's a taste:

![jME3 Games Mashup](https://i.imgur.com/nF8WOW6.jpg)

 - [jME powered games on IndieDB](https://www.indiedb.com/engines/jmonkeyengine/games)
 - [Boardtastic 2](https://boardtastic-2.fileplanet.com/apk)
 - [Attack of the Gelatinous Blob](https://attack-gelatinous-blob.softwareandgames.com/)
 - [Mythruna](https://mythruna.com/)
 - [PirateHell (on Steam)](https://store.steampowered.com/app/321080/Pirate_Hell/)
 - [3089 (on Steam)](https://store.steampowered.com/app/263360/3089__Futuristic_Action_RPG/)
 - [3079 (on Steam)](https://store.steampowered.com/app/259620/3079__Block_Action_RPG/)
 - [Lightspeed Frontier (on Steam)](https://store.steampowered.com/app/548650/Lightspeed_Frontier/)
 - [Skullstone](http://www.skullstonegame.com/)
 - [Spoxel (on Steam)](https://store.steampowered.com/app/746880/Spoxel/)
 - [Nine Circles of Hell (on Steam)](https://store.steampowered.com/app/1200600/Nine_Circles_of_Hell/)
 - [Leap](https://gamejolt.com/games/leap/313308)
 - [Jumping Jack Flag](http://timealias.bplaced.net/jack/)
 - [PapaSpace Flight Simulation](https://www.papaspace.at/)
 - [Cubic Nightmare (on Itch)](https://jaredbgreat.itch.io/cubic-nightmare)
 - [Chatter Games](https://chatter-games.com)
 - [Exotic Matter](https://exoticmatter.io)
 - [Demon Lord (on Google Play)](https://play.google.com/store/apps/details?id=com.dreiInitiative.demonLord&pli=1)
 - [Marvelous Marbles (on Steam)](https://store.steampowered.com/app/2244540/Marvelous_Marbles/)
 - [Boxer (on Google Play)](https://play.google.com/store/apps/details?id=com.tharg.boxer)
 - [Depthris (on Itch)](https://codewalker.itch.io/depthris)
 - [Stranded (on Itch)](https://tgiant.itch.io/stranded)
 - [The Afflicted Forests (Coming Soon to Steam)](https://www.indiedb.com/games/the-afflicted-forests)
 - [Star Colony: Beyond Horizons (on Google Play)](https://play.google.com/store/apps/details?id=game.colony.ColonyBuilder)

## Getting Started

Go to https://github.com/jMonkeyEngine/sdk/releases to download the jMonkeyEngine SDK.
Read [the wiki](https://jmonkeyengine.github.io/wiki) for the installation guide and tutorials.
Join [the discussion forum](https://hub.jmonkeyengine.org/) to participate in our community,
get your questions answered, and share your projects.

Note: The master branch on GitHub is a development version of the engine and is NOT MEANT TO BE USED IN PRODUCTION.

### Technology Stack

 - windowed, multi-platform IDE derived from NetBeans
 - libraries for GUI, networking, physics, SFX, terrain, importing assets, etc.
 - platform-neutral core library for scene graph, animation, rendering, math, etc.
 - LWJGL v2/v3 (to access GLFW, OpenAL, OpenGL, and OpenVR) or Android or iOS
 - Java Virtual Machine (v8 or higher)

### Documentation

Did you miss it? Don't sweat it, [here it is again](https://jmonkeyengine.github.io/wiki).

### Contributing

Read our [contribution guide](https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/CONTRIBUTING.md).

### License

[New BSD (3-clause) License](https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/LICENSE.md)


RoaringBitmap
=============
[![][license img]][license]
[![docs-badge][]][docs]
![Java 11 CI](https://github.com/RoaringBitmap/RoaringBitmap/workflows/Java%2011%20CI/badge.svg)

Bitsets, also called bitmaps, are commonly used as fast data structures.
Unfortunately, they can use too much memory. To compensate, we often use
compressed bitmaps.

Roaring bitmaps are compressed bitmaps which tend to outperform conventional
compressed bitmaps such as WAH, EWAH or Concise. In some instances, roaring bitmaps can
be hundreds of times faster and they often offer significantly better compression.
They can even be faster than uncompressed bitmaps.

Roaring bitmaps are found to work well in many important applications:

> Use Roaring for bitmap compression whenever possible. Do not use other bitmap compression methods ([Wang et al., SIGMOD 2017](http://db.ucsd.edu/wp-content/uploads/2017/03/sidm338-wangA.pdf))

> kudos for making something that makes my software run 5x faster (Charles Parker from BigML)

This library is used by
*   [Apache Spark](http://spark.apache.org/),
*   [Apache Hive](http://hive.apache.org),
*   [Apache Tez](http://tez.apache.org),
*   [Apache Kylin](http://kylin.io),
*   [Apache CarbonData](https://carbondata.apache.org),
*   [Netflix Atlas](https://github.com/Netflix/atlas),
*   [OpenSearchServer](http://www.opensearchserver.com),
*   [zenvisage](http://zenvisage.github.io/),
*   [Jive Miru](https://github.com/jivesoftware/miru),
*   [Tablesaw](https://github.com/jtablesaw/tablesaw),
*   [Apache Hivemall](http://hivemall.incubator.apache.org),
*   [Gaffer](https://github.com/gchq/Gaffer),
*   [Apache Pinot](https://pinot.apache.org/),
*   [Apache Druid](https://druid.apache.org/),
*   [SirixDB](https://sirix.io)
*   [EvitaDB](https://evitadb.io/)
*   [Apache Iceberg](https://iceberg.apache.org/)

The YouTube SQL Engine, [Google Procella](https://research.google/pubs/pub48388/), uses Roaring bitmaps for indexing. [Apache Lucene](http://lucene.apache.org/) uses  Roaring bitmaps, though they have their own [independent implementation](https://svn.apache.org/viewvc/lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/util/RoaringDocIdSet.java?view=markup&pathrev=1629606). Derivatives of Lucene such as Solr and Elastic also use Roaring bitmaps.
Other platforms such as [Whoosh](https://pypi.python.org/pypi/Whoosh/), [Microsoft Visual Studio Team Services (VSTS)](https://www.visualstudio.com/team-services/) and [Pilosa](https://github.com/pilosa/pilosa) also use Roaring bitmaps with their own implementations. You find Roaring bitmaps in [InfluxDB](https://www.influxdata.com), [Bleve](http://www.blevesearch.com), [Cloud Torrent](https://github.com/jpillora/cloud-torrent), [Redpanda](https://github.com/redpanda-data/redpanda), and so forth.

[There is a serialized format specification for interoperability between implementations](https://github.com/RoaringBitmap/RoaringFormatSpec/).
We have interoperable [C/C++](https://github.com/RoaringBitmap/CRoaring), Java and [Go](https://github.com/RoaringBitmap/roaring) implementations.

(c) 2013-... the RoaringBitmap authors

This code is licensed under Apache License, Version 2.0 (AL2.0).

When should you use a bitmap?
===================================

Sets are a fundamental abstraction in
software. They can be implemented in various
ways, as hash sets, as trees, and so forth.
In databases and search engines, sets are often an integral
part of indexes. For example, we may need to maintain a set
of all documents or rows  (represented by numerical identifier)
that satisfy some property. Besides adding or removing
elements from the set, we need fast functions
to compute the intersection, the union, the difference between sets, and so on.

To implement a set
of integers, a particularly appealing strategy is the
bitmap (also called bitset or bit vector). Using n bits,
we can represent any set made of the integers from the range
[0,n): the ith bit is set to one if integer i is present in the set.
Commodity processors use words of W=32 or W=64 bits. By combining many such words, we can
support large values of n. Intersections, unions and differences can then be implemented
 as bitwise AND, OR and ANDNOT operations.
More complicated set functions can also be implemented as bitwise operations.

When the bitset approach is applicable, it can be orders of
magnitude faster than other possible implementation of a set (e.g., as a hash set)
while using several times less memory.

However, a bitset, even a compressed one is not always applicable. For example, if
you have 1000 random-looking integers, then a simple array might be the best representation.
We refer to this case as the "sparse" scenario.

When should you use compressed bitmaps?
===================================

An uncompressed BitSet can use a lot of memory. For example, if you take a BitSet
and set the bit at position 1,000,000 to true and you have just over 100kB. That is over 100kB
to store the position of one bit. This is wasteful  even if you do not care about memory:
suppose that you need to compute the intersection between this BitSet and another one
that has a bit at position 1,000,001 to true, then you need to go through all these zeroes,
whether you like it or not. That can become very wasteful.

This being said, there are definitively cases where attempting to use compressed bitmaps is wasteful.
For example, if you have a small universe size. E.g., your bitmaps represent sets of integers
from [0,n) where n is small (e.g., n=64 or n=128). If you can use an uncompressed BitSet and
it does not blow up your memory usage,  then compressed bitmaps are probably not useful
to you. In fact, if you do not need compression, then a BitSet offers remarkable speed.

The sparse scenario is another use case where compressed bitmaps should not be used.
Keep in mind that random-looking data is usually not compressible. E.g., if you have a small set of
32-bit random integers, it is not mathematically possible to use far less than 32 bits per integer,
and attempts at compression can be counterproductive.

How does Roaring compare with the alternatives?
==================================================

Most alternatives to Roaring are part of a larger family of compressed bitmaps that are run-length-encoded
bitmaps. They identify long runs of 1s or 0s and they represent them with a marker word.
If you have a local mix of 1s and 0, you use an uncompressed word.

There are many formats in this family:

* Oracle's BBC (Byte-aligned Bitmap Code) is an obsolete format at this point: though it may provide good compression,
it is likely much slower than more recent alternatives due to excessive branching.
* WAH (Word Aligned Hybrid) is a patented variation on BBC that provides better performance.
* Concise is a variation on the patented WAH. In some specific instances, it can compress
much better than WAH (up to 2x better), but it is generally slower.
* EWAH (Enhanced Word Aligned Hybrid) is both free of patent, and it is faster than all the above. On the downside, it
does not compress quite as well. It is faster because it allows some form of "skipping"
over uncompressed words. So though none of these formats are great at random access, EWAH
is better than the alternatives.

There is a big problem with these formats however that can hurt you badly in some cases: there is no random access. If you want to check whether a given value is present in the set, you have to start from the beginning and "uncompress" the whole thing. This means that if you want to intersect a big set with a large set, you still have to uncompress the whole big set in the worst case...

Roaring solves this problem. It works in the following manner. It divides the data into chunks of 216 integers
(e.g., [0, 216), [216, 2 x 216), ...). Within a chunk, it can use an uncompressed bitmap, a simple list of integers,
or a list of runs. Whatever format it uses, they all allow you to check for the presence of any one value quickly
(e.g., with a binary search). The net result is that Roaring can compute many operations much faster than run-length-encoded
formats like WAH, EWAH, Concise... Maybe surprisingly, Roaring also generally offers better compression ratios.

API docs
---------

http://www.javadoc.io/doc/org.roaringbitmap/RoaringBitmap/

Scientific Documentation
--------------------------

- Daniel Lemire, Owen Kaser, Nathan Kurz, Luca Deri, Chris O'Hara, François Saint-Jacques, Gregory Ssi-Yan-Kai, Roaring Bitmaps: Implementation of an Optimized Software Library, Software: Practice and Experience 48 (4), 2018 [arXiv:1709.07821](https://arxiv.org/abs/1709.07821)
-  Samy Chambi, Daniel Lemire, Owen Kaser, Robert Godin,
Better bitmap performance with Roaring bitmaps,
Software: Practice and Experience 46 (5), 2016. [arXiv:1402.6407](http://arxiv.org/abs/1402.6407) This paper used data from http://lemire.me/data/realroaring2014.html
- Daniel Lemire, Gregory Ssi-Yan-Kai, Owen Kaser, Consistently faster and smaller compressed bitmaps with Roaring, Software: Practice and Experience 46 (11), 2016. [arXiv:1603.06549](http://arxiv.org/abs/1603.06549)
- Samy Chambi, Daniel Lemire, Robert Godin, Kamel Boukhalfa, Charles Allen, Fangjin Yang, Optimizing Druid with Roaring bitmaps, IDEAS 2016, 2016. http://r-libre.teluq.ca/950/

Code sample
-------------

```java
import org.roaringbitmap.RoaringBitmap;

public class Basic {

  public static void main(String[] args) {
        RoaringBitmap rr = RoaringBitmap.bitmapOf(1,2,3,1000);
        RoaringBitmap rr2 = new RoaringBitmap();
        rr2.add(4000L,4255L);
        rr.select(3); // would return the third value or 1000
        rr.rank(2); // would return the rank of 2, which is index 1
        rr.contains(1000); // will return true
        rr.contains(7); // will return false

        RoaringBitmap rror = RoaringBitmap.or(rr, rr2);// new bitmap
        rr.or(rr2); //in-place computation
        boolean equals = rror.equals(rr);// true
        if(!equals) throw new RuntimeException("bug");
        // number of values stored?
        long cardinality = rr.getLongCardinality();
        System.out.println(cardinality);
        // a "forEach" is faster than this loop, but a loop is possible:
        for(int i : rr) {
          System.out.println(i);
        }
  }
}
```

Please see the examples folder for more examples, which you can run with `./gradlew :examples:runAll`, or run a specific one with `./gradlew :examples:runExampleBitmap64`, etc.

Unsigned integers
------------------

Java lacks native unsigned integers but integers are still considered to be unsigned within Roaring and ordered according to ``Integer.compareUnsigned``. This means that Java will order the numbers like so 0, 1, ..., 2147483647, -2147483648, -2147483647,..., -1. To interpret correctly, you can use ``Integer.toUnsignedLong`` and ``Integer.toUnsignedString``.

Working with memory-mapped bitmaps
---------------------------------------

If you want to have your bitmaps lie in memory-mapped files, you can
use the org.roaringbitmap.buffer package instead. It contains two
important classes, ImmutableRoaringBitmap and MutableRoaringBitmap.
MutableRoaringBitmaps are derived from ImmutableRoaringBitmap, so that
you can convert (cast) a MutableRoaringBitmap to an ImmutableRoaringBitmap
in constant time.

An ImmutableRoaringBitmap that is not an instance of a MutableRoaringBitmap
is backed by a ByteBuffer which comes with some performance overhead, but
with the added flexibility that the data can reside anywhere (including outside
of the Java heap).

At times you may need to work with bitmaps that reside on disk (instances
of ImmutableRoaringBitmap) and bitmaps that reside in Java memory. If you
know that the bitmaps will reside in Java memory, it is best to use
MutableRoaringBitmap instances, not only can they be modified, but they
will also be faster. Moreover, because MutableRoaringBitmap instances are
also ImmutableRoaringBitmap instances, you can write much of your code
expecting ImmutableRoaringBitmap.

If you write your code expecting ImmutableRoaringBitmap instances, without
attempting to cast the instances, then your objects will be truly immutable.
The MutableRoaringBitmap has a convenience method (toImmutableRoaringBitmap)
which is a simple cast back to an ImmutableRoaringBitmap instance.
From a language design point of view, instances of the ImmutableRoaringBitmap class are immutable only when used as per
the interface of the ImmutableRoaringBitmap class. Given that the class is not final, it is possible
to modify instances, through other interfaces. Thus we do not take the term "immutable" in a purist manner,
but rather in a practical one.

One of our motivations for this design where MutableRoaringBitmap instances can be casted
down to ImmutableRoaringBitmap instances is that bitmaps are often large,
or used in a context where memory allocations are to be avoided, so we avoid forcing copies.
Copies could be expected if one needs to mix and match ImmutableRoaringBitmap and MutableRoaringBitmap instances.

The following code sample illustrates how to create an ImmutableRoaringBitmap
from a ByteBuffer. In such instances, the constructor only loads the meta-data
in RAM while the actual data is accessed from the ByteBuffer on demand.

```java
        import org.roaringbitmap.buffer.*;

        //...

        MutableRoaringBitmap rr1 = MutableRoaringBitmap.bitmapOf(1, 2, 3, 1000);
        MutableRoaringBitmap rr2 = MutableRoaringBitmap.bitmapOf( 2, 3, 1010);
        ByteArrayOutputStream bos = new ByteArrayOutputStream();
        DataOutputStream dos = new DataOutputStream(bos);
        // If there were runs of consecutive values, you could
        // call rr1.runOptimize(); or rr2.runOptimize(); to improve compression
        rr1.serialize(dos);
        rr2.serialize(dos);
        dos.close();
        ByteBuffer bb = ByteBuffer.wrap(bos.toByteArray());
        ImmutableRoaringBitmap rrback1 = new ImmutableRoaringBitmap(bb);
        bb.position(bb.position() + rrback1.serializedSizeInBytes());
        ImmutableRoaringBitmap rrback2 = new ImmutableRoaringBitmap(bb);
```

Alternatively, we can serialize directly to a `ByteBuffer` with the `serialize(ByteBuffer)` method.

Operations on an ImmutableRoaringBitmap such as and, or, xor, flip, will
generate a RoaringBitmap which lies in RAM. As the name suggest, the
ImmutableRoaringBitmap itself cannot be modified.

This design was inspired by Druid.

One can find a complete working example in the test file TestMemoryMapping.java.

Note that you should not mix the classes from the org.roaringbitmap package with the classes
from the org.roaringbitmap.buffer package. They are incompatible. They serialize
to the same output however. The performance of the code in org.roaringbitmap package is
generally superior because there is no overhead due to the use of ByteBuffer instances.

Kryo
-----

Many applications use Kryo for serialization/deserialization. One can
use Roaring bitmaps with Kryo efficiently thanks to a custom serializer (Kryo 5):

```java
public class RoaringSerializer extends Serializer<RoaringBitmap> {
    @Override
    public void write(Kryo kryo, Output output, RoaringBitmap bitmap) {
        try {
            bitmap.serialize(new KryoDataOutput(output));
        } catch (IOException e) {
            e.printStackTrace();
            throw new RuntimeException();
        }
    }
    @Override
    public RoaringBitmap read(Kryo kryo, Input input, Class<? extends RoaringBitmap> type) {
        RoaringBitmap bitmap = new RoaringBitmap();
        try {
            bitmap.deserialize(new KryoDataInput(input));
        } catch (IOException e) {
            e.printStackTrace();
            throw new RuntimeException();
        }
        return bitmap;
    }

}
```

64-bit integers (long)
-----------------------

Though Roaring Bitmaps were designed with the 32-bit case in mind, we have extensions to 64-bit integers.
We offer two classes for this purpose: `Roaring64NavigableMap` and `Roaring64Bitmap`.

The `Roaring64NavigableMap` relies on a conventional red-black-tree. The keys are 32-bit integers representing
the most significant 32~bits of  elements
whereas the values of the tree are 32-bit Roaring bitmaps. The 32-bit Roaring bitmaps represent the least significant
bits of a set of elements.

The newer `Roaring64Bitmap` approach relies on the ART data structure to hold the key/value pair. The key
 is made of the most significant 48~bits of elements whereas the values are 16-bit Roaring containers. It is inspired by
 [The Adaptive Radix Tree: ARTful Indexing for Main-Memory Databases](https://db.in.tum.de/~leis/papers/ART.pdf) by Leis et al. (ICDE '13).

```java
    import org.roaringbitmap.longlong.*;

    // first Roaring64NavigableMap
    LongBitmapDataProvider r = Roaring64NavigableMap.bitmapOf(1,2,100,1000);
    r.addLong(1234);
    System.out.println(r.contains(1)); // true
    System.out.println(r.contains(3)); // false
    LongIterator i = r.getLongIterator();
    while(i.hasNext()) System.out.println(i.next());

    // second Roaring64Bitmap
    bitmap1 = new Roaring64Bitmap();
    bitmap2 = new Roaring64Bitmap();
    int k = 1 << 16;
    long i = Long.MAX_VALUE / 2;
    long base = i;
    for (; i < base + 10000; ++i) {
       bitmap1.add(i * k);
       bitmap2.add(i * k);
    }
    b1.and(bitmap2);
```

The serialization of 64-bit Roaring bitmaps is specified: see
https://github.com/RoaringBitmap/RoaringFormatSpec#extention-for-64-bit-implementations

However, it is implemented only by `Roaring64NavigableMap`, by switching:

    Roaring64NavigableMap.SERIALIZATION_MODE = Roaring64NavigableMap.SERIALIZATION_MODE_PORTABLE

Range Bitmaps
-------------

`RangeBitmap` is a succinct data structure supporting range queries.
Each value added to the bitmap is associated with an incremental identifier,
and queries produce a `RoaringBitmap` of the identifiers associated with values
that satisfy the query. Every value added to the bitmap is stored separately,
so that if a value is added twice, it will be stored twice, and if that value
is less than some threshold, there will be at least two integers in the resultant
`RoaringBitmap`.

It is more efficient - in terms of both time and space - to
provide a maximum value. If you don't know the maximum value,
provide a `Long.MAX_VALUE`. Unsigned order is used like elsewhere in
the library.

```java
var appender = RangeBitmap.appender(1_000_000);
appender.add(1L);
appender.add(1L);
appender.add(100_000L);
RangeBitmap bitmap = appender.build();
RoaringBitmap lessThan5 = bitmap.lt(5); // {0,1}
RoaringBitmap greaterThanOrEqualTo1 = bitmap.gte(1); // {0, 1, 2}
RoaringBitmap greaterThan1 = bitmap.gt(1); // {2}
RoaringBitmap equalTo1 = bitmap.eq(1); // {0, 1}
RoaringBitmap notEqualTo1 = bitmap.neq(1); // {2}
```

`RangeBitmap` is can be written to disk and memory mapped:

```java
var appender = RangeBitmap.appender(1_000_000);
appender.add(1L);
appender.add(1L);
appender.add(100_000L);
ByteBuffer buffer = mapBuffer(appender.serializedSizeInBytes());
appender.serialize(buffer);
RangeBitmap bitmap = RangeBitmap.map(buffer);
```

The serialization format uses little endian byte order.

Prerequisites
-------------

 - Version 0.7.x requires JDK 8 or better
 - Version 0.6.x requires JDK 7 or better
 - Version 0.5.x requires JDK 6 or better

To build the project you need maven (version 3).

Download
---------

You can download releases from github:
https://github.com/RoaringBitmap/RoaringBitmap/releases

Maven repository
----------------
If your project depends on roaring, you  can  specify the dependency in the Maven "pom.xml" file:

```xml
        <dependencies>
          <dependency>
            <groupId>org.roaringbitmap</groupId>
            <artifactId>RoaringBitmap</artifactId>
            <version>0.9.9</version>
          </dependency>
        </dependencies>
```

where you should replace the version number by the version you require.

[For up-to-date releases, we recommend configuring maven and gradle to depend on the Jitpack repository](https://jitpack.io/#RoaringBitmap/RoaringBitmap).

Usage
------

* Get java

* ``./gradlew assemble`` will compile
* ``./gradlew build`` will compile and run the unit tests
* ``./gradlew test `` will run the tests
* ``./gradlew :roaringbitmap:test --tests TestIterators.testIndexIterator4`` runs just the test `TestIterators.testIndexIterator4`; `./gradlew -i :roaringbitmap:test --tests TestRoaringBitmap.issue623` runs just the test `issue623` in the class ` TestRoaringBitmap` while printing out to the console.
* ``./gradlew  bsi:test --tests BufferBSITest.testEQ``  run just the test `BufferBSITest.testEQ` in the `bsi` submodule
* ``./gradlew checkstyleMain`` will check that you abide by the code style and that the code compiles. We enforce a strict style so that there is no debate as to the proper way to format the code.

IntelliJ and Eclipse
--------

If you plan to contribute to RoaringBitmap, you can have load
it up in your favorite IDE.
- For IntelliJ, in the IDE create a new project, possibly from existing sources, choose import, gradle.
- For Eclipse: File, Import, Existing Gradle Projects, Select RoaringBitmap on my disk

Contributing
------------

Contributions are invited. We enforce the Google Java style.
Please run  ``./gradlew checkstyleMain`` on your code before submitting
a patch.

FAQ
----

* I am getting an error about a bad cookie. What is this about?

In the serialized files, part of the first 4 bytes are dedicated to a "cookie"
which serves to indicate the file format.

If you try to deserialize or map a bitmap from data that has an
unrecognized "cookie", the code will abort the process and report
an error.

This problem will occur to all users who serialized Roaring bitmaps
using versions prior to 0.4.x as they upgrade to version 0.4.x or better.
These users need to refresh their serialized bitmaps.

* How big can a Roaring bitmap get?

Given N integers in [0,x), then the serialized size in bytes of
a Roaring bitmap should never exceed this bound:

`` 8 + 9 * ((long)x+65535)/65536 + 2 * N ``

That is, given a fixed overhead for the universe size (x), Roaring
bitmaps never use more than 2 bytes per integer. You can call
``RoaringBitmap.maximumSerializedSize`` for a more precise estimate.

* What is the worst case scenario for Roaring bitmaps?

There is no such thing as a data structure that is always ideal. You should
make sure that Roaring bitmaps fit your application profile.
There are at least two cases where Roaring bitmaps can be easily replaced
by superior alternatives compression-wise:

1. You have few random values spanning in a large interval (i.e., you have
a very sparse set). For example, take the set 0, 65536, 131072, 196608, 262144 ...
If this is typical of your application, you might consider using a HashSet or
a simple sorted array.

2. You have dense set of random values that never form runs of continuous
values. For example, consider the set 0,2,4,...,10000. If this is typical of your
application, you might be better served with a conventional bitset (e.g., Java's BitSet class).

* How do I select an element at random?

         Random random = new Random();
         bitmap.select(random.nextInt(bitmap.getCardinality()));

Benchmark
-----------

To run JMH benchmarks, use the following command:

         $ ./gradlew jmhJar

You can also run specific benchmarks...

         $ ./jmh/run.sh 'org.roaringbitmap.aggregation.and.identical.*'

Mailing list/discussion group
-----------------------------

https://groups.google.com/forum/#!forum/roaring-bitmaps

Funding
----------

This work was supported by NSERC grant number 26143.

[maven img]:https://maven-badges.herokuapp.com/maven-central/org.roaringbitmap/RoaringBitmap/badge.svg
[maven]:http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.roaringbitmap%22%20

[license]:LICENSE-2.0.txt
[license img]:https://img.shields.io/badge/License-Apache%202-blue.svg

[docs-badge]:https://img.shields.io/badge/API-docs-blue.svg?style=flat-square
[docs]:http://www.javadoc.io/doc/org.roaringbitmap/RoaringBitmap/


![promo](https://raw.githubusercontent.com/AlmasB/git-server/master/storage/images/fxgl_promo.jpg)

## Languages

  English

  [简体中文](https://github.com/AlmasB/FXGL/blob/dev/README_CN.md)

  [Русский](https://github.com/AlmasB/FXGL/blob/dev/README_RU.md)

## About

<img src="https://raw.githubusercontent.com/AlmasB/git-server/master/storage/images/fxgl_logo.png" width="128" />

JavaFX Game Development Framework

[![Maven Central](https://img.shields.io/maven-central/v/com.github.almasb/fxgl.svg)]()
[![Build Status](https://github.com/AlmasB/FXGL/workflows/Java%20CI%20with%20Maven/badge.svg)](https://github.com/AlmasB/FXGL/actions)
[![codecov](https://codecov.io/gh/AlmasB/FXGL/branch/dev/graph/badge.svg)](https://codecov.io/gh/AlmasB/FXGL)
[![sponsor](https://img.shields.io/badge/sponsor-%241-brightgreen)](https://github.com/sponsors/AlmasB)
[![JFXCentral](https://img.shields.io/badge/Find_me_on-JFXCentral-blue?logo=googlechrome&logoColor=white)](https://www.jfx-central.com/libraries/fxgl)

### Why FXGL?

* No installation or setup is required
* "Out of the box": Java 8-21, Win/Mac/Linux/Android 8+/iOS 11.0+/Web
* Simple and clean API, higher level than other engines
* Superset of JavaFX: no need to learn new UI API
* Real-world game development techniques: Entity-Component, interpolated animations, particles, and [many more](https://github.com/AlmasB/FXGL/wiki/Core-Features)
* Games are easily packaged into a single executable .jar, or native images

### Good for:

* Any 2D game (side-scroller / platformer / arcade / RPG)
* Any business application with complex UI controls / animations
* Experimental 3D
* Hobby / academic / commercial projects
* Teaching / learning / improving game development skills
* Fast prototyping of app ideas

### Minimal Example

```java
public class BasicGameApp extends GameApplication {

    @Override
    protected void initSettings(GameSettings settings) {
        settings.setWidth(800);
        settings.setHeight(600);
        settings.setTitle("Basic Game App");
    }

    public static void main(String[] args) {
        launch(args);
    }
}
```

## Getting Started

For a quick dive into code, see standalone [basic examples](https://github.com/AlmasB/FXGL/tree/dev/fxgl-samples/src/main/java/basics).

Otherwise, see:

* [FXGL book](https://link.springer.com/book/10.1007/978-1-4842-8625-8?sap-outbound-id=3352BB472E8E602B4B29844F1A86CCC4374DDF6E)
* [Showcase Trailer](https://youtu.be/fuDQg7W0v4g)
* [Use FXGL with IntelliJ](https://youtu.be/LhmlFC6KE2Q)
* [Wiki & written tutorials](https://github.com/AlmasB/FXGL/wiki)
* [YouTube tutorials](https://www.youtube.com/playlist?list=PL4h6ypqTi3RTiTuAQFKE6xwflnPKyFuPp)
* [Sample code demos](fxgl-samples)
* [FXGL games](https://github.com/AlmasB/FXGLGames) (with source)
* [Published demos](https://fxgl.itch.io/) on itch.io

### Maven

* [Maven](https://github.com/AlmasB/FXGL-MavenGradle) template project if you use Java and/or Kotlin

```xml
<dependency>
    <groupId>com.github.almasb</groupId>
    <artifactId>fxgl</artifactId>
    <version>21.1</version>
</dependency>
```

### Gradle

* [Gradle](https://github.com/AlmasB/FXGL-MavenGradle) template project if you use Java and/or Kotlin

Please refer to the template if there are any errors.

```gradle
repositories {
    jcenter()
}

dependencies {
    compile 'com.github.almasb:fxgl:21.1'
}
```

### Modularity

If you wish to develop a modular application, here's a complete example of your `module-info.java`:

```java
open module app.name {
    requires com.almasb.fxgl.all;
}
```

### Uber jar

Download the latest uber jar from [Releases](https://github.com/AlmasB/FXGL/releases)

## Community

* University of Brighton, UK
* University of Nottingham, UK
* Georgia Institute of Technology, USA
* kidOYO, USA
* Walton High School, USA
* Conant High School, USA
* Zealand Institute of Business and Technology, Denmark
* Federal Institute of Education, Science and Technology of Rio Grande do Sul, Brazil
* FHNW School of Engineering / Computer Science, Switzerland
* Johann-Andreas-Schmeller-Gymnasium Nabburg, Germany

If your institution wants to use or is using FXGL, add a note via [GitHub Discussions](https://github.com/AlmasB/FXGL/discussions) to be added to the list.

Community tutorials:

- [Space Ranger](https://www.journaldev.com/40219/space-rangers-game-java-fxgl) at journaldev
- [Geometry Wars](https://webtechie.be/post/2020-05-07-getting-started-with-fxgl/) at webtechie
- [Mazela-Man](https://dykstrom.github.io/mazela-man-web/home/) by dykstrom

Community projects (identified using `fxgl` topic):

- [SOFTKNK.IO](https://github.com/softknk/softknk.io)
- [Consume](https://ergoscrit.itch.io/consume)
- [FXGL Sliding Puzzle](https://github.com/beryx/fxgl-sliding-puzzle)

If you'd like your project featured here, just add a note via [GitHub Discussions](https://github.com/AlmasB/FXGL/discussions).

### Development Team

A description of roles is given in the [Contribution Guide](CONTRIBUTING.md).

Maintainers (Collaborators):

* [Almas Baimagambetov](https://github.com/AlmasB)

Coordinators:

* [Chengen Zhao](https://github.com/chengenzhao)

Testers:

* [Carl Dea](https://github.com/carldea)
* [Frank Delporte](https://github.com/FDelporte)

### Contribution & Support

If you want to build FXGL from the source code or want to contribute,
please see the [Contribution Guide](CONTRIBUTING.md) (including non-code).
FXGL is fully modular, so new contributors do not need to understand the entire codebase, only the module to which the contribution is made.
Contributions will be reviewed in accordance with the [Code of Conduct](CODE_OF_CONDUCT.md).

You can support the FXGL development or show interest by simply starring the repo or becoming a [sponsor](https://github.com/sponsors/AlmasB).

### Sponsors

Users:

* @Marsl10
* @SergeMerzliakov
* @mbains
* @sabit86
* @hendrikebbers
* @ImperaEtConquer
* @thejeed
* @chikega

Companies:

* @karakun

### Contact

* Ask questions via [GitHub Discussions](https://github.com/AlmasB/FXGL/discussions)
* Ask via [StackOverflow](https://stackoverflow.com/search?q=fxgl) with tags `javafx` and `fxgl`
* Tweet with [#fxgl](https://twitter.com/search?src=typd&q=%23fxgl)


# Gaffer

![ci](https://github.com/gchq/Gaffer/actions/workflows/continuous-integration.yaml/badge.svg?branch=develop)
[![codecov](https://codecov.io/gh/gchq/Gaffer/branch/develop/graph/badge.svg?token=D7FRqMeurU)](https://codecov.io/gh/gchq/Gaffer)
[](https://gchq.github.io/gaffer-doc/latest/)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/uk.gov.gchq.gaffer/gaffer2/badge.svg)](https://maven-badges.herokuapp.com/maven-central/uk.gov.gchq.gaffer/gaffer2)

Gaffer is a graph database framework. It allows the storage of very large graphs containing rich properties on the nodes and edges. Several storage options are available, including Accumulo and an in-memory Java Map Store.

It is designed to be as flexible, scalable and extensible as possible, allowing for rapid prototyping and transition to production systems.

Gaffer offers:

 - Rapid query across very large numbers of nodes and edges
 - Continual ingest of data at very high data rates, and batch bulk ingest of data via MapReduce or Spark
 - Storage of arbitrary Java objects on the nodes and edges
 - Automatic, user-configurable in-database aggregation of rich statistical properties (e.g. counts, histograms, sketches) on the nodes and edges
 - Versatile query-time summarisation, filtering and transformation of data
 - Fine grained data access controls
 - Hooks to apply policy and compliance rules to queries
 - Automated, rule-based removal of data (typically used to age-off old data)
 - Retrieval of graph data into Apache Spark for fast and flexible analysis
 - A fully-featured REST API

To get going with Gaffer, visit our getting started pages ([1.x](https://gchq.github.io/gaffer-doc/v1docs/summaries/getting-started.html), [2.x](https://gchq.github.io/gaffer-doc/latest/administration-guide/gaffer-deployment/quickstart)).
We also have a demo available to try that is based around a small uk road use dataset. See the example/road-traffic [README](https://github.com/gchq/Gaffer/blob/master/example/road-traffic/README.md) to try it out.

Gaffer is under active development. Version 1.0 of Gaffer was released in October 2017, version 2.0 was released in May 2023.

## Contributing

We welcome contributions to the project.

### Quickstart

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/gchq/Gaffer?quickstart=1)

To quickly and easily get access to an environment with everything installed and setup correctly you can use GitHub Codespaces, or alternatively GitLab GitPod.
These provide remote coding environments using VS Code with the required plugins, Java version and Maven preinstalled.

Our Javadoc can be found [here](http://gchq.github.io/Gaffer/). Gaffer's documentation is kept in the [gaffer-doc](https://github.com/gchq/gaffer-doc) repository and [published on GitHub pages (gchq.github.io)](https://gchq.github.io/gaffer-doc/latest/).

### Local Requirements

For building Gaffer locally you need Java 8 or 11 and Maven installed locally in a *nix environment. MS Windows will work for most purposes, but is not recommended because tests utilising Hadoop fail due to limited Hadoop support on Windows.
Gaffer will compile with newer versions of Java, but some tests will fail because of a lack of support for newer Java in certain external dependencies.

To build Gaffer run `mvn clean install -Pquick` in the top-level directory. This will build all of Gaffer's core libraries and some examples of how to load and query data.

### Contribution Process

Detailed information on our ways of working can be found [in our developer docs](https://gchq.github.io/gaffer-doc/latest/development-guide/ways-of-working). In brief:

- Sign the [GCHQ Contributor Licence Agreement](https://cla-assistant.io/gchq/Gaffer)
- Push your changes to a fork
- Submit a pull request

### Inclusion in other projects

Gaffer is hosted on [Maven Central](https://mvnrepository.com/search?q=uk.gov.gchq.gaffer) and can easily be incorporated into your own maven projects.

To use Gaffer from the Java API the only required dependencies are the Gaffer graph module and a store module for the specific database technology used to store the data, e.g. for the Accumulo store:

```xml
<dependency>
    <groupId>uk.gov.gchq.gaffer</groupId>
    <artifactId>graph</artifactId>
    <version>${gaffer.version}</version>
</dependency>
<dependency>
    <groupId>uk.gov.gchq.gaffer</groupId>
    <artifactId>accumulo-store</artifactId>
    <version>${gaffer.version}</version>
</dependency>
```

This will include all other mandatory dependencies. Other (optional) components can be added to your project as required.

## Related repositories

The [gafferpy](https://github.com/gchq/gafferpy) repository contains a python shell that can execute operations.

The [gaffer-docker](https://github.com/gchq/gaffer-docker) repository contains the code needed to run Gaffer using Docker or Kubernetes.

The [koryphe](https://github.com/gchq/koryphe) repository contains an extensible functions library for filtering, aggregating and transforming data
based on the Java Function API. It is a dependency of Gaffer.

## License

Gaffer is licensed under the Apache 2 license and is covered by [Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/).

```
Copyright 2016-2023 Crown Copyright

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.
```


[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/Microsoft/mssql-jdbc/master/LICENSE)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.microsoft.sqlserver/mssql-jdbc/badge.svg)](http://mvnrepository.com/artifact/com.microsoft.sqlserver/mssql-jdbc)
[![Javadocs](http://javadoc.io/badge/com.microsoft.sqlserver/mssql-jdbc.svg)](http://javadoc.io/doc/com.microsoft.sqlserver/mssql-jdbc)
[![Gitter](https://img.shields.io/gitter/room/badges/shields.svg)](https://gitter.im/Microsoft/mssql-developers)

# Microsoft JDBC Driver for SQL Server

Welcome to the Microsoft JDBC Driver for SQL Server project!

The Microsoft JDBC Driver for SQL Server is a Type 4 JDBC driver that provides database connectivity through the standard JDBC application program interfaces (APIs) available in the Java Platform, Enterprise Editions. The Driver provides access to Microsoft SQL Server and Azure SQL Database from any Java application, application server, or Java-enabled applet.

Releases can be found on the [GitHub Releases](https://github.com/microsoft/mssql-jdbc/releases) page, in the [Microsoft JDBC Documentation](https://learn.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-ver16), or via Maven. Starting from preview release 12.1.0, each release contains two versions of the driver. One for use with Java 8 (jre8), and one for use with version Java 11 and above (jre11).

We hope you enjoy using the Microsoft JDBC Driver for SQL Server.

Microsoft JDBC driver for SQL Server Team

## Take our survey

Let us know how you think we're doing.

## Status of Most Recent Builds
| Azure Pipelines (Windows) | Azure Pipelines (Linux) | Azure Pipelines (MacOS) |
|--------------------------|--------------------------|--------------------------|
| [![Build Status](https://sqlclientdrivers.visualstudio.com/public/_apis/build/status/JDBC/public-mssql-jdbc.windows?branchName=main)](https://sqlclientdrivers.visualstudio.com/public/_build/latest?definitionId=825&branchName=main) | [![Build Status](https://sqlclientdrivers.visualstudio.com/public/_apis/build/status/JDBC/public-mssql-jdbc.linux?branchName=main)](https://sqlclientdrivers.visualstudio.com/public/_build/latest?definitionId=823&branchName=main) | [![Build Status](https://sqlclientdrivers.visualstudio.com/public/_apis/build/status/JDBC/CI-MacOS?branchName=main)](https://sqlclientdrivers.visualstudio.com/public/_build/latest?definitionId=824&branchName=main) |

## Announcements
What's coming next?  We will look into adding a more comprehensive set of tests, improving our javadocs, and start developing the next set of features.

## Get Started
[**Getting started with SQL Server and Java**](https://github.com/AzureSQLDB/sql-driver-examples/blob/main/examples/sql/drivers/java-driver-example.md)

## Build
### Prerequisites
* Java 11+
* [Maven 3.5.0+](http://maven.apache.org/download.cgi)
* An instance of SQL Server or Azure SQL Database that you can connect to.

### Build the JAR files
Maven builds automatically trigger a set of verification tests to run.  For these tests to pass, you will first need to add an environment variable in your system called `mssql_jdbc_test_connection_properties` to provide the [correct connection properties](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url) for your SQL Server or Azure SQL Database instance.

To build the jar files, you must use minimum version of Java 11 with Maven. You may choose to build JDBC 4.3 compliant jar file (for use with JRE 11 or newer JRE versions) and/or a JDBC 4.2 compliant jar file (for use with JRE 8).

* Maven:
	1. If you have not already done so, add the environment variable `mssql_jdbc_test_connection_properties` in your system with the connection properties for your SQL Server or SQL DB instance.
	2. Run one of the commands below to build a JRE 11 and newer versions compatible jar or JRE 8 compatible jar in the `\target` directory.
        * Run `mvn install -Pjre22`. This creates JRE 22 compatible jar in `\target` directory which is JDBC 4.3 compliant (Build with JDK 22).
        * Run `mvn install -Pjre21`. This creates JRE 21 compatible jar in `\target` directory which is JDBC 4.3 compliant (Build with JDK 21+).
        * Run `mvn install -Pjre17`. This creates JRE 17 compatible jar in `\target` directory which is JDBC 4.3 compliant (Build with JDK 17+).
        * Run `mvn install -Pjre11`. This creates JRE 11 compatible jar in `\target` directory which is JDBC 4.3 compliant (Build with JDK 11+).
        * Run `mvn install -Pjre8`. This creates JRE 8 compatible jar in `\target` directory which is JDBC 4.2 compliant (Build with JDK 11+).

* Gradle:
	1. If you have not already done so, add the environment variable `mssql_jdbc_test_connection_properties` in your system with the connection properties for your SQL Server or SQL DB instance.
	2. Run one of the commands below to build a JRE 11 and newer versions compatible jar or JRE 8 compatible jar in the `\build\libs` directory.
        * Run `gradle build -PbuildProfile=jre22`. This creates JRE 22 compatible jar in `\build\libs` directory which is JDBC 4.3 compliant (Build with JDK 22).
        * Run `gradle build -PbuildProfile=jre21`. This creates JRE 21 compatible jar in `\build\libs` directory which is JDBC 4.3 compliant (Build with JDK 21+).
        * Run `gradle build -PbuildProfile=jre17`. This creates JRE 17 compatible jar in `\build\libs` directory which is JDBC 4.3 compliant (Build with JDK 17+).
        * Run `gradle build -PbuildProfile=jre11`. This creates JRE 11 compatible jar in `\build\libs` directory which is JDBC 4.3 compliant (Build with JDK 11+).
        * Run `gradle build -PbuildProfile=jre8`. This creates JRE 8 compatible jar in `\build\libs` directory which is JDBC 4.2 compliant (Build with JDK 11+).

## Resources

### Documentation
API reference documentation is available in [Javadocs](https://aka.ms/jdbcjavadocs).

This driver is documented on [Microsoft Docs](https://docs.microsoft.com/sql/connect/jdbc/).

### Sample Code
For samples, please see the `src\sample` directory.

### Download the DLLs
For some features (e.g. Integrated Authentication and Distributed Transactions), you may need to use the `sqljdbc_xa` and `mssql-jdbc_auth-<version>.<arch>` DLLs. They can be found in the package that can be downloaded from [Microsoft](https://aka.ms/downloadmssqljdbc). `mssql-jdbc_auth-<version>.<arch>` can also be downloaded from [Maven](https://mvnrepository.com/artifact/com.microsoft.sqlserver/mssql-jdbc_auth).

### Download the driver
Don't want to compile anything?

We're now on the Maven Central Repository. Add the following to your POM file to get the most stable release:

```xml
<dependency>
	<groupId>com.microsoft.sqlserver</groupId>
	<artifactId>mssql-jdbc</artifactId>
	<version>12.6.0.jre11</version>
</dependency>
```
The driver can be downloaded from [Microsoft](https://aka.ms/downloadmssqljdbc). For driver version 12.1.0 and greater, please use the jre11 version when using Java 11 or greater, and the jre8 version when using Java 8.

To get the latest version of the driver, add the following to your POM file:

```xml
<dependency>
	<groupId>com.microsoft.sqlserver</groupId>
	<artifactId>mssql-jdbc</artifactId>
	<version>12.6.0.jre11</version>
</dependency>
```

### Using driver as Java Module
Starting from version 7.0.0, the driver Jars (jre10 and above) will expose 'Automatic-Module' as **'com.microsoft.sqlserver.jdbc'**. The supporting Jar can now be added to ModulePath to access this module.

## Dependencies
This project has following dependencies:

Compile Time:
 - `com.azure:azure-security-keyvault-keys` : Microsoft Azure Client Library For KeyVault Keys (optional)
 - `com.azure:azure-identity` : Microsoft Azure Client Library For Identity (optional)
 - `org.bouncycastle:bcprov-jdk18on` : Bouncy Castle Provider for Always Encrypted with secure enclaves feature with JAVA 8 only (optional)
 - `com.google.code.gson:gson` : Gson for Always Encrypted with secure enclaves feature (optional)

Test Time:
 - `junit:jar`   : For Unit Test cases.

### Dependency Tree
One can see all dependencies including Transitive Dependency by executing following command.
```
mvn dependency:tree
```

### Azure Key Vault and Azure Active Directory Authentication Dependencies
Projects that require either of the two features need to explicitly declare the dependency in their pom file.

***For Example:*** If you are using *Azure Active Directory Authentication feature* then you need to declare the *azure-identity* dependency in your project's POM file. Please see the following snippet:

```xml
<dependency>
	<groupId>com.microsoft.sqlserver</groupId>
	<artifactId>mssql-jdbc</artifactId>
	<version>12.6.0.jre11</version>
	<scope>compile</scope>
</dependency>

<dependency>
	<groupId>com.azure</groupId>
	<artifactId>azure-identity</artifactId>
	<version>1.3.3</version>
</dependency>

```

***For Example:*** If you are using *Azure Key Vault feature* then you need to declare the *azure-identity* and *azure-security-keyvault-keys* dependencies in your project's POM file. Please see the following snippet:

```xml
<dependency>
	<groupId>com.microsoft.sqlserver</groupId>
	<artifactId>mssql-jdbc</artifactId>
	<version>12.6.0.jre11</version>
	<scope>compile</scope>
</dependency>

<dependency>
	<groupId>com.azure</groupId>
	<artifactId>azure-identity</artifactId>
	<version>1.3.3</version>
</dependency>

<dependency>
	<groupId>com.azure</groupId>
	<artifactId>azure-security-keyvault-keys</artifactId>
	<version>4.2.8</version>
</dependency>
```

***Please note*** as of the v6.2.2, the way to construct a `SQLServerColumnEncryptionAzureKeyVaultProvider` object has changed. Please refer to this [Wiki](https://github.com/Microsoft/mssql-jdbc/wiki/New-Constructor-Definition-for-SQLServerColumnEncryptionAzureKeyVaultProvider-after-6.2.2-Release) page for more information.

### 'useFmtOnly' connection property Dependencies
When setting 'useFmtOnly' property to 'true' for establishing a connection or creating a prepared statement, *antlr-runtime* dependency is required to be added in your project's POM file.  Please see the following snippet:

```xml
<dependency>
	<groupId>com.microsoft.sqlserver</groupId>
	<artifactId>mssql-jdbc</artifactId>
	<version>12.6.0.jre11</version>
</dependency>

<dependency>
	<groupId>org.antlr</groupId>
	<artifactId>antlr4-runtime</artifactId>
	<version>4.9.2</version>
</dependency>
```

## Guidelines for Creating Pull Requests
We love contributions from the community.  To help improve the quality of our code, we encourage you to use the mssql-jdbc_formatter.xml formatter provided on all pull requests.

Thank you!

## Guidelines for Reporting Issues
We appreciate you taking the time to test the driver, provide feedback and report any issues. It would be extremely helpful if you:

- Report each issue as a new issue (but check first if it's already been reported)
- Try to be detailed in your report. Useful information for good bug reports include:
  * What you are seeing and what the expected behavior is
  * Which jar file?
  * Environment details: e.g. Java version, client operating system?
  * Table schema (for some issues the data types make a big difference!)
  * Any other relevant information you want to share
- Try to include a Java sample demonstrating the isolated problem.

Thank you!

### Reporting security issues and security bugs
Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) [secure@microsoft.com](mailto:secure@microsoft.com). You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://technet.microsoft.com/en-us/security/ff852094.aspx).

## Release roadmap and standards
Our goal is to release regular updates which improve the driver and bring new features to users. Stable, production quality releases happen twice a year, targeting the first and third quarters of the calendar year. They are tested against a comprehensive matrix of supported operating systems, Java versions, and SQL Server versions. Stable releases are accompanied by additional localized packages, which are available on the Microsoft website.

Preview releases happen approximately monthly between stable releases. This gives users an opportunity to try out new features and provide feedback on them before they go into stable releases. Preview releases also include frequent bug fixes for customers to verify without having to wait for a stable release. Preview releases are only available in English. While they are tested, preview releases do not necessarily go through the same rigorous, full test matrix and review process as stable releases.

You can see what is going into a future release by monitoring [Milestones](https://github.com/Microsoft/mssql-jdbc/milestones) in the repository.

### Version conventions
Starting with 6.0, stable versions have an even minor version. For example, 6.0, 6.2, 6.4, 7.0, 7.2, 7.4, 8.2, 8.4, 9.2, 9.4, 10.2, 11.2, 12.2, 12.4, 12.6. Preview versions have an odd minor version. For example, 6.1, 6.3, 6.5, 7.1, 7.3, 8.1, 9.1, 10.1, 11.1, 12.1, 12.3, 12.5, and so on.

## Contributors
Special thanks to everyone who has contributed to the project.

Up-to-date list of contributors: https://github.com/Microsoft/mssql-jdbc/graphs/contributors

Here are our Top 15 contributors from the community:
- pierresouchay (Pierre Souchay)
- marschall (Philippe Marschall)
- JamieMagee (Jamie Magee)
- sehrope (Sehrope Sarkuni)
- gordthompson (Gord Thompson)
- simon04 (Simon Legner)
- gstojsic
- cosmofrit
- mmimica  (Milan Mimica)
- harawata (Iwao AVE!)
- rPraml (Roland Praml)
- laeubi (Christoph Laubrich)
- worldtiki (Daniel Albuquerque)
- shayaantx
- mnhubspot

## License
The Microsoft JDBC Driver for SQL Server is licensed under the MIT license. See the [LICENSE](https://github.com/Microsoft/mssql-jdbc/blob/master/LICENSE) file for more details.

## Code of conduct
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.


# Example Code Repository

[![CI](https://github.com/thombergs/code-examples/workflows/CI/badge.svg)](https://github.com/thombergs/code-examples/actions?query=workflow%3ACI)

This repo contains example projects which show how to use different (not only) Java technologies.
The examples are usually accompanied by a blog post on [https://reflectoring.io](https://reflectoring.io).

See the READMEs in each subdirectory of this repo for more information on each module.


Introduction
------------

Welcome to the BaseX Open Source project. We are interested in your feedback:

* Please send new suggestions and bug reports to our
  [basex-talk](https://basex.org/open-source/) mailing list.
* Confirmed bugs and feature requests are discussed in our issue tracker.
* We invite you to contribute to our [Documentation](https://docs.basex.org/).

Compiling BaseX
---------------

The code base of BaseX can be accessed on [GitHub]: https://github.com/BaseXdb/basex

JDK 11 and JUnit are currently required to compile the complete sources of the
main project. Our default IDE is Eclipse.

You can launch the following classes, which are all placed in the basex-core
directory and the `org.basex` main package:

    BaseX        : console mode
    BaseXServer  : server instance, waiting for requests
    BaseXClient  : console mode, interacting with the server
    BaseXGUI     : graphical user interface

Moreover, try `-h` to list the available command line options. For example, you
can use BaseX to process XQuery expressions without entering the console.

Using Eclipse
-------------

BaseX is being developed with the Eclipse environment. Some style guidelines
are integrated in the sources of BaseX; they are being embedded as soon as you
open the project.

### Running BaseX

The following steps can be performed to start BaseX with Eclipse:

 - Press `Run` → `Run...`
 - Create a new `Java Application` launch configuration
 - Select `basex` as Project
 - Choose a `Main class` (e.g., org.basex.BaseXGUI)
 - Launch the project via `Run`

Best regards, have fun,

Your BaseX Team

[documentation]: https://docs.basex.org
[bug tracker]: https://github.com/BaseXdb/BaseX/issues