Rebase the branch and update the README.md

Author: ting-lan-wang

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

@@ -10,11 +10,11 @@
   <parent>
     <groupId>com.oracle.database.jdbc</groupId>
     <artifactId>ojdbc-extensions</artifactId>
-    <version>${extensions-version}</version>
+    <version>1.0.6</version>
   </parent>
 
   <properties>
-    <pkl.version>0.27.0</pkl.version>
+    <pkl.version>0.30.0</pkl.version>
     <maven.compiler.source>17</maven.compiler.source>
     <maven.compiler.target>17</maven.compiler.target>
   </properties>
@@ -47,6 +47,13 @@
       <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>
@@ -69,34 +76,16 @@
           </execution>
         </executions>
       </plugin>
-<!--      <plugin>-->
-<!--        &lt;!&ndash; Comment out this plugin for now. We only need to generate the Java class from pkl template only once. &ndash;&gt;-->
-<!--        &lt;!&ndash; There are some changes being made manually in the generated Java class. For example, replacing        &ndash;&gt;-->
-<!--        &lt;!&ndash; dots (.) in variable names with double dollar sign ($$), since dot is illegal in Java variable names. &ndash;&gt;-->
-<!--        <groupId>org.codehaus.mojo</groupId>-->
-<!--        <artifactId>exec-maven-plugin</artifactId>-->
-<!--        <version>3.3.0</version>-->
-<!--        <executions>-->
-<!--          <execution>-->
-<!--            <goals>-->
-<!--              <goal>java</goal>-->
-<!--            </goals>-->
-<!--            <phase>initialize</phase>-->
-<!--          </execution>-->
-<!--        </executions>-->
-<!--        <configuration>-->
-<!--          <mainClass>org.pkl.codegen.java.Main</mainClass>-->
-<!--          <arguments>-->
-<!--            <argument>&#45;&#45;generate-javadoc</argument>-->
-<!--            <argument>-w</argument>-->
-<!--            <argument>${maven.multiModuleProjectDirectory}/ojdbc-provider-pkl</argument>-->
-<!--            <argument>-o</argument>-->
-<!--            <argument>${maven.multiModuleProjectDirectory}/ojdbc-provider-pkl/src/main</argument>-->
-<!--            <argument>src/main/resources/OjdbcConfig.pkl</argument>-->
-<!--          </arguments>-->
-<!--        </configuration>-->
-<!--      </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>

ojdbc-provider-pkl/src/main/java/oracle/jdbc/provider/pkl/configuration/parser/PklParser.java renamed to ojdbc-provider-pkl/src/main/java/oracle/jdbc/provider/pkl/configuration/PklParser.java

@@ -1,6 +1,6 @@
-package oracle.jdbc.provider.pkl.configuration.parser;
+package oracle.jdbc.provider.pkl.configuration;
 
-import oracle.jdbc.provider.pkl.configuration.parser.generated.OjdbcConfig;
+import oracle.jdbc.provider.pkl.configuration.generated.JdbcConfig;
 import oracle.jdbc.spi.OracleConfigurationParser;
 import oracle.jdbc.spi.OracleConfigurationSecretProvider;
 import org.pkl.config.java.Config;
@@ -10,15 +10,18 @@
 import org.pkl.core.ModuleSource;
 import org.pkl.core.PNull;
 
+import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.InputStream;
+import java.io.InputStreamReader;
 import java.lang.reflect.Field;
 import java.nio.charset.StandardCharsets;
 import java.sql.SQLException;
 import java.util.Base64;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Properties;
+import java.util.stream.Collectors;
 
 import static oracle.jdbc.OracleConnection.CONNECTION_PROPERTY_PASSWORD;
 import static oracle.jdbc.OracleConnection.CONNECTION_PROPERTY_WALLET_LOCATION;
