### Install pre-commit

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/install-pre-commit-hooks.md

Install the pre-commit tool using pip. This is a prerequisite for using pre-commit hooks.

```bash
pip install pre-commit
```

--------------------------------

### Java File Copyright Example (Multiple Contributors)

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2025-01-apply-spdx-license-info-and-comply-with-reuse-specification.adoc

Example header for a Java file with contributions from multiple authors, showing individual copyright lines.

```java
// SPDX-FileCopyrightText: Copyright 2023 Mark Rotteveel
// SPDX-FileCopyrightText: Copyright 2023-2025 Jane Doe
// SPDX-License-Identifier: LGPL-2.1-or-later
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/install-pre-commit-hooks.md

Install the pre-commit hooks for the Jaybird repository from the root directory. This command enables the hooks to run automatically before each commit.

```bash
pre-commit install
```

--------------------------------

### Java File Copyright Example (Company Attribution)

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2025-01-apply-spdx-license-info-and-comply-with-reuse-specification.adoc

Example showing how to attribute copyright to a company while listing the individual contributor, for cases like Boix i Oltra, S.L.

```java
// SPDX-FileCopyrightText: Copyright 2023-2025 Mark Rotteveel
// SPDX-FileCopyrightText: Copyright 2001-2002 Boix i Oltra, S.L.
// SPFX-FileContributor: 2001-2002 Alejandro Alberola (Boix i Oltra, S.L.)
// SPDX-License-Identifier: LGPL-2.1-or-later
```

--------------------------------

### Start Operation Monitoring

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2019-06-ability-to-monitor-driver-operations.md

Call this static method before starting a database operation to inform the monitor. If the OperationMonitor is not initialized, the driver operates normally.

```java
OperationMonitor.startOperation(op);
```

--------------------------------

### Example MANIFEST.MF Fragment for Licensing

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2025-01-apply-spdx-license-info-and-comply-with-reuse-specification.adoc

This fragment shows the required OSGi headers for specifying license information, including Bundle-License, SPDX-License-Identifier, and SPDX-FileCopyrightText. Ensure these are correctly populated.

```manifest
Bundle-License: LGPL-2.1-or-later OR LGPL-2.1-or-later AND BSD-3-Clause
SPDX-License-Identifier: LGPL-2.1-or-later OR LGPL-2.1-or-later AND BSD-3-Clause
SPDX-FileCopyrightText: Copyright 2001-2025 Firebird development team and individual contributors
```

--------------------------------

### Wildfly Module Configuration

Source: https://github.com/firebirdsql/jaybird/blob/master/src/docs/asciidoc/faq.adoc

Example `module.xml` configurations for using Jaybird with Wildfly.

```APIDOC
## Wildfly Module Configuration

### Description
Minimal `module.xml` configurations for integrating Jaybird with Wildfly.

### Example 1: Basic Configuration (Jaybird 3.0.x)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.firebirdsql">
  <resources>
    <resource-root path="jaybird-3.0.x.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="javax.resource.api"/>
  </dependencies>
</module>
```

### Example 2: Configuration for Java 7 with Jaybird 3.0.4+ (Requires `javax.xml.bind.api`)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.firebirdsql">
  <resources>
    <resource-root path="jaybird-3.0.x.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="javax.resource.api"/>
    <module name="javax.xml.bind.api"/> <!-- Add this -->
  </dependencies>
</module>
```

