Feature/storm 25 (#26)

* Eliminate annotations from metamodel.
* Add nullable reference method.
* Document and clean up conversion logic.

Author: zantvoort

README.adoc

@@ -45,15 +45,15 @@ Maven::
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm</artifactId>
-    <version>1.3.4</version>
+    <version>1.3.5</version>
     <scope>compile</scope>
 </dependency>
 ----
 Gradle::
 +
 [source,groovy]
 ----
-implementation 'st.orm:storm:1.3.4'
+implementation 'st.orm:storm:1.3.5'
 ----
 ====
 
@@ -846,15 +846,15 @@ Maven::
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-oracle</artifactId>
-    <version>1.3.4</version>
+    <version>1.3.5</version>
     <scope>runtime</scope>
 </dependency>
 ----
 Gradle::
 +
 [source,groovy]
 ----
-runtimeOnly 'st.orm:storm-oracle:1.3.4'
+runtimeOnly 'st.orm:storm-oracle:1.3.5'
 ----
 ====
 
@@ -876,15 +876,15 @@ Maven::
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-metamodel-processor</artifactId>
-    <version>1.3.4</version>
+    <version>1.3.5</version>
     <scope>provided</scope>
 </dependency>
 ----
 Gradle::
 +
 [source,groovy]
 ----
-annotationProcessor 'st.orm:storm-metamodel-processor:1.3.4'
+annotationProcessor 'st.orm:storm-metamodel-processor:1.3.5'
 ----
 ====
 
@@ -952,15 +952,15 @@ Maven::
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-json</artifactId>
-    <version>1.3.4</version>
+    <version>1.3.5</version>
     <scope>compile</scope>
 </dependency>
 ----
 Gradle::
 +
 [source,groovy]
 ----
-implementation 'st.orm:storm-json:1.3.4'
+implementation 'st.orm:storm-json:1.3.5'
 ----
 ====
 
@@ -1096,15 +1096,15 @@ Maven::
 <dependency>
     <groupId>st.orm</groupId>
     <artifactId>storm-spring</artifactId>
-    <version>1.3.4</version>
+    <version>1.3.5</version>
     <scope>compile</scope>
 </dependency>
 ----
 Gradle::
 +
 [source,groovy]
 ----
-implementation 'st.orm:storm-spring:1.3.4'
+implementation 'st.orm:storm-spring:1.3.5'
 ----
 ====
 

pom.xml

@@ -12,7 +12,7 @@
     </properties>
     <groupId>st.orm</groupId>
     <artifactId>storm-framework</artifactId>
-    <version>1.3.4</version>
+    <version>1.3.5</version>
     <packaging>pom</packaging>
     <name>Storm Framework</name>
     <description>A SQL Template and ORM framework, focusing on modernizing and simplifying database programming.</description>

storm-json/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>st.orm</groupId>
         <artifactId>storm-framework</artifactId>
-        <version>1.3.4</version>
+        <version>1.3.5</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     <artifactId>storm-json</artifactId>

storm-json/src/main/java/st/orm/json/spi/JsonORMConverterImpl.java

@@ -39,9 +39,14 @@
 
 import static com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_MISSING_CREATOR_PROPERTIES;
 import static com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES;
+import static java.util.Objects.requireNonNull;
 import static java.util.Optional.empty;
 
-public class JsonORMConverterImpl implements ORMConverter {
+/**
+ * Implementation of {@link ORMConverter} that converts JSON fields to and from the database. It uses Jackson for JSON
+ * serialization and deserialization.
+ */
+public final class JsonORMConverterImpl implements ORMConverter {
     private static final ORMReflection REFLECTION = Providers.getORMReflection();
     private static final Map<CacheKey, ObjectMapper> OBJECT_MAPPER = new ConcurrentHashMap<>();
 
@@ -51,13 +56,15 @@ public class JsonORMConverterImpl implements ORMConverter {
 
     record CacheKey(Class<?> sealedType, Json json) {}
 
-    public JsonORMConverterImpl(@Nonnull RecordComponent component, @Nonnull TypeReference<?> typeReference, @Nonnull Json json) {
-        this.component = component;
-        this.typeReference = typeReference;
+    public JsonORMConverterImpl(@Nonnull RecordComponent component,
+                                @Nonnull TypeReference<?> typeReference,
+                                @Nonnull Json json) {
+        this.component = requireNonNull(component, "component");
+        this.typeReference = requireNonNull(typeReference, "typeReference");
         var type = getRawType(typeReference.getType())
                 .filter(Class::isSealed)
                 .orElse(null);
-        this.mapper = OBJECT_MAPPER.computeIfAbsent(new CacheKey(type, json), key -> {
+        this.mapper = OBJECT_MAPPER.computeIfAbsent(new CacheKey(type, requireNonNull(json, "json")), key -> {
             var mapper = new ObjectMapper();
             mapper.findAndRegisterModules();
             if (!json.failOnUnknown()) {
@@ -93,37 +100,72 @@ private static NamedType[] getPermittedSubtypes(Class<?> sealedClass) {
                 .toArray(NamedType[]::new);
     }
 
+    /**
+     * Returns the number of parameters in the SQL template.
+     *
+     * <p><strong>Note:</strong> the count must match the parameter as returned by {@link #getParameterTypes()}.</p>
+     *
+     * @return the number of parameters.
+     */
     @Override
     public int getParameterCount() {
+        // The number of parameters is always 1 for this implementation, as it only handles a single JSON field.
         return 1;
     }
 
+    /**
+     * Returns the types of the parameters in the SQL template.
+     *
+     * @return a list of parameter types.
+     */
     @Override
     public List<Class<?>> getParameterTypes() {
         return List.of(String.class);
     }
 
-    @Override
-    public Object convert(@Nonnull Object[] args) throws SqlTemplateException {
-        try {
-            Object arg = args[0];
-            return arg == null ? null : mapper.readValue((String) args[0], typeReference);
-        } catch (JsonProcessingException e) {
-            throw new SqlTemplateException(e);
-        }
-    }
-
+    /**
+     * Returns the names of the columns that will be used in the SQL template.
+     *
+     * <p><strong>Note:</strong> the names must match the parameters as returned by {@link #getParameterTypes()}.</p>
+     *
+     * @return a list of column names.
+     */
     @Override
     public List<Name> getColumns(@Nonnull NameResolver nameResolver) throws SqlTemplateException {
         return List.of(nameResolver.getName(component));
     }
 
+    /**
+     * Converts the given record to a list of values that can be used in the SQL template.
+     *
+     * <p><strong>Note:</strong> the values must match the parameters as returned by {@link #getParameterTypes()}.</p>
+     *
+     * @param record the record to convert.
+     * @return the values to be used in the SQL template.
+     */
     @Override
-    public List<Object> getValues(@Nullable Record record) throws SqlTemplateException {
+    public List<Object> toDatabase(@Nullable Record record) throws SqlTemplateException {
         try {
             return List.of(mapper.writeValueAsString(record == null ? null : REFLECTION.invokeComponent(component, record)));
         } catch (Throwable e) {
             throw new SqlTemplateException(e);
         }
     }
+
+    /**
+     * Converts the given values to an object that is used in the object model.
+     *
+     * @param values the arguments to convert. The arguments match the parameters as returned by getParameterTypes().
+     * @return the converted object.
+     * @throws SqlTemplateException if an error occurs during conversion.
+     */
+    @Override
+    public Object fromDatabase(@Nonnull Object[] values) throws SqlTemplateException {
+        try {
+            Object value = values[0];
+            return value == null ? null : mapper.readValue((String) values[0], typeReference);
+        } catch (JsonProcessingException e) {
+            throw new SqlTemplateException(e);
+        }
+    }
 }

storm-json/src/main/java/st/orm/json/spi/JsonORMConverterProviderImpl.java

@@ -28,9 +28,21 @@
 
 import static java.util.Optional.empty;
 
+/**
+ * Provides an ORM converter for JSON annotated record components.
+ *
+ * <p>This implementation retrieves the {@link Json} annotation from the record component and creates a
+ * {@link JsonORMConverterImpl} if the annotation is present.</p>
+ */
 public class JsonORMConverterProviderImpl implements ORMConverterProvider {
     private static final ORMReflection REFLECTION = Providers.getORMReflection();
 
+    /**
+     * Retrieves the converter for the specified record component.
+     *
+     * @param component the record component for which to get the converter
+     * @return an Optional containing the ORMConverter if available, or empty if not supported.
+     */
     @Override
     public Optional<ORMConverter> getConverter(@Nonnull RecordComponent component) {
         Json json = REFLECTION.getAnnotation(component, Json.class);

storm-kotlin/pom.xml

@@ -6,7 +6,7 @@
     <parent>
         <groupId>st.orm</groupId>
         <artifactId>storm-framework</artifactId>
-        <version>1.3.4</version>
+        <version>1.3.5</version>
         <relativePath>../pom.xml</relativePath>
     </parent>
     <artifactId>storm-kotlin</artifactId>

storm-kotlin/src/main/java/st/orm/kotlin/template/KORMTemplate.java

@@ -15,100 +15,20 @@
  */
 package st.orm.kotlin.template;
 
+import st.orm.kotlin.KTemplates;
 import st.orm.kotlin.repository.KRepositoryLookup;
 import st.orm.kotlin.template.impl.KORMTemplateImpl;
+import st.orm.repository.EntityRepository;
+import st.orm.repository.ProjectionRepository;
 import st.orm.template.ORMTemplate;
 
 /**
- * <p>The {@link KORMTemplate} supports a fluent API that allows you to build queries in a more concise manner:
+ * <p>The {@code KORMTemplate} is the primary interface that extends the {@code KQueryTemplate} and
+ * {@code KRepositoryLooking} interfaces, providing access to both the SQL Template engine and ORM logic.
  *
- * <pre>{@code
- * DataSource dataSource = ...;
- * List<User> users = KTemplates.ORM(dataSource).entity(User.class)
- *     .select()
- *     .where("city", Operator.EQUALS, "Sunnyvale")
- *     .getResultList();
- * }</pre>
- *
- * <p>In this example, the query is constructed by chaining method calls, enhancing readability and reducing boilerplate code.
- * The {@code entity(Class<T> clazz)} method specifies the entity type for the query, and subsequent methods like {@code select()}
- * and {@code where()} build upon it.
- *
- * <h2>Key Features</h2>
- * <ul>
- *   <li><strong>Type Safety:</strong> Leverages Java generics and type inference to ensure that queries are type-safe.</li>
- *   <li><strong>Fluent API:</strong> Supports method chaining to build queries in a readable and concise manner.</li>
- *   <li><strong>Flexibility:</strong> Compatible with both JPA and JDBC, allowing you to choose the underlying technology.</li>
- *   <li><strong>SQL Templates:</strong> Integrates with SQL string templates for dynamic query construction.</li>
- *   <li><strong>Ease of Use:</strong> Reduces boilerplate code and simplifies common database operations.</li>
- * </ul>
- *
- * <h2>Creating KORMTemplate Instances</h2>
- *
- * <p>The {@code KTemplates} interface provides static methods to create {@link KORMTemplate} instances based on your data source:
- *
- * <h3>Using EntityManager (JPA)</h3>
- * <pre>{@code
- * EntityManager entityManager = ...;
- * KORMTemplate orm = Kemplates.ORM(entityManager);
- * }</pre>
- *
- * <h3>Using DataSource (JDBC)</h3>
- * <pre>{@code
- * DataSource dataSource = ...;
- * KORMTemplate orm = KTemplates.ORM(dataSource);
- * }</pre>
- *
- * <h3>Using Connection (JDBC)</h3>
- *
- * <p><strong>Note:</strong> The caller is responsible for closing the connection after usage.
- *
- * <pre>{@code
- * Connection connection = ...;
- * ORMTemplate orm = KTemplates.KORM(connection);
- * }</pre>
- *
- * <h2>Example: Querying with Fluent API</h2>
- * <p>Here is a more detailed example demonstrating how to use the fluent API to perform a query:
- * <pre>{@code
- * DataSource dataSource = ...;
- * List<User> users = ORM(dataSource).entity(User.class)
- *     .select()
- *     .where("city.name", Operator.EQUALS, "Sunnyvale")
- *     .getResultList();
- * }</pre>
- *
- * <p>In this example:
- * <ul>
- *   <li>{@code entity(User.class)} specifies the entity to query.</li>
- *   <li>{@code select()} constructs the SELECT clause.</li>
- *   <li>{@code where("city", Operator.EQUALS, "Sunnyvale")} adds a WHERE condition.</li>
- *   <li>{@code getResultList()} executes the query and returns the results as a list.</li>
- * </ul>
- *
- * <h2>Integration with SQL Templates</h2>
- * <p>You can seamlessly integrate the fluent API with SQL templates when needed. For instance, you can combine method chaining with template-based queries:
- *
- * <pre>{@code
- * City city = ORM(dataSource).entity(City.class)
- *     .select()
- *     .where(RAW."name = \{"Sunnyvale"}")
- *     .getSingleResult();
- * List<User> users = ORM(dataSource).query(RAW."""
- *         SELECT \{User.class}
- *         FROM \{User.class}
- *         WHERE \{city)}""")
- *     .getResultList(User.class);
- * }</pre>
- *
- * <h2>Conclusion</h2>
- *
- * <p>The {@code KTemplates} interface streamlines the process of writing database queries by integrating
- * object-relational mapping with SQL string templates and a fluent API, ensuring type safety and reducing boilerplate code.
- * Whether you prefer constructing queries using SQL templates or method chaining, the {@code KTemplates} interface provides
- * flexible options to suit your development style.
- *
- * @see st.orm.kotlin.KTemplates
+ * @see KTemplates
+ * @see EntityRepository
+ * @see ProjectionRepository
  */
 public interface KORMTemplate extends KQueryTemplate, KRepositoryLookup {
 

storm-kotlin/src/main/java/st/orm/kotlin/template/KQueryBuilder.java

@@ -702,7 +702,7 @@ public final KQueryBuilder<T, R, ID> whereRef(@Nonnull Iterable<? extends Ref<T>
     }
 
     /**
-     * Adds WHERE clause that matches the specified record. The record can represent any of the related tables in the
+     * Adds a WHERE clause that matches the specified record. The record can represent any of the related tables in the
      * table graph.
      *
      * @param path the path to the object in the table graph.
@@ -714,7 +714,7 @@ public final <V extends Record> KQueryBuilder<T, R, ID> where(@Nonnull Metamodel
     }
 
     /**
-     * Adds WHERE clause that matches the specified ref. The ref can represent any of the related tables in the
+     * Adds a WHERE clause that matches the specified ref. The ref can represent any of the related tables in the
      * table graph.
      *
      * @param path the path to the object in the table graph.

storm-kotlin/src/main/java/st/orm/kotlin/template/impl/KColumnImpl.java

@@ -81,7 +81,7 @@ public String name() {
     }
 
     /**
-     * Gets the qualified name of the column including escape characters where necessary.
+     * Gets the qualified name of the column, including escape characters where necessary.
      *
      * @param dialect the SQL dialect.
      * @return the qualified column name.