Add pkl support

.github/workflows/run-tests.yaml

@@ -16,10 +16,11 @@ jobs:
     steps:
       - name: Checkout the repository
         uses: actions/checkout@v4
-      - name: Set up JDK 11
-        uses: actions/setup-java@v1
+      - name: Set up JDK 17
+        uses: actions/setup-java@v5
         with:
-          java-version: 11
+          distribution: 'oracle'
+          java-version: '17'
       - name: Cache Maven packages
         uses: actions/cache@v4
         with:

README.md

@@ -30,6 +30,8 @@ Each module of this project contains a set of providers.
 <dt><a href="ojdbc-provider-jackson-oson/README.md">Oracle JDBC Jackson OSON</a></dt>
 <dd>Provider for <a href="https://docs.oracle.com/en/database/oracle/oracle-database/23/adjsn/json-in-oracle-database.html#GUID-A8A58B49-13A5-4F42-8EA0-508951DAE0BB">OSON</a> through the JACKSON APIs. 
 This provider can be used for seamless integration of applications that use the JACKSON APIs with the Oracle JSON type.</dd>
+<dt><a href="ojdbc-provider-pkl/README.md">Oracle JDBC Pkl Parser</a></dt>
+<dd>Parser for integration with Pkl that can be used by providers</dd>
 </dl>
 Visit any of the links above to learn about providers which are available for 
 a particular platform.
@@ -144,6 +146,8 @@ this project:
 
 [ojdbc-provider-jackson-oson](ojdbc-provider-jackson-oson/README.md#installation)
 
+[ojdbc-provider-pkl](ojdbc-provider-pkl/README.md#installation)
+
 
 Each module listed above is distributed on the Maven Central Repository as a
 separate jar file. Coordinates can be found by visiting the links above.

ojdbc-provider-pkl/README.md

@@ -0,0 +1,107 @@
+# Oracle JDBC Configuration Provider Parser for Pkl
+
+This module provides a parser that integrates **Oracle JDBC** with **Pkl**, a modern configuration language.  
+It implements the `OracleConfigurationParser` interface to parse and read `.pkl` files for database configuration.
+
+With the Oracle JDBC Pkl Parser, developers can store JDBC configurations in `.pkl` files and load them dynamically through Oracle JDBC Driver Extensions.
+
+> **Note:** This parser works only with providers that extend `OracleConfigurationParsableProvider`, such as `file`, `https`, `ociobject`, `awss3`, and others.
+> 
+## Installation
+
+All providers in this module are distributed as single jar on the Maven Central
+Repository. The jar is compiled for JDK 8, and is forward compatible with later
+JDK versions. The coordinates for the latest release are:
+
+```xml
+<dependency>
+  <groupId>com.oracle.database.jdbc</groupId>
+  <artifactId>ojdbc-provider-pkl</artifactId>
+  <version>1.0.6</version>
+</dependency>
+```
+
+## Usage 
+
+To use the Oracle JDBC Pkl Parser:
+
+1. Prepare a .pkl configuration file (see examples below).
+2. Add this artifact to your application's classpath.
+3. Reference the .pkl file in the JDBC URL.
+
+The parser type is inferred from the file extension. In this case, it’s "pkl".
+If the file name doesn’t include an extension, you can specify the parser explicitly using the parser option.
+All other options (like key, label, etc.) follow the same format as other providers.
+
+Example using the file configuration provider:
+
+```java
+jdbc:oracle:thin:@config-file://{pkl-file-name}[?parser=pkl&key=prefix&label=value&option1=value1&option2=value2...]
+```
+
+## Writing .pkl Configuration
+
+There are two approaches to filling out a template: **amends** and **import**.
+
+### 1. Using `amends`
+
+#### myJdbcConfig.pkl
+
+```yaml
+amends "https://raw.githubusercontent.com/oracle/ojdbc-extensions/ojdbc-provider-pkl/src/main/resources/JdbcConfig.pkl"
+
+connect_descriptor = "dbhost:1521/orclpdb1"
+user = "scott"
+
+password {
+  type = "ocivault"
+  value = "ocid1.vaultsecret..."
+  authentication {
+    ["method"] = "OCI_DEFAULT"
+  }
+}
+
+jdbc {
+  autoCommit = false
+  `oracle.jdbc.loginTimeout` = 60.s
+}
+```
+
+#### URL (using file provider):
+
+```java
+jdbc:oracle:thin:@config-file://myJdbcConfig.pkl
+```
+
+### 2. Using `import`
+
+#### myJdbcConfig.pkl
+
+```yaml
+import "https://raw.githubusercontent.com/oracle/ojdbc-extensions/ojdbc-provider-pkl/src/main/resources/JdbcConfig.pkl"
+
+config1 = (JdbcConfig) {
+  connect_descriptor = "dbhost:1521/orclpdb1"
+
+  user = "scott"
+
+  password {
+    type = "ocivault"
+    value = "ocid1.vaultsecret..."
+    authentication {
+      ["method"] = "OCI_DEFAULT"
+    }
+  }
+
+  jdbc {
+    autoCommit = false
+    `oracle.jdbc.loginTimeout` = 60.s
+  }
+}
+```
+
+#### URL (using file provider):
+
+```java
+jdbc:oracle:thin:@config-file://myJdbcConfig.pkl?key=config1
+```

ojdbc-provider-pkl/pom.xml

@@ -0,0 +1,87 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <name>Oracle JDBC Providers Pkl Module</name>
+
+  <artifactId>ojdbc-provider-pkl</artifactId>
+  <packaging>jar</packaging>
+
+  <parent>
+    <groupId>com.oracle.database.jdbc</groupId>
+    <artifactId>ojdbc-extensions</artifactId>
+    <version>1.0.6</version>
+  </parent>
+
+  <properties>
+    <pkl.version>0.30.0</pkl.version>
+    <java.version>17</java.version>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.oracle.database.jdbc</groupId>
+      <artifactId>ojdbc8</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.pkl-lang</groupId>
+      <artifactId>pkl-config-java</artifactId>
+      <version>${pkl.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+    </dependency>
+    <!-- TEST DEPENDENCIES -->
+    <dependency>
+      <groupId>com.oracle.database.jdbc</groupId>
+      <artifactId>ojdbc-provider-common</artifactId>
+      <classifier>tests</classifier>
+      <type>test-jar</type>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.11.0</version>
+        <configuration>
+          <release>${java.version}</release>
+        </configuration>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <version>3.3.0</version>
+        <executions>
+          <execution>
+            <goals>
+              <!--
+                The test classes of this module are used by test classes of
+                the sibling modules (OCI and Azure).
+                Maven's jar plugin is configured to generate a test-jar. The
+                sibling modules then declare a dependency on it.
+                -->
+              <goal>test-jar</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+    <resources>
+      <resource>
+        <directory>src/main/resources</directory>
+        <includes>
+          <include>**/*.pkl</include>
+          <include>META-INF/services/oracle.jdbc.spi.*</include>
+        </includes>
+      </resource>
+    </resources>
+  </build>
+
+</project>