**Note**: Alternatively, use Jaybird for Java 8 or higher to avoid the `javax.xml.bind.api` dependency.
```

--------------------------------

### Java File Copyright Example (Multiple Years)

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2025-01-apply-spdx-license-info-and-comply-with-reuse-specification.adoc

Example of a copyright and license header for a Java file authored by Jane Doe across multiple years.

```java
// SPDX-FileCopyrightText: Copyright 2023-2025 Jane Doe
// SPDX-License-Identifier: LGPL-2.1-or-later
```

--------------------------------

### Java File Copyright Example (Single Year)

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2025-01-apply-spdx-license-info-and-comply-with-reuse-specification.adoc

Example of a copyright and license header for a Java file authored by Mark Rotteveel in 2023.

```java
// SPDX-FileCopyrightText: Copyright 2023 Mark Rotteveel
// SPDX-License-Identifier: LGPL-2.1-or-later
```

--------------------------------

### New Jaybird Artifact Naming Scheme Examples

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2019-02-version-number-and-naming-scheme.md

Examples illustrating the new naming scheme for Jaybird artifacts, including download artifacts, jar files, and Maven coordinates, incorporating the target Java version.

```text
jaybird-jdk18-4.0.0.zip
jaybird-java11-4.0.0.zip
```

```text
jaybird-jdk18-4.0.0.jar
jaybird-java11-4.0.0.jar
jaybird-full-jdk18-4.0.0.jar
jaybird-jdk18-4.0.0-sources.jar
```

```text
org.firebirdsql.jdbc:jaybird-jdk18:4.0.0
org.firebirdsql.jdbc:jaybird-java11:4.0.0 (tentative)
org.firebirdsql.jdbc:jaybird-full-jdk18:4.0.0 (example only)
```

--------------------------------

### Example Directory Structure for Firebird Embedded

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2020-05-firebird-embedded-locator-service-provider.md

Illustrates the expected file and directory layout for packaging Firebird Embedded libraries when using ClasspathFirebirdEmbeddedLibrary. Ensure all files are placed within the package directory structure.

```text
/--META-INF
|  |--services
|  |   \--org.firebirdsql.jna.embedded.spi.FirebirdEmbeddedProvider
|  \--MANIFEST.MF
|--org
   \--example
      \--firebird_3_0_5
         \--win32_x86_64
            |--fbintl
            |  |--fbintl.conf
            |  \--fbintl.dll
            |--plugins
            |  |--engine12.dll
            |  |--udr_engine.conf
            |  \--udr_engine.dll
            |--fbclient.dll
            |--firebird.conf
            |--firebird.msg
            |--FirebirdEmbeddedProvider.class             
            |--FirebirdEmbeddedProvider$ResourceInfo.class
            |--ib_util.dll
            |--icudt52.dll
            |--icudt52l.dat
            |--icuin52.dll
            |--icuuc52.dll
            \--plugins.conf