@@ -31,11 +34,12 @@ public Properties parse(
     Config pklConfig;
 
     // Parse Pkl config from String
-    try (ConfigEvaluator evaluator = ConfigEvaluator.preconfigured()) {
-      String fileString = new String(inputStream.readAllBytes(), StandardCharsets.UTF_8);
+    try (ConfigEvaluator evaluator = ConfigEvaluator.preconfigured();
+         BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
+      String fileString =  reader.lines().collect(Collectors.joining("\n"));
       pklConfig = evaluator.evaluate(ModuleSource.text(fileString));
     } catch (IOException e) {
-      throw new SQLException(e);
+      throw new SQLException("Failed to parse input stream", e);
     }
 
     // If key is present, we parse that pkl class
@@ -50,7 +54,7 @@ public Properties parse(
     }
 
     // User common connect_descriptor as the URL
-    OjdbcConfig ojdbcConfig = pklConfig.as(OjdbcConfig.class);
+    JdbcConfig ojdbcConfig = pklConfig.as(JdbcConfig.class);
 
     if (ojdbcConfig.connect_descriptor != null)
       properties.put("URL",
@@ -130,7 +134,7 @@ private Config getOptional(Config node, String s) {
     return null;
   }
 
-  private Map<String, String> toSecretMap(OjdbcConfig.Secret secretConfig) {
+  private Map<String, String> toSecretMap(JdbcConfig.Secret secretConfig) {
     // Convert Pkl config to map
     Map<String, String> options = new HashMap<>();
     options.put("value", secretConfig.value);
@@ -145,7 +149,7 @@ private Map<String, String> toSecretMap(OjdbcConfig.Secret secretConfig) {
     return options;
   }
 
-  private Properties toJdbcProperties(OjdbcConfig.Jdbc ojdbcConfig)
+  private Properties toJdbcProperties(JdbcConfig.Jdbc ojdbcConfig)
     throws IllegalAccessException {
 
     Properties properties = new Properties();

ojdbc-provider-pkl/src/main/java/oracle/jdbc/provider/pkl/configuration/parser/generated/OjdbcConfig.java renamed to ojdbc-provider-pkl/src/main/java/oracle/jdbc/provider/pkl/configuration/generated/JdbcConfig.java

@@ -1,4 +1,4 @@
-package oracle.jdbc.provider.pkl.configuration.parser.generated;
+package oracle.jdbc.provider.pkl.configuration.generated;
 
 import java.lang.Boolean;
 import java.lang.Long;
@@ -20,7 +20,7 @@
  * Generator so the changes are made manually for now. The good thing is that
  * this is a one-time process.
  */
-public final class OjdbcConfig {
+public final class JdbcConfig {
   public final @NonNull String connect_descriptor;
 
   public final String user;
@@ -33,10 +33,10 @@ public final class OjdbcConfig {
 
   public final Duration config_time_to_live;
 
-  public OjdbcConfig(@Named("connect_descriptor") @NonNull String connect_descriptor,
-      @Named("user") String user, @Named("password") Secret password,
-      @Named("wallet_location") Secret wallet_location, @Named("jdbc") Jdbc jdbc,
-      @Named("config_time_to_live") Duration config_time_to_live) {
+  public JdbcConfig(@Named("connect_descriptor") @NonNull String connect_descriptor,
+                    @Named("user") String user, @Named("password") Secret password,
+                    @Named("wallet_location") Secret wallet_location, @Named("jdbc") Jdbc jdbc,
+                    @Named("config_time_to_live") Duration config_time_to_live) {
     this.connect_descriptor = connect_descriptor;
     this.user = user;
     this.password = password;
@@ -45,36 +45,36 @@ public OjdbcConfig(@Named("connect_descriptor") @NonNull String connect_descript
     this.config_time_to_live = config_time_to_live;
   }
 
-  public OjdbcConfig withConnect_descriptor(@NonNull String connect_descriptor) {
-    return new OjdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
+  public JdbcConfig withConnect_descriptor(@NonNull String connect_descriptor) {
+    return new JdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
   }
 
-  public OjdbcConfig withUser(String user) {
-    return new OjdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
+  public JdbcConfig withUser(String user) {
+    return new JdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
   }
 
-  public OjdbcConfig withPassword(Secret password) {
-    return new OjdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
+  public JdbcConfig withPassword(Secret password) {
+    return new JdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
   }
 
-  public OjdbcConfig withWallet_location(Secret wallet_location) {
-    return new OjdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
+  public JdbcConfig withWallet_location(Secret wallet_location) {
+    return new JdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
   }
 
-  public OjdbcConfig withJdbc(Jdbc jdbc) {
-    return new OjdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
+  public JdbcConfig withJdbc(Jdbc jdbc) {
+    return new JdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
   }
 
-  public OjdbcConfig withConfig_time_to_live(Duration config_time_to_live) {
-    return new OjdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
+  public JdbcConfig withConfig_time_to_live(Duration config_time_to_live) {
+    return new JdbcConfig(connect_descriptor, user, password, wallet_location, jdbc, config_time_to_live);
   }
 
   @Override
   public boolean equals(Object obj) {
     if (this == obj) return true;
     if (obj == null) return false;
     if (this.getClass() != obj.getClass()) return false;
-    OjdbcConfig other = (OjdbcConfig) obj;
+    JdbcConfig other = (JdbcConfig) obj;
     if (!Objects.equals(this.connect_descriptor, other.connect_descriptor)) return false;
     if (!Objects.equals(this.user, other.user)) return false;
     if (!Objects.equals(this.password, other.password)) return false;
@@ -99,7 +99,7 @@ public int hashCode() {
   @Override
   public String toString() {
     StringBuilder builder = new StringBuilder(350);
-    builder.append(OjdbcConfig.class.getSimpleName()).append(" {");
+    builder.append(JdbcConfig.class.getSimpleName()).append(" {");
     appendProperty(builder, "connect_descriptor", this.connect_descriptor);
     appendProperty(builder, "user", this.user);
     appendProperty(builder, "password", this.password);
@@ -126,8 +126,9 @@ public static final class Secret {
 
     public final Map<@NonNull String, @NonNull String> authentication;
 
-    public Secret(@Named("type") @NonNull String type, @Named("value") @NonNull String value,
-        @Named("authentication") Map<@NonNull String, @NonNull String> authentication) {
+    public Secret(@Named("type") @NonNull String type,
+                  @Named("value") @NonNull String value,
+                  @Named("authentication") Map<@NonNull String, @NonNull String> authentication) {
       this.type = type;
       this.value = value;
       this.authentication = authentication;