# What is joynr?
joynr is a web-based communication framework for Java, C++, and JavaScript applications
wanting to interact with other applications, no matter whether they're deployed on consumer
devices, vehicles, backend infrastructure or in the cloud.

joynr makes writing distributed applications easy, as it:

* takes care of determining the most appropriate communication paradigm to talk with the desired
	end point
* provides a simple application programming interface to the joynr framework
* speeds up integration of new applications

... allowing you to focus on building your distributed application.

# How do I write joynr?
joynr is correctly written as "joynr". It is not an abbreviation nor a combination of words.

# Documentation
Have a peek at our documentation for more information:
* [Get to know joynr](wiki/Home.md) -- Introduction to joynr
* [Using joynr](wiki/using_joynr.md) -- General information about joynr
	* [Franca IDL overview](wiki/franca.md) -- Introduction to Franca Interface Definition Language
		used for modelling
	* [joynr Code Generator](wiki/generator.md) -- Using the joynr Code Generator to generate code
		from the Franca model files
	* [Infrastructure](wiki/infrastructure.md) -- Setting up the joynr infrastructure components for your environment
	* [Multiple backends](wiki/multiple-backends.md) -- joynr with multiple backends (multiple global connections)
* Building joynr
	* [Building joynr Java](wiki/java_building_joynr.md) -- Building joynr Java and common components
		yourself
	* [Building joynr C++](wiki/cpp_building_joynr.md) -- Building joynr C++ yourself
	* [Building joynr JavaScript](wiki/javascript_building_joynr.md) -- Building joynr JavaScript yourself
* Developer documentation
	* Java and JEE
		* [Java Developer Guide](wiki/java.md) -- Developing Java applications with joynr
		* [Java Configuration Reference](wiki/JavaSettings.md) -- a reference of the available
			configuration options for Java and JEE joynr applications
		* [MQTT Clients](wiki/java_mqtt_clients.md) -- how to choose and configure the MQTT client to
			use for a Java runtime.
		* [JEE Developer Guide](wiki/jee.md) -- Developing JEE applications with joynr
		* [Glassfish Settings](wiki/Glassfish-settings.md) -- Settings you need to run joynr backend
			services on Glassfish application servers
	* Android
		* [Android Developer Guide](wiki/Android.md) -- Developing Android applications with joynr
	* C++
		* [C++ Developer Guide](wiki/cplusplus.md) -- Developing C++ applications with joynr
		* [C++ cluster-controller Settings](wiki/ClusterControllerSettings.md) -- C++ cluster-controller settings
	* JavaScript / TypeScript
		* [JavaScript Developer Guide](wiki/javascript.md) -- Developing JavaScript applications with joynr
		* [JavaScript Configuration Reference](wiki/JavaScriptSettings.md) -- a reference of the available
			configuration options for JavaScript and TypeScript joynr applications
        * *For details about running the joynr Javascript tests see [joynr Javascript Testing](javascript_testing.md)*
* Tutorials
	* [Radio App Tutorial](wiki/Tutorial.md) -- Create your first joynr app: define a communication
		interface, implement a provider, and create a consumer
	* [Broadcast Tutorial](wiki/Broadcast-Tutorial.md) -- Learn about (selective) broadcasts and
		implement a geocast
	* [JavaScript Tutorial](wiki/JavaScriptTutorial.md) -- Create your first joynr JavaScript application
* [Distribution](wiki/Distribution.md) -- How to get joynr
* [Versioning scheme](wiki/JoynrVersioning.md) -- Meaning of joynr version numbers
* [Release Notes](wiki/ReleaseNotes.md) -- All joynr releases and API changes at a glance