```

--------------------------------

### Run Gradle Build with Specific Java Version (Windows Batch)

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/build-documentation.md

This batch script demonstrates how to run the Gradle wrapper with a specific Java version profile. Ensure you have Gradle wrapper installed.

```batch
@echo off
call gradlew.bat -PbuildProfile=21 %*
```

--------------------------------

### Jaybird Pre-release Version Suffixes

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2019-02-version-number-and-naming-scheme.md

Examples of version suffixes used for pre-releases in Jaybird, such as development snapshots, alpha, beta, and release candidates.

```text
4.0.0-SNAPSHOT
```

```text
4.0.0-alpha-1
```

```text
4.0.0-beta-1
```

```text
4.0.0-rc-1
```

--------------------------------

### Create User for Legacy Authentication via SQL

Source: https://github.com/firebirdsql/jaybird/wiki/Jaybird-and-Firebird-3

Use the 'CREATE USER' SQL statement with 'USING PLUGIN Legacy_UserManager' to create a user specifically for legacy authentication. This example creates a user 'jaybird' with password 'jdbc'.

```sql
CREATE USER jaybird PASSWORD 'jdbc' USING PLUGIN Legacy_UserManager
```

--------------------------------

### Build Documentation with Gradle

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/build-documentation.md

Use the 'asciidoctor' task to build project documentation, including FAQ and release notes. This requires Asciidoctor to be configured.

```bash
./gradlew asciidoctor
```

--------------------------------

### Historical Jaybird Artifact Naming Examples

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2019-02-version-number-and-naming-scheme.md

Examples of how Jaybird artifacts were named historically, including download artifacts, jar files, and Maven coordinates.

```text
FirebirdSQL-1.5.6JDK_1.3.zip
JayBird-2.0.1JDK_1.3.zip
Jaybird-3.0.4-JDK_1.7.zip
```

```text
firebirdsql.jar
jaybird-2.1.6.jar
jaybird-3.0.4.jar
jaybird-full-3.0.4.jar
jaybird-3.0.4-sources.jar
```

```text
org.firebirdsql.jdbc:jaybird-jdk18:3.0.4
```

--------------------------------

### List All Gradle Tasks

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/build-documentation.md

Run this command to display a list of all available Gradle tasks for the project. This is useful for discovering build functionalities.

```bash
./gradlew tasks
```

--------------------------------

### Sign and Deploy Jar Files (Java 11 Snapshot)

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/maven-release/instructions.txt

Command for signing and deploying Jaybird artifacts for Java 11 to the snapshot repository. Verify paths, URLs, and repository IDs.

```bash
mvn gpg:sign-and-deploy-file -DpomFile=jaybird-5.0.0.java11-SNAPSHOT.pom -Dfile=jaybird-5.0.0.java11-SNAPSHOT.jar -Dsources=jaybird-5.0.0.java11-SNAPSHOT-sources.jar -Djavadoc=jaybird-5.0.0.java11-SNAPSHOT-javadoc.jar -Durl=https://oss.sonatype.org/content/repositories/snapshots -DrepositoryId=sonatype-nexus-snapshots
```

--------------------------------

### Publish to Maven

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/publish.md

Use this Gradle command to clean, assemble, and publish artifacts to Maven. It may prompt for your GPG key password.

```bash
./gradlew clean assemble publish -PcentralPassword=<value>
```

--------------------------------

### Clean Build Output with Gradle

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/build-documentation.md

Execute this command to clean the current build output. It's recommended to run this when switching between Java versions.

```bash
./gradlew clean
```

--------------------------------

### FirebirdBlob.BlobInputStream Extensions

Source: https://github.com/firebirdsql/jaybird/wiki/JDBC-Extensions

Extensions for FirebirdBlob.BlobInputStream to get the corresponding blob and seek within the stream.

```APIDOC
## FirebirdBlob.BlobInputStream Extensions

### Description
Provides methods to retrieve the parent blob object and to change the read position within a stream blob.

### Methods

#### getBlob()

##### Description
Get the corresponding blob instance.

##### Method
`FirebirdBlob.BlobInputStream.getBlob()`

#### seek( int position )

##### Description
Change the position from which blob content will be read. This method works only for stream blobs.

##### Method
`FirebirdBlob.BlobInputStream.seek( int position )`
```

--------------------------------

### Handling Auto-commit and USER_TRANSACTION

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2023-11-new-design-client-info-properties.adoc

Explains the behavior for setting or getting values from USER_TRANSACTION context when the connection is in auto-commit mode. Operations are silently ignored.

```plaintext
For connections in auto-commit mode, setting or getting values from context USER_TRANSACTION is silently ignored for individual _get_ (return null) and _set_ (do nothing).
```

--------------------------------

### Wildfly Module Configuration (Jaybird 3)

Source: https://github.com/firebirdsql/jaybird/blob/master/src/docs/asciidoc/faq.adoc

Minimal module.xml configuration for using Jaybird 3 with Wildfly. Ensure the JAR path matches your installation.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.firebirdsql">
  <resources>
    <resource-root path="jaybird-3.0.x.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="javax.resource.api"/>
  </dependencies>
</module>
```

--------------------------------

### Sign and Deploy Jar Files (Java 8 Snapshot)

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/maven-release/instructions.txt

Use this command to sign and deploy Jaybird artifacts for Java 8 to the snapshot repository. Ensure paths, URLs, and repository IDs are correctly set.

