JSON Starter Javadoc

Signed-off-by: Anders Swanson <anders.swanson@oracle.com>

Author: anders-swanson

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

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 <T> Type parameter for the Java conversion class.
+     * @return Converted Java object of type T.
+     * @throws IOException When OSON parsing fails.
+     */
     public <T> T fromOSON(byte[] oson, Class<T> 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 <T> Type parameter for the Java object.
+     * @return Converted Java object of type T.
+     */
     public <T> T fromOSON(JsonParser parser, Class<T> 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 <T> Type parameter for the Java object.
+     * @return Converted Java object of type T.
+     */
     public <T> T fromOSON(InputStream inputStream, Class<T> 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 <T> Type parameter for the Java object.
+     * @return Converted Java object of type T.
+     */
     public <T> T fromOSON(ByteBuffer byteBuffer, Class<T> clazz) {
         JsonParser jsonParser = oracleJsonFactory.createJsonBinaryParser(byteBuffer).wrap(JsonParser.class);
         return jsonb.fromJson(jsonParser, clazz);

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 <T> Type parameter to convert JSON row data into.
+ */
 public class JSONBRowMapper<T> implements RowMapper<T> {
     private final JSONB mapper;
     private final Class<T> clazz;

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;