![Mantle logo](https://raw.github.com/SlimeKnights/Mantle/master/src/main/resources/Mantle.png)
# Mantle
**Shared code for Forge mods**

## Compile from Source
Note: Git MUST be installed and in the system path to use our scripts.
* setup: Import as a gradle project into your desired IDE. Run `gradlew[.bat] [genIntellijRuns|genEclipseRuns]` to be able to launch the game
* build: Run [gradle]in the repository root: `gradlew[.bat] build`
* if obscure gradle issues are found try running `gradlew clean` or/and `gradlew cleanCache`

## Issue reporting
Please include the following:

* Minecraft version
* Mantle version
* Versions of Mantle dependant mods
* Forge version/build
* Versions of any mods potentially related to the issue
* Any relevant screenshots are greatly appreciated.
* For crashes:
	* Steps to reproduce
	* ForgeModLoader-client-0.log (the FML log) from the root folder of the client

## Licenses
The MIT License (MIT)
Copyright (c) 2013-2022 Slime Knights (mDiyo, fuj1n, Sunstrike, progwml6, pillbox, alexbegt, KnightMiner)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Any alternate licenses are noted where appropriate.


# Ambry

[![Github Actions CI](https://github.com/linkedin/ambry/actions/workflows/github-actions.yml/badge.svg)](https://github.com/linkedin/ambry/actions/workflows/github-actions.yml)
[![codecov.io](https://codecov.io/github/linkedin/ambry/branch/master/graph/badge.svg)](https://codecov.io/github/linkedin/ambry)
[![license](https://img.shields.io/github/license/linkedin/ambry.svg)](LICENSE)

Ambry is a distributed object store that supports storage of trillions of small immutable objects (50K -100K) as well as billions of large objects. It was specifically designed to store and serve media objects in web companies. However, it can be used as a general purpose storage system to store DB backups, search indexes or business reports. The system has the following characterisitics:

1. Highly available and horizontally scalable
2. Low latency and high throughput
3. Optimized for both small and large objects
4. Cost effective
5. Easy to use

Requires at least JDK 1.8.

## Documentation
Detailed documentation is available at https://github.com/linkedin/ambry/wiki

## Research
Paper introducing Ambry at [SIGMOD 2016](http://sigmod2016.org/) -> http://dprg.cs.uiuc.edu/data/files/2016/ambry.pdf

Reach out to us at ambrydev@googlegroups.com if you would like us to list a paper that is based off of research on Ambry.

## Getting Started
##### Step 1: Download the code, build it and prepare for deployment.
To get the latest code and build it, do

    $ git clone https://github.com/linkedin/ambry.git
    $ cd ambry
    $ ./gradlew allJar
    $ cd target
    $ mkdir logs
Ambry uses files that provide information about the cluster to route requests from the frontend to servers and for replication between servers. We will use a simple clustermap that contains a single server with one partition. The partition will use `/tmp` as the mount point.
##### Step 2: Deploy a server.
    $ nohup java -Dlog4j2.configurationFile=file:../config/log4j2.xml -jar ambry.jar --serverPropsFilePath ../config/server.properties --hardwareLayoutFilePath ../config/HardwareLayout.json --partitionLayoutFilePath ../config/PartitionLayout.json > logs/server.log &

Through this command, we configure the log4j properties, provide the server with configuration options and cluster definitions and redirect output to a log. Note down the process ID returned (`serverProcessID`) because it will be needed for shutdown.
The log will be available at `logs/server.log`. Alternately, you can change the log4j properties to write the log messages to a file instead of standard output.
##### Step 3: Deploy a frontend.
    $ nohup java -Dlog4j2.configurationFile=file:../config/log4j2.xml -cp "*" com.github.ambry.frontend.AmbryFrontendMain --serverPropsFilePath ../config/frontend.properties --hardwareLayoutFilePath ../config/HardwareLayout.json --partitionLayoutFilePath ../config/PartitionLayout.json > logs/frontend.log &

Note down the process ID returned (`frontendProcessID`) because it will be needed for shutdown. Make sure that the frontend is ready to receive requests.

    $ curl http://localhost:1174/healthCheck
    GOOD
The log will be available at `logs/frontend.log`. Alternately, you can change the log4j properties to write the log messages to a file instead of standard output.
##### Step 4: Interact with Ambry !
We are now ready to store and retrieve data from Ambry. Let us start by storing a simple image. For demonstration purposes, we will use an image `demo.gif` that has been copied into the `target` folder.
###### POST
    $ curl -i -H "x-ambry-service-id:CUrlUpload"  -H "x-ambry-owner-id:`whoami`" -H "x-ambry-content-type:image/gif" -H "x-ambry-um-description:Demonstration Image" http://localhost:1174/ --data-binary @demo.gif
    HTTP/1.1 201 Created
    Location: AmbryID
    Content-Length: 0
The CUrl command creates a `POST` request that contains the binary data in demo.gif. Along with the file data, we provide headers that act as blob properties. These include the size of the blob, the service ID, the owner ID and the content type.
In addition to these properties, Ambry also has a provision for arbitrary user defined metadata. We provide `x-ambry-um-description` as user metadata. Ambry does not interpret this data and it is purely for user annotation.
The `Location` header in the response is the blob ID of the blob we just uploaded.
###### GET - Blob Info
Now that we stored a blob, let us verify some properties of the blob we uploaded.

    $ curl -i http://localhost:1174/AmbryID/BlobInfo
    HTTP/1.1 200 OK
    x-ambry-blob-size: {Blob size}
    x-ambry-service-id: CUrlUpload
    x-ambry-creation-time: {Creation time}
    x-ambry-private: false
    x-ambry-content-type: image/gif
    x-ambry-owner-id: {username}
    x-ambry-um-desc: Demonstration Image
    Content-Length: 0
###### GET - Blob
Now that we have verified that Ambry returns properties correctly, let us obtain the actual blob.

    $ curl http://localhost:1174/AmbryID > demo-downloaded.gif
    $ diff demo.gif demo-downloaded.gif
    $
This confirms that the data that was sent in the `POST` request matches what we received in the `GET`. If you would like to see the image, simply point your browser to `http://localhost:1174/AmbryID` and you should see the image that was uploaded !
###### DELETE
Ambry is an immutable store and blobs cannot be updated but they can be deleted in order to make them irretrievable. Let us go ahead and delete the blob we just created.

    $ curl -i -X DELETE http://localhost:1174/AmbryID
    HTTP/1.1 202 Accepted
    Content-Length: 0
You will no longer be able to retrieve the blob properties or data.

    $ curl -i http://localhost:1174/AmbryID/BlobInfo
    HTTP/1.1 410 Gone
    Content-Type: text/plain; charset=UTF-8
    Content-Length: 17
    Connection: close

    Failure: 410 Gone
##### Step 5: Stop the frontend and server.
    $ kill -15 frontendProcessID
    $ kill -15 serverProcessID
You can confirm that the services have been shut down by looking at the logs.
##### Additional information:
In addition to the simple APIs demonstrated above, Ambry provides support for `GET` of only user metadata and `HEAD`. In addition to the `POST` of binary data that was demonstrated, Ambry also supports `POST` of `multipart/form-data` via CUrl or web forms.
Other features of interest include:
* **Time To Live (TTL)**: During `POST`, a TTL in seconds can be provided through the addition of a header named `x-ambry-ttl`. This means that Ambry will stop serving the blob after the TTL has expired. On `GET`, expired blobs behave the same way as deleted blobs.
* **Private**: During `POST`, providing a header named `x-ambry-private` with the value `true` will mark the blob as private. API behavior can be configured based on whether a blob is public or private.


## TEAM Engine

### Overview

TEAM Engine (Test, Evaluation, And Measurement Engine) is a Java-based application for
testing web services and other information resources. It executes test suites developed
using the popular TestNG framework, OGC Compliance Test Language (CTL) scripts, and possibly
other JVM-friendly languages. It is lightweight and easy to run from the command-line or
as a web application.

TEAM Engine can be used to test almost any type of service or information resource. It is
the official test harness used by the Open Geospatial Consortium's (OGC) [compliance program](https://www.ogc.org/resources/compliance/).
Visit the [project documentation website](https://opengeospatial.github.io/teamengine/)
for more information.

An installation is maintained by the OGC at https://cite.ogc.org/teamengine/.

### How to build

Java 17 and [Apache Maven](http://maven.apache.org/) 3.9 are required to build TEAM Engine.

* Clone the repository:

   `git clone https://github.com/opengeospatial/teamengine.git`

* Change to the directory containing the local repository:

   `cd teamengine`

* Execute the Maven install phase to add the build artifacts to the local repository:

   `mvn install`

### More information

The following sources include documentation about how to install the tests, run TEAM Engine via the
command line or as a web application in a Java servlet container.

* An extensive tutorial can be found in the [doc folder](https://github.com/opengeospatial/teamengine/blob/master/src/site/doc/en/index.rst).

* A _Getting Started Guide_ is available at the [project documentation website](https://opengeospatial.github.io/teamengine/).
This can also be created by generating the site documentation (which includes a PDF
document in the target/pdf directory):

   `mvn site`

### License

[Apache 2.0 License](LICENSE.txt)

### How to contribute

If you would like to get involved, you can:

* [Report an issue](https://github.com/opengeospatial/teamengine/issues) such as a defect or an
enhancement request
* Help to resolve an [open issue](https://github.com/opengeospatial/teamengine/issues?q=is%3Aopen)
* Fix a bug: Fork the repository, apply the fix, and create a pull request
* Add a new feature: Fork the repository, implement (and test) the feature on a new topic
branch, and then create a pull request

### Mailing Lists

The [cite-forum](https://lists.ogc.org/mailman/listinfo/cite-forum) is where software developers discuss issues
and solutions related to OGC tests and TEAM Engine.

Contributors are expected to observe the project's [code of conduct](https://github.com/opengeospatial/teamengine/blob/master/CODE_OF_CONDUCT.md).

### More Information

Visit the [CITE wiki](https://github.com/opengeospatial/cite/wiki) for more information about the
CITE program and tools.


BridgeDb
========

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.593034.svg)](https://doi.org/10.5281/zenodo.593034)
[![Actions Status](https://github.com/bridgedb/BridgeDb/workflows/build/badge.svg)](https://github.com/bridgedb/BridgeDb/actions)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.bridgedb/bridgedb-bundle/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.bridgedb/bridgedb-bundle)
[![codecov](https://codecov.io/gh/bridgedb/BridgeDb/branch/master/graph/badge.svg?token=F0kJdoEt0x)](https://codecov.io/gh/bridgedb/BridgeDb)
[![NWO](https://img.shields.io/badge/NWO%20Open%20Science-203.001.121-orange)](https://www.nwo.nl/en/projects/203001121)

BridgeDb is currently tested with Java 11 and higher (3.0.x releases and master branch).

Using BridgeDb dependencies
---------------------------

The [BridgeDb releases](https://github.com/bridgedb/BridgeDb/releases) are published to
[Maven Central](https://search.maven.org/artifact/org.bridgedb/bridgedb-bundle), which means you can use the BridgeDb JARs without needing to compile BridgeDb.

Usage depends on which module you require. The examples below assumes artifact `org.bridgedb.bio` and version `3.0.26`:

For [Maven](https://maven.apache.org/):

```xml
<dependencies>
    <dependency>
        <groupId>org.bridgedb</groupId>
        <artifactId>org.bridgedb.bio</artifactId>
        <version>3.0.26</version>
    </dependency>
</dependencies>
```

For [Gradle](https://gradle.org/):

```gradle
compile group: 'org.bridgedb', name: 'org.bridgedb.bio', version: '3.0.26'
```

For [Ivy](http://ant.apache.org/ivy/):

```xml
<dependency org="org.bridgedb" name="org.bridgedb.bio" rev="3.0.26"/>
```

For [Buildr](https://buildr.apache.org/):

```buildr
'org.bridgedb:org.bridgedb.bio:jar:3.0.26'
```

Compilation
-----------

If you've obtained the source code of BridgeDb, you should be
able to compile with a simple:

```shell
mvn clean install -Dgpg.skip
```

You can find the libraries in the folder called "target", in each sublibrary folder (used to be called "dist" in ant).

If you want to ignore failing tests, e.g. because you are not online,
add this option: -Dmaven.test.failure.ignore=true. Furthermore,
note that 'mvn clean compile' fails.

Command line tools
------------------

The BridgeDb distribution comes with a few command line tools. You
can try:

```shell
bash info.sh <database.bridge>
bash qc.sh <database.bridge> <database2.bridge>
bash voidtool.sh <database.bridge> <fileName.void>
```

Checking for regressions
------------------------

You may want to run the following commands to detect regressions,
which is particularly important before starting to make a release:

```shell
mvn clean test
```

Note that the first call may fail a number of unit tests, like for those
of `IDMapperCapabilitiesTest`. For that one, this is because it is an
abstract class that should not actually be run by JUnit as test suite.

Note also that the second one may fail because BridgeDb module dependencies
may not be resolved yet.

Several tests also depend on a running MySQL backend or running BridgeDb
webservice. You can exclude these tests in Maven with:

```shell
mvn clean test -Djunit5.excludeGroups=webservice,mysql
```

The JUnit5 tagging also allows to specifically test the MySQL-backend tests,
for example with:

```shell
mvn clean test junit5.groups=mysql
```

Updating the datasources
------------------------

The `datasources.tsv` and `organisms.tsv` files were separated from this
repository, and this BridgeDb library is regularly updated for releases
from [https://github.com/bridgedb/datasources](https://github.com/bridgedb/datasources).

```shell
wget -O ./org.bridgedb.bio/src/main/resources/org/bridgedb/bio/datasources.tsv https://bridgedb.github.io/datasources/datasources.tsv
wget -O ./org.bridgedb.bio/src/main/resources/org/bridgedb/bio/datasources_headers.tsv https://bridgedb.github.io/datasources/datasources_headers.tsv
wget -O ./org.bridgedb.bio/src/main/resources/org/bridgedb/bio/organisms.tsv https://bridgedb.github.io/datasources/organisms.tsv
cp ./org.bridgedb.bio/src/main/resources/org/bridgedb/bio/*.tsv ./org.bridgedb.bio/resources/org/bridgedb/bio/.
```

The last line makes a copy for backwards compatibility.

Making releases
---------------

If it is time for a release, first, update `org.bridgedb/src/main/resources/version.props` (for BridgeDb),
this `README.md` and `CITATION.cff` (for Zenodo).

To make the release, run the following commands. Mind you, this requires you
to have an approved Sonatype (http://oss.sonatype.org/) account with push rights:

```shell
mvn versions:set -DnewVersion=3.0.26
mvn clean deploy
```

The second command will make the actual push. These commands will update the version
and everything.

To make a development (SNAPSHOT) release, use:

```shell
mvn versions:set -DnewVersion=3.0.27-SNAPSHOT
mvn clean deploy
```

Library dependencies
--------------------

If you do not use all mappers, you do not need to include all
libraries in the dist directory in your project.

Here is a brief overview that will help you to find out
which ones you need. For questions, you can always contact our mailing list.

 * org.bridgedb.jar - always needed. This includes the tab-delimited file driver.
 * org.bridgedb.bio.jar - includes the BioDataSource enum, often needed
 * org.bridgedb.webservice.cronos.jar - needed for CRONOS webservice
 * org.bridgedb.webservice.synergizer.jar - needed for Synergizer webservice
 * org.bridgedb.webservice.picr.jar - needed for PICR webservice
 * org.bridgedb.server.jar - the BridgeRest SERVER, not needed if you only want to access BridgeRest or BridgeWebservice as client
 * org.bridgedb.tools.batchmapper.jar - Contains the batchmapper command line tool

org.bridgedb.jar and org.bridgedb.bio.jar do not need any other jar files to work.
Most of the other jar files in dist/ are part of the SOAP libraries needed only for
some of the webservices. Look in the lib directory and build.xml of the
respective mappers to find clues which libraries are needed by which service.

Additional packages added for version 2 (mainly for URI support needed for OpenPHACTS)
org.bridgedb.utils - adds logging and some utils - Needed for all of modules below
org.bridgedb.sql - Alternative SQL database optimized for speed not size

org.bridgedb.ws.*  Another version of the Webservice. Runs with and IDMapper

org.bridgedb.rdf   Loads DataSources from rdf and miriam (with URI suppport)

org.bridgedb.uri.sql   Adds support for URIs (requires org.bridgedb.sql)
org.bridgedb.uri.loader  Loads RDF linksets into org.bridgedb.uri.sql. Also creates transitive linksets

org.bridgedb.uri.ws.*  Extends org.bridgedb.ws.* with URI supports from org.bridgedb.uri.sql

Database structure
------------------

For further information about the database structure check [the documentation here](docs/database).

Contact
-------

* Website, wiki and bug tracker: http://www.bridgedb.org
* Mailing list: http://groups.google.com/group/bridgedb-discuss/
* Source code can be obtained from http://github.com/bridgedb/BridgeDb

Authors
-------

BridgeDb and related tools are developed by (alphabetic order):

 * Manas Awasthi
 * Christian Brenninkmeijer
 * Jianjiong Gao
 * Alasdair Gray
 * Isaac Ho
 * Martijn van Iersel
 * Alexander Pico
 * Stian Soiland-Reyes
 * Egon Willighagen
 * Martina Kutmon
 * Jonathan Mélius
 * Anders Riutta
 * Randy Kerber

The lead teams at this moment are (alphabetic order):

 * Gladstone Institutes
 * Maastricht University
 * The University of Manchester

License
-------

BridgeDb is free and open source. It is available under
the conditions of the [Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
See LICENSE-2.0.txt for details.

Configuration For the URI/OpenPHACTS packages ONLY!
=============

Where are configuration files loaded from?
------------------------------------------
BridgeDb looks for the configuration files from the following locations with priority given to those at the top of the list (i.e. location 1 is a
higher priority than 2 etc). Once it finds a configuration file the other locations are ignored.

1. Directly in the run directory  (Mainly for java *.jar runs)
2. Environment Variable `BRIDGEDB_CONFIG` : can be used to point to any location
3. Tomcat configuration folder : `$CATALINA_HOME/conf/BridgeDb`
4. conf/BridgeDb : Allows tomcat 7 to pick up `$CATALINA_HOME/conf/BridgeDb` even if it can not get `$CATALINA_HOME`
4. ../conf/BridgeDb : Allows tomcat 6 to pick up `$CATALINA_HOME/../conf/BridgeDb` even if it can not get `$CATALINA_HOME`
5. Using classLoader getResource : This will pick up the files included in Jars and Wars.

Configuration files
-------------------

* local.properties
* BridgeDB.properties
* log4j.properties
* DataSource.ttl
* lens.properties
* graph.properties

### local.properties
(There is no local properties files included)

This is the recommended place to overwrite individual property values of any other *.properties file.

`local.properties` will overwrite values with the same key in any other properties file.
Properties not overwritten in local will keep their original values.

To install local properties you need to.

1. Create a local.properties file
2. Store it in a location as described above
3. Copy the keys from the original file

### BridgeDB.properties
(Default file is included in build and can be found in org.bridgedb.utils/resources)

This file contains the local setup information which **MUST** be configured correctly for the service to run. It is essential that the
database user, password and database name are correct.

You **MUST** either supply local values matching your local setup or setup your data stores to use the defaults.
The recommended way to overwrite properties is to add a property with the exact (case sensitive) key to local.properties

Database Dependency
-------------------
(for the org.bridgedb.sql package and its dependencies ONLY)

* MySQL **MUST** be installed and running, otherwise it fails to start. Tested with MySQL up to version 5.5
* MySQL databases and users **MUST** be created with CREATE, DROP, INDEX, INSERT, ALTER,
UPDATE, DELETE, and SELECT permissions.

Consult the BridgeDB.properties file for the defaults, or copy and amend the configuration file
to reflect your own setup.

If you are using the default MySQL accounts and databases then execute the file
mysqlConfig.sql from the BridgeDB root directory which will configure your local mysql with the BridgeDb defaults

```shell
mysql -u root -p < mysqlConfig.sql
```

Note that the SQL script will fail, without reverting changes made up to the
point of failure, if any of the user accounts or databases already exist.

RDF Repository and Transitive Directory Dependency
-------------------------
(For org.bridgedb.rdf package and its extensions ONLY)

BridgeDb uses OpenRDF Sesame RDF engine and this is included automatically via Maven.
**WARNING**: All directories **MUST** exists and the (linux) user running tomcat **MUST** have READ/WRITE permission set!
Some of the OpenRDF error message are unclear if this is not the case.

See BridgeDb.properties and change the appropriate property to point to the correct directory.
A Sesame SailNativeStore(s) will be created automatically as long as the loader can create/find the directory,

We recommend changing the relative directories to absolute directories.
Please ensure the parent directories exist and have the correct permissions.

The settings for testing (and therefore compilation) can be left as is as long as the testing user would have permission to create and delete files there.

The BaseURI variable is no longer used but may be in the future so is worth setting correctly.

Other Configuration files
-------------------------
### log4j.properties
(Default file is included in build and can be found in org.bridgedb.utils/resources)

Edit this to change the logger setup.
The default can be found in the Utils Resource directory
Please refer to the log4j documentation for more information.

### DataSource.ttl
(Included in the build and found at org.bridgedb.rdf/resources)

RDF format of all the BridgeDb DataSource(s) and Registered UriPatterns,
Found in $BRIDGEDB_HOME/org.bridgedb.rdf/resources

This file defines all the URI patterns that will match every BridgeDb DataSource.
Warning: As additional UriPatterns are constantly being found and created this file is subject to continuous updates.
Having a local DataSource.ttl is therefore highly discouraged as it will block future updates being discovered.
Instead please push any changes into the version inside the source code.
This file is **NOT** effected by local.properties and
you cannot change existing or add additional datasource URI patterns through local.properties.
If you require local additions that should not become general usage (such as commercial uriPatterns)
then the suggested approach is for you to change the code to use multiple dataSource files.

### lens.properties
(Included in the build and found at org.bridgedb.uri.sql\resources)

This file defines the lenses to be used in the system.
See [Scientific Lenses over Linked Data](http://ceur-ws.org/Vol-951/paper5.pdf)
for more information on what lenses are.

Can and should be added to using local.properties

**WARNING**: As the Lens work is still evolving it is subject to alterations and the format of this file could be changed at any time.
Having a local lens.properties is highly discouraged as it will block future updates being discovered.
Instead please push any changes into the version inside the source code.

Local additions that should not become general usage (such as commercial lens) can be added to the local.properties file.

Note: the fourth part of the key
`lens.lenkey.justification.***`
only serves to keep the keys unique and can have any value.
If extending a key we suggest using `local**` as the fourth part of the justification key to ensure not overwriting general additions.

### graph.properties
(Included in the build and found at org.bridgedb.uri.sql\resources)

This file maps RDF Graphs/Context with the UriPatterns found in that graph.
This allows Map functions to supply a graph name rather than a list of targetUriPatterns

Data in the included file is Open PHACTS specific.

Data Loading
============
All tests should load their required data at the start of the tests.
To load the test data into the live SQL use the method SetupWithTestData in the URI loader package.
The [IMS project](https://github.com/openphacts/IdentityMappingService) also has a data loader which should be used
if the IMS is the deployed project.

Compilation
===========
For URI/Open PHACTS packages

If you've obtained the source code of BridgeDb, you should be
able to compile with a simple:

```shell
mvn clean install
```

Note that for the maven build to run all tests:
1. The MySQL database **MUST** be running and configured as above.
2. (Optional) http://localhost:8080/OPS-IMS to be running the war created by the URI webserver Server module,
   with test data which can be loaded using the class SetupWithTestData in the URI Loader module.
   Maven will skip the client tests if the localhost server is not found.

OPS Webservice Setup.
--------------------

Make sure your local.properties file matches:
* The SQL databases included user names and password
* The RDF parent directories are setup (and accessible) as above.

or you have set up the default databases etc from BridgeDB.properties

Deploy $BridgeDb/org.bridgedb.uri.ws.service/target/org.bridgedb.uri.ws.server-*.war to something like your local
Tomcat webapps directory
To setup databases and add test data run org.bridgedb.uri.loader.SetupLoaderWithTestData. The easiest way is within eclipse since you
can set the OPS_IMS_CONFIG environment variable within the run configuration, Netbeans unfortunately does not allow environment variables to be set
within the IDE.
(Optional) Deploy $BridgeDb/org.bridgedb.ws.service/target/BridgeDb.war
   Both wars share the same SQL data.

Note: If Installing the Open PHACTS IMS and or the Open PHACTS QueryExpander the org.bridgedb.uri.ws.server-*.war should not be deployed but
instead the war appropriate to the other project should be deployed. See the readme within the
other projects for more details.


image:https://github.com/bitcoinj/bitcoinj/workflows/Java%20CI/badge.svg[GitHub Build Status,link=https://github.com/bitcoinj/bitcoinj/actions]
image:https://gitlab.com/bitcoinj/bitcoinj/badges/master/pipeline.svg[GitLab Build Status,link=https://gitlab.com/bitcoinj/bitcoinj/-/pipelines]
image:https://coveralls.io/repos/bitcoinj/bitcoinj/badge.png?branch=master[Coverage Status,link=https://coveralls.io/r/bitcoinj/bitcoinj?branch=master]

image::https://img.shields.io/badge/chat-Join%20bitcoinj--users%20on%20Matrix-blue[Join the bitcoinj-users Matrix room, link=https://matrix.to/#/#bitcoinj-users:matrix.org]

### Welcome to bitcoinj

The bitcoinj library is a Java implementation of the Bitcoin protocol, which allows it to maintain a wallet and send/receive transactions without needing a local copy of Bitcoin Core. It comes with full documentation and some example apps showing how to use it.

### Technologies

* Java 8+ (needs Java 8 API or Android 8.0 API, compiles to Java 8 bytecode) and Gradle 4.4+ for the `core` module
* Java 11+ and Gradle 4.4+ for `tools`, `wallettool` and `examples`
* Java 17+ and Gradle 7.3+ for the JavaFX-based `wallettemplate`
* https://gradle.org/[Gradle] - for building the project
* https://github.com/google/protobuf[Google Protocol Buffers] - for use with serialization and hardware communications

### Getting started

To get started, it is best to have the latest JDK and Gradle installed. The HEAD of the `master` branch contains the latest development code and various production releases are provided on feature branches.

#### Building from the command line

Official builds are currently using JDK 17. Our GitHub Actions build and test with JDK 11, 17 and 21.

To perform a full build (_including_ JavaDocs, unit/integration _tests_, and `wallettemplate`) use JDK 17+.

```
gradle clean build
```
If you are using JDK 17+ and Gradle 7.3+, the build will automatically include the JavaFX-based `wallettemplate` module. The outputs are under the `build` directory.

To perform a full build _without_ unit/integration _tests_ use:
```
gradle clean assemble
```

#### Building from an IDE

Alternatively, just import the project using your IDE. http://www.jetbrains.com/idea/download/[IntelliJ] has Gradle integration built-in and has a free Community Edition. Simply use `File | New | Project from Existing Sources` and locate the `build.gradle` in the root of the cloned project source tree.

### Building and Using the Wallet Tool

The *bitcoinj* `wallettool` subproject includes a command-line Wallet Tool (`wallet-tool`) that can be used to create and manage *bitcoinj*-based wallets (both the HD keychain and SPV blockchain state.) Using `wallet-tool` on Bitcoin's test net is a great way to learn about Bitcoin and *bitcoinj*.

To build an executable shell script that runs the command-line Wallet Tool, use:
```
gradle bitcoinj-wallettool:installDist
```

You can now run the `wallet-tool` without parameters to get help on its operation:
```
./wallettool/build/install/wallet-tool/bin/wallet-tool
```

To create a test net wallet file in `~/bitcoinj/bitcoinj-test.wallet`, you would use:
```
mkdir ~/bitcoinj
```
```
./wallettool/build/install/wallet-tool/bin/wallet-tool --net=TESTNET --wallet=$HOME/bitcoinj/bitcoinj-test.wallet create
```

To sync the newly created wallet in `~/bitcoinj/bitcoinj-test.wallet` with the test net, you would use:
```
./wallettool/build/install/wallet-tool/bin/wallet-tool --net=TESTNET --wallet=$HOME/bitcoinj/bitcoinj-test.wallet sync
```

To dump the state of the wallet in `~/bitcoinj/bitcoinj-test.wallet` with the test net, you would use:
```
./wallettool/build/install/wallet-tool/bin/wallet-tool --net=TESTNET --wallet=$HOME/bitcoinj/bitcoinj-test.wallet dump
```

NOTE: These instructions are for macOS/Linux, for Windows use the `wallettool/build/install/wallet-tool/bin/wallet-tool.bat` batch file with the equivalent Windows command-line commands and options.

### Building the reference build

Our reference build (which is also used for our releases) is running within a container to provide good reproducibility.
Buildah 1.26+, Podman 4.1+ and Docker (with BuildKit) are supported. We tested various combinations of host OSes
(Debian, Ubuntu, macOS, Windows+WSL) and architectures (amd64, arm64). For usage instructions see `build.Containerfile`.

### Example applications

These are found in the `examples` module.

### Where next?

Now you are ready to https://bitcoinj.github.io/getting-started[follow the tutorial].

### Testing a SNAPSHOT build

Building apps with official releases of *bitcoinj* is covered in the https://bitcoinj.github.io/getting-started[tutorial].

If you want to develop or test your app with a https://jitpack.io[Jitpack]-powered build of the latest `master` or `release-0.16` branch of *bitcoinj* follow the dynamically-generated instructions for that branch by following the correct link.

* https://jitpack.io/#bitcoinj/bitcoinj/master-SNAPSHOT[master] branch
* https://jitpack.io/#bitcoinj/bitcoinj/release-0.16-SNAPSHOT[release-0.16] branch


![CFLint](/src/main/resources/CFLint-logo.jpg)

# CFLint

[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.cflint/CFLint/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.cflint/CFLint) [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Codacy Badge](https://api.codacy.com/project/badge/Grade/6f4b01d4d2cb4860b60ac666452071f1)](https://www.codacy.com/app/ryaneberly/CFLint?utm_source=github.com&utm_medium=referral&utm_content=cflint/CFLint&utm_campaign=Badge_Grade) [![Build Status](https://travis-ci.org/cflint/CFLint.svg?branch=master)](https://travis-ci.org/cflint/CFLint)

A static code analysis tool for CFML.

License: [BSD](http://www.opensource.org/licenses/bsd-license.html)

Current Version: 1.5.x

## Versions

See [CHANGELOG.md](/CHANGELOG.md) for further information.

## Project and library organization

CFLint is a project developed and worked on by volunteers. When logging issues please, be nice and considerate. We're here to help. We really appreciate fixes and improvements, so feel free to talk to us and/or provide pull requests.

`/src/main` contains the source code. Tests can be found in `/src/test`. CFLint relies heavily on the [CFParser](https://github.com/cfparser/cfparser) project as well as a bunch of third-party Java libraries.

The master branch is considered our stable codebase. Most of the development happens in the dev branch resp. local development branches for specific issues.

## Building CFLint

1. Fork the repository into your account and clone or download the codebase as a zip-file.
1. Install the tooling of your choice and build via Gradle or Maven (deprecated). CFLint requires Java 8.

    a. Gradle: execute

        gradlew build

    in the cflint directory

    b. Maven: execute

        mvn clean install

    in the cflint directory

    Alternatively, import the CFLint codebase into the IDE of your choice and use its respectively Gradle/Maven integration. This should work out of the box for Eclipse and IntelliJ users.

## Using CFLint - Quickstart Guide

Get the latest version from [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Ccflint) or the [CFLint GitHub release page](https://github.com/cflint/CFLint/releases) or build the project.

If you want to use CFLint from within another Maven project, use:

```xml
<dependency>
    <groupId>com.github.cflint</groupId>
    <artifactId>CFLint</artifactId>
    <version>1.4.0</version>
</dependency>
```

Or always use the latest:

```xml
<dependency>
    <groupId>com.github.cflint</groupId>
    <artifactId>CFLint</artifactId>
    <version>LATEST</version>
</dependency>
```

With the binaries retrieved one or the other way, you can now use CFLint on the command line.

### Use the "-all"-version of the jar-file

    CFLint-1.5.0-all.jar

### Scan a folder with the complete set of rules

    java -jar CFLint-1.5.0-all.jar -folder <baseFolder>

### Scan a file with the complete set of rules

    java -jar CFLint-1.5.0-all.jar -file <fullPathToFile>

### See command line parameters and help

    java -jar CFLint-1.5.0-all.jar -help

# User manual

**Note: This is a work in progress, we're currently collating information from a variety of sources.**

## Introduction

The simplest options for executing CFLint is via the command line. CFLint currently has a UI mode (triggered by -ui on the command line) which will be removed by the latest for CFLint 2.0 - see [Issue #316](https://github.com/cflint/CFLint/issues/316). If you rely on the UI mode, you're unfortunately on your own - no more work will go into this from here onwards.

## Configuration

Alternatively to the command line, you can put `.cflintrc` files into certain directories. Configuring CFLint this way conceptually allows you to run specific rules in specific parts of your application.

CFLint currently supports JSON- and XML-based configuration. XML-based configuration is deprecated in CFLint 1.3.0 and will be removed in CFLint 2.0.

### Rules

When CFLint executes, it scans and parses your code (using CFParser). The syntax tree is then being examined against a set of built-in rules.

In CFLint, those rules are called and implemented as plugins (they live in `/src/main/java/com/cflint/plugins`). By default, all rules will be used against your codebase. This is what a lot of people will do, but using configuration allows you to build a custom scenario to test your code against. See [RULES.md](/RULES.md) for more information on rules and their meaning.

CFLint is opinionated and every release after 1.3.0 will never scan in directories starting with a ```.``` to prevent wasting time of hidden directories such as build configuration, module/library storage or version control information.

### Global configuration

The default and global configuration file is [`/src/main/resources/cflint.definition.json`](/src/main/resources/cflint.definition.json). Common usage of CFLint usually does not require replacing this file.

### Folder-based configuration

Putting a `.cflintrc` file into a directory allows you to specify certain rules that should be executed for this directory and its children. Additionally, you can specify a handful of other properties.

An example `.cflintrc` file is shown below:

```json
{
    "rule": [ ],
    "excludes": [ ],
    "includes": [ {
        "code": "FUNCTION_HINT_MISSING"
    } ],
    "inheritParent": false,
    "parameters": { }
}
```

* `rule` allows you add a plugin for this folder that is not listed in the global configuration. See `ruleImpl` in `cflint.definition.json` for examples.

* `excludes` and `includes` allow you to specify an array of objects describing rules you want to be applied for this directory and its children. In the example above, the only rule to be checked for will be FUNCTION_HINT_MISSING.

* `inheritParent` configures if the rules set in the global or any parent configuration should be inherited as a base set of rules.

* `parameters` allows configuration of rules. See [RULES.md](/RULES.md) for the parameters of each rule and their defaults. You must precede the parameter name with the rule name separated by a dot.

* Please note: `inheritPlugins` and `output` were marked deprecated in CFLint 1.2.0 and removed in 1.4.0. Plugin inheritance is now always treated as true since the team cannot see a use case in which it should be disabled. The output type can be controlled elsewhere, such as command-line flags.

We provide a [schema with the deprecated properties excluded](/src/main/resources/schemas/.cflintrc.schema.json).

See [Recipes](#recipes) for some usage examples of `.cflintrc`. Example files can be found by browsing the [project test files](/src/test/resources/com/cflint/tests).

### Annotation-based configuration

Quite often there are scenarios in which you would generally want to run a certain set of rules against your code but in specific cases need to ignore an otherwise valid violation.

A common example are violations of CFQUERYPARAM_REQ that can't be fixed by applying `<cfqueryparam>` because your DB server doesn't allow params in certain positions (for instance in a `SELECT something FROM #application.config.linkedServerName#.DefaultDatabase.dbo.Comment` scenario). See [Issue #282](https://github.com/cflint/CFLint/issues/282) for more examples.

CFLint offers an annotation-based configuration to deal with this and similar scenarios. Annotations can be placed on the component- or function-level in a CFC or inline with code.

#### Tag-based CFML

    <!---
    @CFLintIgnore SOMETHINGELSE,MISSING_VAR,ANOTHERTHINGTOIGNORE
    --->

#### CFScript

Ignoring all rules on the current line:

    //cflint ignore:line

Ignoring a specific rule (or a comma-separated list of rules) on the current line:

    //cflint ignore:MISSING_VAR

Multiline ignore annotation:

    /*
        @CFLintIgnore SOMETHINGELSE,MISSING_VAR,ANOTHERTHINGTOIGNORE
    */

#### Ignoring within SQL

Within SQL, you can also use

    <!--- @CFLintIgnore CFQUERYPARAM_REQ --->

to ignore a rule violation on the next line.

### Precedence of configuration settings

Configuration of which plugins are run and which rules are included starts with the global configuration and flows through the command line parameters, folder level rules, and down to the annotations within the source.

* global configuration
* custom configuration file  (`-configfile`, we do **not** encourage this option to be used in day-to-day operations of CFLint)
* rule groups (`-rulegroups`,  default behavior is --rulegroups !Experimental)
* includes/excludes from the command line (`-includeRule` and `-excludeRule`)
* .cflintrc - folder level configuration, mostly for including/excluding specific messages
* annotations - explicitly exclude messages in the source code at the tag or line level.

The configuration rule that is closest to the rule is the one that takes effect.

* If an annotation excludes a message, it will not fire regardless of any configuration above it.
* If you exclude a rule at the command line level, but a `.cflintrc` adds it back in, it will fire for source files in that part of the source tree.
* If you are passing in multiple parameters at the command line level, in Windows Powershell the parameters must be included in "double quotes", e.g. `-includeRule "MISSING_VAR,CFQUERYPARAM_REQ"`

## Creating reports

CFLint supports a variety of reporting and output options that you can control via command-line flags. Beyond the targeted output formats of Text, XML, JSON or HTML you can also run CFLint with options for quiet, verbose and debug output.

If no targeted output format is specified at all, CFLint will default to creating an HTML report in the file `cflint-result.html`.

### Execution modes

You can force CFLint's output behavior to stdout and stderr by specifying options for quiet, verbose and debug. If you do not specify either, CFlint will return basic internal information and error output to stdout and stderr.

#### Quiet

Quiet mode (`-quiet <boolean>`) suppresses most of the output CFLint would otherwise create during linting. This might contain actual errors and exceptions but also information like the termination of recursive template parsing or certain configuration issues. Do not run quiet mode if you likely will need assistance with error messages or want to understand better what CFLint is doing.

This is the minimum output mode you can run CFLint in and the feature was originally inspired by [Issue #4](https://github.com/cflint/CFLint/issues/4).

There might be occasional messages from CFParser and ANTLR being pushed into stderr at this stage - even though CFlint runs in quiet mode. This is a known [issue](https://github.com/cflint/CFLint/issues/526) and will be addressed in the future.

#### Verbose

Verbose mode (`-verbose <boolean>`) enables verbose linting output. This contains information on selected output formats and configuration files being found and processes during linting as well as the currently processed file CFLint is working on (showing only files that are actually scanned).

If you want more information about the inner workings of CFLint during execution, verbose mode is the minimum you should run CFLint in.

#### Debug

Debug mode (`-debug <boolean>`) enables debug output. Debug mode implies verbose mode but adds additional information such as the parser tokens and every processed file (regardless of being supported by your or the default extension list) into the output streams.

#### Precedence

It is possible to switch on and run quiet, verbose and debug modes together at the same time. This is partly intended as you might not want to see error information being suppressed by quiet mode, but still want so see certain information being shown in verbose mode. Please take this behavior with a grain of salt though - there might be the odd scenario in which combining `-quiet`, `-verbose` and `-debug` causes unusual output.

The exception is debug mode. In debug mode, CFLint will always ignore user settings for verbose and quiet and set `verbose` to `true` and `quiet` to `false`.

### HTML

The flag `-html` instructs CFLint to create an HTML document. The full syntax is:

    -html -html <outputFileName>

### XML

The flag `-xml` instructs CFLint to create XML. There are two options for XML reporting.

The first option is what we call CFLint XML. It's an internal format that adheres to a basic schema provided [here](/src/main/resources/schemas/cflint-result.xsd). You could then use this format as-is or to do further processing of your choice.

The second option is FindBugs XML. The resulting XML document adheres to the current version of the FindBugs BugCollection [XML Schema Definition](src/main/resources/findbugs/bugcollection.xsd) and can be used in most CI-/Build-Server products. JetBrains TeamCity 10+ can import this format out of the box.

*Please note*: Currently it's not possible to produce BOTH flavors of XML reports at the same time. This is a known limitation. This limitation will be removed as part of CFLint 2.0 (see [Issue #331](https://github.com/cflint/CFLint/issues/331)).

#### CFLint XML

To create CFLint XML provide the following command-line arguments:

    -xml -xmlstyle cflint -xmlfile <outputFileName>

Example of CFLint XML:

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<issues version="1.2.1" timestamp="1500107134">
    <issue severity="WARNING" id="CFQUERYPARAM_REQ" message="CFQUERYPARAM_REQ" category="CFLint" abbrev="CR">
        <location file="/Users/kai/Documents/Code/paypal.cfc" fileName="paypal.cfc" function="doSomething" column="0" line="325" message="<cfquery> should use <cfqueryparam/> for variable 'arguments.PaymentType'." variable="arguments.PaymentType">
            <Expression><![CDATA[<cfquery name="doPayment" datasource="#paymentDatasource#">...some more Details...]]></Expression>
        </location>
    </issue>
    <issue severity="WARNING" id="CFQUERYPARAM_REQ" message="CFQUERYPARAM_REQ" category="CFLint" abbrev="CR">
        <location file="/Users/kai/Documents/Code/paypal.cfc" fileName="paypal.cfc" function="doSomethingElse" column="0" line="432" message="<cfquery> should use <cfqueryparam/> for variable 'arguments.something'." variable="arguments.something">
            <Expression><![CDATA[<cfquery name="doPayment" datasource="#paymentDatasource#">...some more Details...]]></Expression>
        </location>
    </issue>
...
    <counts totalfiles="108" totallines="55596">
        <count code="CFQUERYPARAM_REQ" count="39"></count>
        <count severity="WARNING" count="39"></count>
    </counts>
</issues>
```

#### FindBugs XML

To create FindBugs XML provide the following command-line arguments:

    -xml -xmlstyle findbugs -xmlfile <outputFileName>

The FindBugs XML format is currently created using an XSLT document, transforming the CFLint report to FindBugs XML ([`/src/main/resources/findbugs/cflint-to-findbugs.xsl`](/src/main/resources/findbugs/cflint-to-findbugs.xsl)).

### JSON

JSON output can be created with

    -json -jsonfile <outputFileName>

Example of CFLint JSON:

```json
{
    "version" : "1.2.1",
    "timestamp" : 1501202128,
    "issues" : [ {
        "severity" : "ERROR",
        "id" : "MISSING_VAR",
        "message" : "MISSING_VAR",
        "category" : "CFLINT",
        "abbrev" : "MV",
        "locations" : [ {
            "file" : "src/test/resources/com/cflint/tests/Ignores/ignoreCFMLAny2.cfc",
            "fileName" : "ignoreCFMLAny2.cfc",
            "function" : "testFunction",
            "column" : 6,
            "line" : 14,
            "message" : "Variable someVar is not declared with a var statement.",
            "variable" : "someVar",
            "expression" : "someVar"
        } ]
    } ],
    "counts" : {
        "totalFiles" : 7,
        "totalLines" : 49,
        "countByCode" : [ {
            "code" : "MISSING_VAR",
            "count" : 1
        } ],
        "countBySeverity" : [ {
            "severity" : "ERROR",
            "count" : 1
        } ]
    }
}
```

The JSON schema is available [here](/src/main/resources/schemas/cflint-result.schema.json).

### Text

Plain text output can be created with

    -text -textfile <outputFileName>

Example of plain text output:

    Issue
    Severity:WARNING
    Message code:CFQUERYPARAM_REQ
        File:/Users/kai/Documents/Code/paypal.cfc
        Column:0
        Line:79
            Message:<cfquery> should use <cfqueryparam/> for variable 'arguments.something'.
            Variable:'arguments.something' in function:
            Expression:<cfquery name=\"qry\" datasource=\"#variables.dsn#\" cachedwithin=\"#createTimeSpan(0,0,arguments.cacheInMins,0)#\">\r\n...some Details...

    Severity:WARNING
    Message code:CFQUERYPARAM_REQ
        File:/Users/kai/Documents/Code/paypal.cfc
        Column:0
        Line:145
            Message:<cfquery> should use <cfqueryparam/> for variable 'arguments.something'.
            Variable:'arguments.something' in function:
            Expression:<cfquery name=\"qry\" datasource=\"#variables.dsn#\" cachedwithin=\"#createTimeSpan(0,0,arguments.cacheInMins,0)#\">\r\n...some Details...

    ...

    Total files:108
    Total lines:55690

    Issue counts:1
    CFQUERYPARAM_REQ:4

    Total issues:4
    Total warnings:4

## API

To interact directly with CFLint within the JVM use the CFLint API.

```java
import com.cflint.api.CFLintAPI;
import com.cflint.api.CFLintResult;

CFLintAPI api = new CFLintAPI();
CFLintResult result = api.scan(filename);
String jsonResult = result.getJSON();
```

## Integration server support

For **Jenkins**, please look at the Jenkins/Hudson plugin mentioned further below.

JetBrains' **TeamCity** has support for FindBugs XML code inspection reports. They can be produced out of the box with CFLint from 1.2.0 onwards (see above in the [FindBugs XML section](#findbugs-xml)).

There is support for **SonarQube** through StepStone's Sonar ColdFusion plugin mentioned further below.

For **Azure DevOps/TFS**, please look at the Azure Pipeline/TFS Build extension mentioned further below.

There's an NPM wrapper for CFLint below. Please be aware that the wrapper seems to come with its own bundled CFLint binary which might not be up-to-date, which is outside of our control.

Other products in the integration/build server category might work, too. If you're using a specific product that works for you with CFLint, please let us know. If you can't get CFLint to work in an environment you use, please let us know as well - we might be able to help.

## IDE support

There are several IDE integrations for CFLint that are available. Below are some brief descriptions, but if you'd like to know more, see [Interesting third-party projects](#interesting-third-party-projects).

There is IDE support for **Sublime Text 3** through a third-party project utilizing SublimeLinter.

There is also support for **Adobe ColdFusion Builder** through a third-party project. Users of CFBuilder, please also see the discussion in [Issue #327](https://github.com/cflint/CFLint/issues/327).

Users of **Atom** can integrate via AtomLinter through a third-party project.

An extension for **Visual Studio Code** is also available as a third-party project.

Support for JetBrains' **IntelliJ** is available as third-party plugin.

## Extending CFLint

### Adding custom rules

```java
package com.cflint.plugins.core;

import net.htmlparser.jericho.Element;
import cfml.parsing.cfscript.script.CFFuncDeclStatement;
import cfml.parsing.cfscript.script.CFFunctionParameter;
import cfml.parsing.cfscript.script.CFScriptStatement;

import com.cflint.BugList;
import com.cflint.plugins.CFLintScannerAdapter;
import com.cflint.plugins.Context;
import com.cflint.tools.CFTool;

public class ArgDefChecker extends CFLintScannerAdapter {

    @Override
    public void expression(final CFScriptStatement expression, final Context context, final BugList bugs) {
        if (expression instanceof CFFuncDeclStatement) {
            final CFFuncDeclStatement function = (CFFuncDeclStatement) expression;
            for (final CFFunctionParameter argument : function.getFormals()) {
                // handler.addArgument(param.getName());
                final String name = argument.getName();
                if (!argument.toString().contains("required") && !argument.toString().contains("=")) {
                    function.getLine();
                    function.getColumn();
                    context.addMessage("ARG_DEFAULT_MISSING", name);
                }
            }
        }
    }

    @Override
    public void element(final Element element, final Context context, final BugList bugs) {
        if (element.getName().equals("cfargument")) {
            final String name = element.getAttributeValue("name");
            final boolean required = CFTool.toBoolean(element.getAttributeValue("required"));
            final String defaultExpr = element.getAttributeValue("default");
            if (!required && defaultExpr == null) {
                element.getSource().getRow(element.getBegin());
                element.getSource().getColumn(element.getBegin());
                context.addMessage("ARG_DEFAULT_MISSING", name);
            }
        }
    }
}
```

Looking at the function `element`, the arguments are:

* `element` - the current CFML tag
* `context` - the current file being checked
* `bugs` - the appending object of violations

# Recipes

## Ignoring a directory for processing

The easiest way to achieve this is with a custom `.cflintrc` file:

The `includes` field is ignored if it is an empty list, so simply add a single item to it for which nothing matches.

```json
{
    "code" : "NOTHING"
}
```

or more simply:

```json
    {}
```

The following will ignore all rules in the current folder and below.

```json
{
    "rule" : [ ],
    "excludes" : [ ],
    "includes" : [ {} ],
    "inheritParent" : false,
    "parameters" : {}
}
```

This can be simplified using the default values of a `.cflintrc` file:

```json
{
    "includes" : [{}],
    "inheritParent" : false
}
```

See the discussion in [Issue #290](https://github.com/cflint/CFLint/issues/290) for more info.

## Configuring a parameter

Parameters within the rules can be overridden in the `.cflintrc` files. Use the rule name and the parameter joined with a dot.

```json
{
    "parameters" : {
        "VariableNameChecker.maxLength": "15"
    }
}
```

## Filtering out specific processing results in specific folders

Supply a `cflintexclude.json` file in the command line with the -filterFile argument.

### Examples

To filter out the GLOBAL_VAR messages in the "some\package\location\" folder, add the following to `cflintexclude.json`

#### Windows

    [
        other exclude rules...,
        {"file":".*some\\\\package\\\\location\\\\.*","code":"GLOBAL_VAR"}
    ]

Note: The back slashes must be escaped twice, once for JSON, once for regular expressions

#### \*nix

    [
        other exclude rules...,
        {"file":".*some/package/location/.*","code":"GLOBAL_VAR"}
    ]

# Support

Raise issues here on GitHub and we will look at them.

The [CFML Slack team](http://cfml-slack.herokuapp.com/) has a `#cflint` channel you can join and talk to most of the regular contributors and other users.

# How to contribute

See [CONTRIBUTING.md](/CONTRIBUTING.md) for further information.

# Interesting third-party projects

Please note that the majority of the libraries and projects mentioned here are not directly related to and maintained by the CFLint team. Please see the authors and maintainers of the respective project for support using their libraries first.

* [Jenkins/Hudson plugin](https://github.com/jenkinsci/CFLint-plugin)
* [Sublime Text package](https://github.com/ckaznocha/SublimeLinter-contrib-CFLint)
* [ColdFusion Builder extension](https://github.com/cfjedimaster/CFLint-Extension)
* [Atom package](https://github.com/ditinc/linter-cflint)
* [Visual Studio Code extension](https://github.com/KamasamaK/vscode-cflint)
* [IntelliJ plugin](https://bitbucket.org/SyncHot/cflint/)
* [Azure Pipeline/TFS Build extension](https://marketplace.visualstudio.com/items?itemName=JoshKnutsonExtensions.devops-extension-cflint)
* [SonarQube plugin](https://github.com/stepstone-tech/sonar-coldfusion)
* [NPM wrapper](https://github.com/morgdenn/npm-cflint)
* Vim [Syntastic support for CFLint](https://github.com/cflint/cflint-syntastic)
* [IntelliJ IDEA Ultimate plugin](https://github.com/Pr1st0n/cflint-intellij)

If you have been working on (or are thinking about starting) a project related to CFLint, please let us know. We're happy to include relevant third-party projects to the list above.


Byte Buddy
==========

runtime code generation for the Java virtual machine

[![Actions Status](https://github.com/raphw/byte-buddy/workflows/CI/badge.svg)](https://github.com/raphw/byte-buddy/actions)
[![Security Score](https://snyk-widget.herokuapp.com/badge/mvn/net.bytebuddy/byte-buddy/badge.svg)](https://snyk.io/test/github/raphw/byte-buddy)
[![Coverage Status](https://img.shields.io/coveralls/raphw/byte-buddy/master.svg)](https://coveralls.io/r/raphw/byte-buddy?branch=master)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.bytebuddy/byte-buddy-parent/badge.svg#)](https://maven-badges.herokuapp.com/maven-central/net.bytebuddy/byte-buddy-parent)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/6251/badge)](https://bestpractices.coreinfrastructure.org/projects/6251)

Byte Buddy is a code generation and manipulation library for creating and modifying Java classes during the runtime of a
Java application and without the help of a compiler. Other than the code generation utilities
that [ship with the Java Class Library](https://docs.oracle.com/javase/8/docs/api/java/lang/reflect/Proxy.html), Byte
Buddy allows the creation of arbitrary classes and is not limited to implementing interfaces for the creation of runtime
proxies. Furthermore, Byte Buddy offers a convenient API for changing classes either manually, using a Java agent or
during a build.

In order to use Byte Buddy, one does not require an understanding of Java byte code or
the [class file format](https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html). In contrast, Byte Buddy’s API
aims for code that is concise and easy to understand for everybody. Nevertheless, Byte Buddy remains fully customizable
down to the possibility of defining custom byte code. Furthermore, the API was designed to be as non-intrusive as
possible and as a result, Byte Buddy does not leave any trace in the classes that were created by it. For this reason,
the generated classes can exist without requiring Byte Buddy on the class path. Because of this feature, Byte Buddy’s
mascot was chosen to be a ghost.

Byte Buddy is written in Java 5 but supports the generation of classes for any Java version. Byte Buddy is a
light-weight library and only depends on the visitor API of the Java byte code parser library
[ASM](https://asm.ow2.io/) which does itself
[not require any further dependencies](https://repo1.maven.org/maven2/org/ow2/asm/asm/5.0.4/asm-5.0.4.pom).

At first sight, runtime code generation can appear to be some sort of black magic that should be avoided and only few
developers write applications that explicitly generate code during their runtime. However, this picture changes when
creating libraries that need to interact with arbitrary code and types that are unknown at compile time. In this
context, a library implementer must often choose between either requiring a user to implement library-proprietary
interfaces or to generate code at runtime when the user’s types becomes first known to the library. Many known libraries
such as for example *Spring* or *Hibernate* choose the latter approach which is popular among their users under the term
of using [*Plain Old Java Objects*](https://en.wikipedia.org/wiki/Plain_Old_Java_Object). As a result, code generation
has become an ubiquitous concept in the Java space. Byte Buddy is an attempt to innovate the runtime creation of Java
types in order to provide a better tool set to those relying on code generation.

___

In October 2015, Byte Buddy was distinguished with a
[*Duke's Choice award*](https://www.oracle.com/corporate/pressrelease/dukes-award-102815.html)
by Oracle. The award appreciates Byte Buddy for its "*tremendous amount of innovation in Java Technology*". We feel very
honored for having received this award and want to thank all users and everybody else who helped making Byte Buddy the
success it has become. We really appreciate it!

___

Byte Buddy offers excellent performance at production quality. It is stable and in use by distinguished frameworks and
tools such as [Mockito](https://site.mockito.org/), [Hibernate](https://hibernate.org/)
, [Jackson](https://github.com/FasterXML/jackson), [Google's Bazel build system](https://bazel.build/)
and [many others](https://github.com/raphw/byte-buddy/wiki/Projects-using-Byte-Buddy). Byte Buddy is also used by a
large number of commercial products to great result. It is currently downloaded over 75 million times a year.

Hello World
-----------

Saying *Hello World* with Byte Buddy is as easy as it can get. Any creation of a Java class starts with an instance of
the `ByteBuddy` class which represents a configuration for creating new types:

```java
Class<?> dynamicType = new ByteBuddy()
  .subclass(Object.class)
  .method(ElementMatchers.named("toString"))
  .intercept(FixedValue.value("Hello World!"))
  .make()
  .load(getClass().getClassLoader())
  .getLoaded();
assertThat(dynamicType.newInstance().toString(), is("Hello World!"));
```

The default `ByteBuddy` configuration which is used in the above example creates a Java class in the newest version of
the class file format that is understood by the processing Java virtual machine. As hopefully obvious from the example
code, the created type will extend the `Object` class and overrides its `toString` method which should return a fixed
value of `Hello World!`. The method to be overridden is identified by a so-called `ElementMatcher`. In the above
example, a predefined element matcher `named(String)` is used which identifies methods by their exact names. Byte Buddy
comes with numerous predefined and well-tested matchers which are collected in the `ElementMatchers`
class and which can be easily composed. The creation of custom matchers is however as simple as implementing the
([functional](https://docs.oracle.com/javase/8/docs/api/java/lang/FunctionalInterface.html)) `ElementMatcher` interface.

For implementing the `toString` method, the `FixedValue` class defines a constant return value for the overridden
method. Defining a constant value is only one example of many method interceptors that ship with Byte Buddy. By
implementing the `Implementation` interface, a method could however even be defined by custom byte code.

Finally, the described Java class is created and then loaded into the Java virtual machine. For this purpose, a target
class loader is required. Eventually, we can convince ourselves of the result by calling the `toString` method on an
instance of the created class and finding the return value to represent the constant value we expected.

A more complex example
----------------------

Of course, a *Hello World example* is a too simple use case for evaluating the quality of a code generation library. In
reality, a user of such a library wants to perform more complex manipulations, for example by introducing hooks into the
execution path of a Java program. Using Byte Buddy, doing so is however equally simple. The following example gives a
taste of how method calls can be intercepted.

Byte Buddy expresses dynamically defined method implementations by instances of the `Implementation` interface. In the
previous example, `FixedValue` that implements this interface was already demonstrated. By implementing this interface,
a user of Byte Buddy can go to the length of defining custom byte code for a method. Normally, it is however easier to
use Byte Buddy's predefined implementations such as `MethodDelegation` which allows for implementing any method in plain
Java. Using this implementation is straight forward as it operates by delegating the control flow to any POJO. As an
example of such a POJO, Byte Buddy can for example redirect a call to the only method of the following class:

```java
public class GreetingInterceptor {
  public Object greet(Object argument) {
    return "Hello from " + argument;
  }
}
```

Note that the above `GreetingInterceptor` does not depend on any Byte Buddy type. This is good news because none of the
classes that Byte Buddy generates require Byte Buddy on the class path! Given the above `GreetingInterceptor`, we can
use Byte Buddy to implement the Java 8 `java.util.function.Function` interface and its abstract `apply` method:

```java
Class<? extends java.util.function.Function> dynamicType = new ByteBuddy()
  .subclass(java.util.function.Function.class)
  .method(ElementMatchers.named("apply"))
  .intercept(MethodDelegation.to(new GreetingInterceptor()))
  .make()
  .load(getClass().getClassLoader())
  .getLoaded();
assertThat((String) dynamicType.newInstance().apply("Byte Buddy"), is("Hello from Byte Buddy"));
```

Executing the above code, Byte Buddy implements Java's `Function` interface and implements the `apply` method as a
delegation to an instance of the `GreetingInterceptor` POJO that we defined before. Now, every time that the
`Function::apply` method is called, the control flow is dispatched to `GreetingInterceptor::greet` and the latter
method's return value is returned from the interface's method.

Interceptors can be defined to take with more generic inputs and outputs by annotating the interceptor's parameters.
When Byte Buddy discovers an annotation, the library injects the dependency that the interceptor parameter requires. An
example for a more general interceptor is the following class:

```java
public class GeneralInterceptor {
  @RuntimeType
  public Object intercept(@AllArguments Object[] allArguments,
                          @Origin Method method) {
    // intercept any method of any signature
  }
}
```

With the above interceptor, any intercepted method could be matched and processed. For example, when matching
`Function::apply`, the method's arguments would be passed as the single element of an array. Also, a `Method`
reference to `Fuction::apply` would be passed as the interceptor's second argument due to the `@Origin`
annotation. By declaring the `@RuntimeType` annotation on the method, Byte Buddy finally casts the returned value to the
return value of the intercepted method if this is necessary. In doing so, Byte Buddy also applies automatic boxing and
unboxing.

Besides the annotations that were already mentioned there exist plenty of other predefined annotations. For example,
when using the `@SuperCall` annotation on a `Runnable` or `Callable` type, Byte Buddy injects proxy instances that allow
for an invocation of a non-abstract super method if such a method exists. And even if Byte Buddy does not cover a use
case, Byte Buddy offers an extension mechanism for defining custom annotations.

You might expect that using these annotations ties your code to Byte Buddy. However, Java ignores annotations in case
that they are not visible to a class loader. This way, generated code can still exist without Byte Buddy! You can find
more information on the `MethodDelegation` and on all of its predefined annotations in its *javadoc* and in Byte Buddy's
tutorial.

Changing existing classes
----------------------

Byte Buddy is not limited to creating subclasses but is also capable of redefining existing code. To do so, Byte Buddy
offers a convenient API for defining
so-called [Java agents](https://docs.oracle.com/javase/8/docs/api/java/lang/instrument/package-summary.html). Java
agents are plain old Java programs that can be used to alter the code of an existing Java application during its
runtime. As an example, we can use Byte Buddy to change methods to print their execution time. For this, we first define
an interceptor similar to the interceptors in the previous examples:

```java
public class TimingInterceptor {
  @RuntimeType
  public static Object intercept(@Origin Method method,
                                 @SuperCall Callable<?> callable) {
    long start = System.currentTimeMillis();
    try {
      return callable.call();
    } finally {
      System.out.println(method + " took " + (System.currentTimeMillis() - start));
    }
  }
}
```

Using a Java agent, we can now apply this interceptor to all types that match an `ElementMatcher` for
a `TypeDescription`. For the example, we choose to add the above interceptor to all types with a name that ends
in `Timed`. This is done for the sake of simplicity whereas an annotation would probably be a more appropriate
alternative to mark such classes for a production agent. Using Byte Buddy's `AgentBuilder` API, creating a Java agent is
as easy as defining the following agent class:

```java
public class TimerAgent {
  public static void premain(String arguments,
                             Instrumentation instrumentation) {
    new AgentBuilder.Default()
      .type(ElementMatchers.nameEndsWith("Timed"))
      .transform((builder, type, classLoader, module, protectionDomain) ->
          builder.method(ElementMatchers.any())
                 .intercept(MethodDelegation.to(TimingInterceptor.class))
      ).installOn(instrumentation);
  }
}
```

Similar to Java's `main` method, the `premain` method is the entry point to any Java agent from which we apply the
redefinition. As one argument, a Java agent receives an instance of the `Instrumentation` interface which allows Byte
Buddy to hook into the JVM's standard API for runtime class redefinition.

This program is packaged together with a manifest file with
the [`Premain-Class` attribute](https://docs.oracle.com/javase/8/docs/api/java/lang/instrument/package-summary.html)
pointing to the `TimerAgent`. The resulting *jar* file can now be added to any Java application by
setting `-javaagent:timingagent.jar` similar to adding a jar to the class path. With the agent active, all classes
ending in `Timed` do now print their execution time to the console.

Byte Buddy is also capable of applying so-called runtime attachments by disabling class file format changes and using
the `Advice` instrumentation. Please refer to the *javadoc* of the `Advice` and the `AgentBuilder` class for further
information. Byte Buddy also offers the explicit change of Java classes via a `ByteBuddy` instance or by using the Byte
Buddy *Maven* and *Gradle* plugins.

Where to go from here?
----------------------

Byte Buddy is a comprehensive library and we only scratched the surface of Byte Buddy's capabilities. However, Byte
Buddy aims for being easy to use by providing a domain-specific language for creating classes. Most runtime code
generation can be done by writing readable code and without any knowledge of Java's class file format. If you want to
learn more about Byte Buddy, you can find such a [tutorial on Byte Buddy's web page](https://bytebuddy.net/#/tutorial) (
There is also [a Chinese translation available](https://notes.diguage.com/byte-buddy-tutorial/)).

Furthermore, Byte Buddy comes with a [detailed in-code documentation](https://bytebuddy.net/#/javadoc) and extensive
test case coverage which can also serve as example code. Finally, you can find an up-to-date list of articles and
presentations on Byte Buddy [in the wiki](https://github.com/raphw/byte-buddy/wiki/Web-Resources). When using Byte
Buddy, make also sure to read the following information on maintaining a project dependency.

Getting support
----------------------------

#### Commercial ####

The use of Byte Buddy is free and does not require the purchase of a license. To get the most out of the library or to
secure an easy start, it is however possible to purchase training, development hours or support plans. Rates are
dependent on the scope and duration of an engagement. Please get in touch with <rafael.wth@gmail.com> for further
information.

#### Tidelift ####

Byte Buddy
is [listed on Tidelift](https://tidelift.com/subscription/pkg/maven-net-bytebuddy-byte-buddy?utm_source=byte-buddy&utm_medium=referral)
. If you are not using Byte Buddy to an extent where you want to purchase explicit support and want to support the open
source community in general, please consider a subscription.

#### GitHub sponsors ####

You can support my work via [GitHub sponsors](https://github.com/sponsors/raphw). Note that this option is only meant
for commercial actors who are looking for a simple payment channel and that do not expect support in return. Support via
GitHub Sponsors is not possible to maintain VAT compliance. Please reach out for a direct support agreement instead.

#### Free ####

General questions can be asked on [Stack Overflow](https://stackoverflow.com/questions/tagged/byte-buddy) or on
the [Byte Buddy mailing list](https://groups.google.com/forum/#!forum/byte-buddy) which also serve as an archive for
questions. Of course, bug reports will be considered also outside of a commercial plan. For open source projects, it is
sometimes possible to receive extended help for taking Byte Buddy into use.

Dependency and API evolution
----------------------------

Byte Buddy is written on top of [ASM](https://asm.ow2.io), a mature and well-tested library for reading and writing
compiled Java classes. In order to allow for advanced type manipulations, Byte Buddy is intentionally exposing the ASM
API to its users. Of course, the direct use of ASM remains fully optional and most users will most likely never require
it. This choice was made such that a user of Byte Buddy is not restrained to its higher-level functionality but can
implement custom implementations without a fuss when it is necessary.

ASM has previously changed its public API but added a mechanism for API compatibility starting with version 4 of the
library. In order to avoid version conflicts with such older versions, Byte Buddy repackages the ASM dependency into its
own namespace. If you want to use ASM directly, the `byte-buddy-dep` artifact offers a version of Byte Buddy with an
explicit dependency to ASM. When doing so, you **must** repackage *both* Byte Buddy and ASM into your namespace to avoid
version conflicts.

Please note the [security policy](https://github.com/raphw/byte-buddy/blob/master/SECURITY.md) of this project.

License and development
-----------------------

Byte Buddy is licensed under the liberal and business-friendly
[*Apache Licence, Version 2.0*](https://www.apache.org/licenses/LICENSE-2.0.html) and is freely available on GitHub.
Additionally, the *byte-buddy* distribution bundles ASM which is released
under [a 3-clause BSD license](https://asm.ow2.io/license.html).

Byte Buddy binaries are published to the repositories of Maven Central and on JCenter. The artifacts signatures can be
validated against [this PGP public key](https://keys.openpgp.org/search?q=rafael.wth@gmail.com) beginning with Byte
Buddy 1.10.3. Older versions can be validated
against [this older and weaker certificate](https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xf42b96b8648b5c4a1c43a62fbb2914c1fa0811c3)
.

The project is built using Maven. From your shell, cloning and building the
project would go something like this:

```shell
git clone https://github.com/raphw/byte-buddy.git
cd byte-buddy
mvn package
```

On these commands, Byte Buddy is cloned from GitHub and built on your machine. Further build options are listed in the
root POM file. Byte Buddy can be built with any JDK of at least version 6. It is however recommended to use a JDK of
at least version 8 as the builds for version 6 and 7 require the usage of unencrypted HTTP. Its support is only meant
for running tests against this JDK version and can expose you to man-in-the-middle attacks. Therefore, these builds
should be avoided. Byte Buddy is currently tested for versions 6 and upwards of the JDK on CI servers.

Please use GitHub's [issue tracker](https://github.com/raphw/byte-buddy/issues) for reporting bugs. When committing
code, please provide test cases that prove the functionality of your features or that demonstrate a bug fix.
Furthermore, make sure you are not breaking any existing test cases. If possible, please take the time to write some
documentation. For feature requests or general feedback, you can also use the
[issue tracker](https://github.com/raphw/byte-buddy/issues) or contact us on
[our mailing list](https://groups.google.com/forum/#!forum/byte-buddy).

Supporters
----------

The work on Byte Buddy is also possible thanks to a row of supporters that have dedicated regular resources and
attention to the project. Please take your time to have a look at those supporters and their offerings.