```bash
mvn gpg:sign-and-deploy-file -DpomFile=jaybird-5.0.0.java8-SNAPSHOT.pom -Dfile=jaybird-5.0.0.java8-SNAPSHOT.jar -Dsources=jaybird-5.0.0.java8-SNAPSHOT-sources.jar -Djavadoc=jaybird-5.0.0.java8-SNAPSHOT-javadoc.jar -Durl=https://oss.sonatype.org/content/repositories/snapshots -DrepositoryId=sonatype-nexus-snapshots
```

--------------------------------

### Run reuse lint manually

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/install-pre-commit-hooks.md

Manually run the 'reuse lint' command to check for compliance with REUSE specifications, including copyright and license information. Ensure the 'reuse' tool is installed separately.

```bash
reuse lint
```

--------------------------------

### Handling SYSTEM Properties Set Explicitly

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2023-11-new-design-client-info-properties.adoc

Demonstrates the behavior when attempting to set SYSTEM properties explicitly. An explicit set throws a SQLClientInfoException.

```java
setClientInfo(String, String)
```

--------------------------------

### Enable specific protocol versions via Gradle

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2023-04-disable-unsupported-protocols.md

Configures Jaybird tests to enable specific protocol versions using the Gradle '-P' option. This example enables protocols 13 and 15.

```bash
gradle test -P'test.enableProtocol=13,15'
```

--------------------------------

### Jaybird Driver Configuration for Base

Source: https://github.com/firebirdsql/jaybird/wiki/LibreOffice-Base

Use these parameters to enable support for the enhanced driver when connecting to Firebird from LibreOffice/OpenOffice Base. Note the specific `jdbc:firebirdsql:oo:` prefix for the URL.

```properties
Driver name|org.firebirdsql.jdbc.FBDriver
JDBC URL|jdbc:firebirdsql:oo://host[:port]/<path_or_alias>
```

```text
jdbc:firebirdsql:oo://localhost/c:/database/employee.fdb
```

--------------------------------

### Enable specific protocol versions for Jaybird tests

Source: https://github.com/firebirdsql/jaybird/blob/master/devdoc/jdp/jdp-2023-04-disable-unsupported-protocols.md

Configures Jaybird tests to enable specific protocol versions using the 'test.enableProtocol' system property. This example enables protocols 13 and 15.

```java
test.enableProtocol=13,15
```

--------------------------------

### TOCbot Initialization and Resize Handling

Source: https://github.com/firebirdsql/jaybird/blob/master/src/docs/theme/jaybird-html/docinfo/docinfo-footer.html

This script initializes TOCbot for dynamic table of contents generation. It also includes a resize handler to refresh TOCbot with different configurations based on screen width, specifically adjusting collapse depth for smaller screens.

```javascript
/* Tocbot dynamic TOC, based on https://github.com/asciidoctor/asciidoctor/issues/699#issuecomment-321066006 */ var oldtoc = document.getElementById('toctitle').nextElementSibling; var newtoc = document.createElement('div'); newtoc.setAttribute('id', 'tocbot'); newtoc.setAttribute('class', 'js-toc'); oldtoc.parentNode.replaceChild(newtoc, oldtoc); tocbot.init({ contentSelector: '#content', headingSelector: 'h1, h2, h3, h4', ignoreSelector: '.float', scrollSmooth: false }); var handleTocOnResize = function() { var width = window.innerWidth || document.documentElement.clientWidth || document.body.clientWidth; if (width < 768) { tocbot.refresh({ contentSelector: '#content', headingSelector: 'h1, h2, h3, h4', ignoreSelector: '.float', collapseDepth: 6, activeLinkClass: 'ignoreactive', throttleTimeout: 1000, scrollSmooth: false }); } else { tocbot.refresh({ contentSelector: '#content', headingSelector: 'h1, h2, h3, h4', ignoreSelector: '.float', scrollSmooth: false }); } }; window.addEventListener('resize', handleTocOnResize); handleTocOnResize();
```