From dae666a3ac9f25732fadb49ac3ffc4ce5f41c3ca Mon Sep 17 00:00:00 2001 From: Anders Swanson Date: Thu, 26 Jun 2025 12:03:03 -0700 Subject: [PATCH 1/2] JSON Starter Javadoc Signed-off-by: Anders Swanson --- .../JsonCollectionsAutoConfiguration.java | 5 ++ .../com/oracle/spring/json/jsonb/JSONB.java | 47 +++++++++++++++++++ .../spring/json/jsonb/JSONBRowMapper.java | 4 ++ .../kafka/OSONKafkaSerializationFactory.java | 3 ++ 4 files changed, 59 insertions(+) diff --git a/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/JsonCollectionsAutoConfiguration.java b/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/JsonCollectionsAutoConfiguration.java index a478a156..0a6e0aaf 100644 --- a/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/JsonCollectionsAutoConfiguration.java +++ b/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/JsonCollectionsAutoConfiguration.java @@ -13,6 +13,11 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnClass; import org.springframework.context.annotation.Bean; +/** + * Autoconfiguration for the JSON Collections beans. + * OKafka-related beans are only instantiated if the required interfaces + * are on the classpath. + */ @AutoConfiguration public class JsonCollectionsAutoConfiguration { @Bean diff --git a/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/jsonb/JSONB.java b/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/jsonb/JSONB.java index cb78f544..cfadacf8 100644 --- a/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/jsonb/JSONB.java +++ b/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/jsonb/JSONB.java @@ -14,10 +14,19 @@ import oracle.sql.json.OracleJsonFactory; import org.eclipse.yasson.YassonJsonb; +/** + * The JSONB bean provides utility methods to convert Java objects to and from OSON. + * You may inject this bean into your application, or use the createDefault factory + * method to create a new instance. + */ public class JSONB { private final OracleJsonFactory oracleJsonFactory; private final YassonJsonb jsonb; + /** + * Create a new JSONB instance. + * @return Default JSONB instance. + */ public static JSONB createDefault() { return new JSONB(new OracleJsonFactory(), (YassonJsonb) JsonbBuilder.create()); } @@ -27,6 +36,11 @@ public JSONB(OracleJsonFactory oracleJsonFactory, YassonJsonb jsonb) { this.jsonb = jsonb; } + /** + * Converts a Java object to an OSON byte array. + * @param o Java object to convert to OSON. + * @return OSON byte array. + */ public byte[] toOSON(Object o) { try (ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) { JsonGenerator gen = oracleJsonFactory.createJsonBinaryGenerator(outputStream).wrap(JsonGenerator.class); @@ -38,27 +52,60 @@ public byte[] toOSON(Object o) { } } + /** + * Creates an OSON JsonParser from a Java object. + * @param o Java object to create a JsonParser from. + * @return JsonParser for generating OSON. + */ public JsonParser toJsonParser(Object o) { byte[] oson = toOSON(o); ByteBuffer buf = ByteBuffer.wrap(oson); return oracleJsonFactory.createJsonBinaryParser(buf).wrap(JsonParser.class); } + /** + * Convert an OSON byte array to a Java object of type T. + * @param oson OSON byte array. + * @param clazz Java class to convert OSON to. + * @param Type parameter for the Java conversion class. + * @return Converted Java object of type T. + * @throws IOException When OSON parsing fails. + */ public T fromOSON(byte[] oson, Class clazz) throws IOException { try (ByteArrayInputStream inputStream = new ByteArrayInputStream(oson)) { return fromOSON(inputStream, clazz); } } + /** + * Create a Java object of type T from an OSON JsonParser. + * @param parser OSON JsonParser. + * @param clazz Java object to create. + * @param Type parameter for the Java object. + * @return Converted Java object of type T. + */ public T fromOSON(JsonParser parser, Class clazz) { return jsonb.fromJson(parser, clazz); } + /** + * Create a Java object from an OSON InputStream. + * @param inputStream OSON InputStream. + * @param clazz Java object to create. + * @param Type parameter for the Java object. + * @return Converted Java object of type T. + */ public T fromOSON(InputStream inputStream, Class clazz) { JsonParser jsonParser = oracleJsonFactory.createJsonBinaryParser(inputStream).wrap(JsonParser.class); return jsonb.fromJson(jsonParser, clazz); } + /** Create a Java Object from an OSON ByteBuffer. + * @param byteBuffer OSON ByteBuffer. + * @param clazz Java object to create. + * @param Type parameter for the Java object. + * @return Converted Java object of type T. + */ public T fromOSON(ByteBuffer byteBuffer, Class clazz) { JsonParser jsonParser = oracleJsonFactory.createJsonBinaryParser(byteBuffer).wrap(JsonParser.class); return jsonb.fromJson(jsonParser, clazz); diff --git a/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/jsonb/JSONBRowMapper.java b/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/jsonb/JSONBRowMapper.java index 15b84ee0..662e9701 100644 --- a/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/jsonb/JSONBRowMapper.java +++ b/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/jsonb/JSONBRowMapper.java @@ -8,6 +8,10 @@ import jakarta.json.stream.JsonParser; import org.springframework.jdbc.core.RowMapper; +/** + * JSONBRowMapper maps Oracle Database JSON row data to Java objects. + * @param Type parameter to convert JSON row data into. + */ public class JSONBRowMapper implements RowMapper { private final JSONB mapper; private final Class clazz; diff --git a/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/kafka/OSONKafkaSerializationFactory.java b/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/kafka/OSONKafkaSerializationFactory.java index f1ce5c73..fb53f20c 100644 --- a/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/kafka/OSONKafkaSerializationFactory.java +++ b/database/starters/oracle-spring-boot-json-data-tools/src/main/java/com/oracle/spring/json/kafka/OSONKafkaSerializationFactory.java @@ -4,6 +4,9 @@ import com.oracle.spring.json.jsonb.JSONB; +/** + * Factory class to create OSONDeserializer and OSONSerializer instances. + */ public class OSONKafkaSerializationFactory { private final JSONB jsonb; From cd5624f9e18084016609f35ad59d65b63726143a Mon Sep 17 00:00:00 2001 From: Anders Swanson Date: Thu, 26 Jun 2025 12:05:49 -0700 Subject: [PATCH 2/2] Update doc versions Signed-off-by: Anders Swanson --- .../oracle-spring-boot-sample-txeventqjms/README.md | 2 +- spring-cloud-oci/docs/src/main/asciidoc/aqjms.adoc | 2 +- spring-cloud-oci/docs/src/main/asciidoc/jsoncollection.adoc | 4 ++-- spring-cloud-oci/docs/src/main/asciidoc/ucp.adoc | 4 ++-- spring-cloud-oci/docs/src/main/asciidoc/wallet.adoc | 4 ++-- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-txeventqjms/README.md b/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-txeventqjms/README.md index 797fa07e..81187e91 100644 --- a/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-txeventqjms/README.md +++ b/database/starters/oracle-spring-boot-starter-samples/oracle-spring-boot-sample-txeventqjms/README.md @@ -61,5 +61,5 @@ To use Oracle Spring Boot Starter for TxEventQ and JMS for your Spring Boot appl or if you are using Gradle: ```text -implementation 'com.oracle.database.spring:oracle-spring-boot-starter-aqjms:24.4.0' +implementation 'com.oracle.database.spring:oracle-spring-boot-starter-aqjms:25.3.0' ``` diff --git a/spring-cloud-oci/docs/src/main/asciidoc/aqjms.adoc b/spring-cloud-oci/docs/src/main/asciidoc/aqjms.adoc index 19a4e5a8..fec0ead5 100644 --- a/spring-cloud-oci/docs/src/main/asciidoc/aqjms.adoc +++ b/spring-cloud-oci/docs/src/main/asciidoc/aqjms.adoc @@ -15,7 +15,7 @@ To add this starter to your project, add this Maven dependency: com.oracle.database.spring oracle-spring-boot-starter-aqjms - 25.1.0 + 25.3.0 ---- diff --git a/spring-cloud-oci/docs/src/main/asciidoc/jsoncollection.adoc b/spring-cloud-oci/docs/src/main/asciidoc/jsoncollection.adoc index 06c4284a..2fd5ec62 100644 --- a/spring-cloud-oci/docs/src/main/asciidoc/jsoncollection.adoc +++ b/spring-cloud-oci/docs/src/main/asciidoc/jsoncollection.adoc @@ -11,7 +11,7 @@ This starter provides dependencies and tooling for using JSON with Oracle Databa com.oracle.database.spring oracle-spring-boot-starter-json-collections - 24.4.0 + 25.3.0 ---- @@ -20,7 +20,7 @@ For Gradle projects, add this dependency: [source,subs="normal"] ---- dependencies { - implementation 'com.oracle.database.spring:oracle-spring-boot-starter-json-collections:24.4.0' + implementation 'com.oracle.database.spring:oracle-spring-boot-starter-json-collections:25.3.0' } ---- diff --git a/spring-cloud-oci/docs/src/main/asciidoc/ucp.adoc b/spring-cloud-oci/docs/src/main/asciidoc/ucp.adoc index 1e6c4aeb..27dd33b6 100644 --- a/spring-cloud-oci/docs/src/main/asciidoc/ucp.adoc +++ b/spring-cloud-oci/docs/src/main/asciidoc/ucp.adoc @@ -13,7 +13,7 @@ To add this starter to your project, add this Maven dependency: com.oracle.database.spring oracle-spring-boot-starter-ucp - 24.4.0 + 25.3.0 ---- @@ -22,7 +22,7 @@ For Gradle projects, add this dependency: [source,subs="normal"] ---- dependencies { - implementation 'com.oracle.database.spring:oracle-spring-boot-starter-ucp:24.4.0' + implementation 'com.oracle.database.spring:oracle-spring-boot-starter-ucp:25.3.0' } ---- diff --git a/spring-cloud-oci/docs/src/main/asciidoc/wallet.adoc b/spring-cloud-oci/docs/src/main/asciidoc/wallet.adoc index cdb4788c..28ca9297 100644 --- a/spring-cloud-oci/docs/src/main/asciidoc/wallet.adoc +++ b/spring-cloud-oci/docs/src/main/asciidoc/wallet.adoc @@ -13,7 +13,7 @@ To add this starter to your project, add this Maven dependency: com.oracle.database.spring oracle-spring-boot-starter-wallet - 24.4.0 + 25.3.0 ---- @@ -22,6 +22,6 @@ For Gradle projects, add this dependency: [source,subs="normal"] ---- dependencies { - implementation 'com.oracle.database.spring:oracle-spring-boot-starter-wallet:24.4.0' + implementation 'com.oracle.database.spring:oracle-spring-boot-starter-wallet:25.3.0' } ----