Better Examples in comments, better error handling of some exceptions - additional test case.

Author: johnlpage

memex/README.md

@@ -392,7 +392,7 @@ classes for an Entity including all the new
 derived classes by running the maven goal. This adds a Generic flexible model.
 
 ```shell
- mvn generate-sources -Pgenerate-entity -Dentity=Company -Dplural=companies -DidFieldName=companyNumber -DidFieldType=String
+ mvn generate-sources -Pgenerate-entity -Dentity=MyEntity -Dplural=entities -DidFieldName=entityId -DidFieldType=Long
 ```
 
 You can delete it with
@@ -409,7 +409,7 @@ field in the JSON
 
 ```shell
 
- mvn generate-sources -Pgenerate-models-from-json   -DjsonFile=../companies250k.json  -DbasePackage=com.johnlpage.memex  -Dentity=Company  -DidFieldName=companyNumber
+ mvn generate-sources -Pgenerate-models-from-json   -DjsonFile=../DataGen/mot.json  -DbasePackage=com.johnlpage.memex  -Dentity=MyEntity  -DidFieldName=myentityId
 
 ```
 

memex/pom.xml

@@ -233,7 +233,7 @@
             <plugin>
                 <groupId>org.jacoco</groupId>
                 <artifactId>jacoco-maven-plugin</artifactId>
-                <version>0.8.12</version>
+                <version>0.8.14</version>
                 <executions>
                     <execution>
                         <id>jacoco-initialize</id>

memex/src/main/java/com/johnlpage/memex/VehicleInspection/controller/VehicleInspectionController.java

@@ -63,7 +63,7 @@ public class VehicleInspectionController {
 
     @GetMapping("/vehicles/id/{id}")
     public ResponseEntity<Vehicle> vehicleById(@PathVariable Long id) {
-        // While you can to straight to the repository, it's  best practise to use a service.
+        // Vehicles are embedde din inspections but can still have their own repository
         return vehicleRepository
                 .findByVehicleIdWithInspections(id)
                 .map(ResponseEntity::ok)
@@ -161,25 +161,27 @@ public ResponseEntity<PageDto<VehicleInspection>> getInspectionsByModel(
      */
     @PostMapping(value = "/inspections/query", produces = MediaType.APPLICATION_JSON_VALUE)
     public ResponseEntity<String> mongoQuery(@RequestBody String requestBody) {
-        List<VehicleInspection> result = queryService.mongoDbNativeQuery(requestBody);
+
         try {
+            List<VehicleInspection> result = queryService.mongoDbNativeQuery(requestBody);
             // Convert list to JSON string
             String jsonResult = objectMapper.writeValueAsString(result);
             return ResponseEntity.ok(jsonResult);
-        } catch (JsonProcessingException e) {
-            return ResponseEntity.status(500).body("Error converting vehicles to JSON");
+        } catch (Exception e) {
+            return ResponseEntity.status(500).body("Error " + e.getMessage());
         }
     }
 
     @PostMapping("/inspections/search")
     public ResponseEntity<String> atlasSearchQuery(@RequestBody String requestBody) {
-        List<VehicleInspection> result = queryService.atlasSearchQuery(requestBody);
+
         try {
+            List<VehicleInspection> result = queryService.atlasSearchQuery(requestBody);
             // Convert list to JSON string
             String jsonResult = objectMapper.writeValueAsString(result);
             return ResponseEntity.ok(jsonResult);
-        } catch (JsonProcessingException e) {
-            return ResponseEntity.status(500).body("Error converting vehicles to JSON");
+        } catch (Exception e) {
+            return ResponseEntity.status(500).body("Error "+e.getMessage()) ;
         }
     }
 

memex/src/main/java/com/johnlpage/memex/VehicleInspection/repository/VehicleInspectionRepository.java

@@ -6,13 +6,19 @@
 import com.johnlpage.memex.generics.repository.OptimizedMongoLoadRepository;
 import com.johnlpage.memex.generics.repository.OptimizedMongoQueryRepository;
 
+import java.util.List;
 import java.util.stream.Stream;
 
+import org.bson.Document;
+import org.springframework.data.mongodb.repository.Aggregation;
 import org.springframework.data.mongodb.repository.MongoRepository;
+import org.springframework.data.mongodb.repository.Query;
+import org.springframework.data.mongodb.repository.Update;
 import org.springframework.stereotype.Repository;
 
-/* The repository lets you define simple operations by name of function or by Javascript
-versions of MongoDB queries
+/* The repository Shows examples of the different ways you can define Queries.
+   Annotation based (@Quer, @Aggregation), Derived query Methods and
+   Custom methods using a variety of types/
 */
 @Repository
 public interface VehicleInspectionRepository
@@ -22,31 +28,32 @@ public interface VehicleInspectionRepository
         OptimizedMongoDownstreamRepository<VehicleInspection>,
         MongoHistoryRepository<VehicleInspection, Long> {
 
-  /*
-   * EXAMPLE REPOSITORY METHODS
-   *
-   *
-  // Find inspections by engine capacity - auto generated query
-  List<VehicleInspection> findAllByCapacityGreaterThan(Long engineCapacity);
-
-  // Custom query to find vehicle inspections by vehicle make and model
-  @Query("{ 'vehicle.make': ?0, 'vehicle.model': ?1 }")
-  List<VehicleInspection> findByVehicleMakeAndModel(String make, String model);
-
-  // Custom aggregation to compute mean mileage of a given model
-  @Aggregation(
-      pipeline = {
-        "{ '$match': { 'vehicle.model': ?0 } }",
-        "{ '$group': { '_id': null, 'averageMileage': { '$avg': '$vehicle.mileage' } } }"
-      })
-  List<Document> findAverageMileageByModel(String model);
-
-  // Simple efficient update without reading or sending whole document (N.B won't do history)
-  @Query("{ 'testid' : ?0 }")
-  @Update("{ 'inc' : { 'testmileage' : ?1 } }")
-  void adjustTestMileage(Long testid, int increment);
-  */
-
-    // You have to explicitly call out a streaming version here if you want it.
+
+    // Find inspections by engine capacity - Automatically derived query
+    List<VehicleInspection> findByCapacityGreaterThan(Long engineCapacity);
+
+    // Derived Query with Boolean and
+    List<VehicleInspection> findByVehicleColourAndVehicleModel(String colour, String model);
+
+    // Annotation-based aggregation (Group By in this case) returning a Docuement as a generic type
+    @Aggregation(
+            pipeline = {
+                    "{ '$match': { 'vehicle.model': ?0 } }",
+                    "{ '$group': { '_id': null, 'averageMileage': { '$avg': '$vehicle.mileage' } } }"
+            })
+    List<Document> findAverageMileageByModel(String model);
+
+
+    // Simple efficient annotation update without reading or sending the whole document (N.B won't do history)
+    @Query("{ 'testid' : ?0 }")
+    @Update("{ 'inc' : { 'testmileage' : ?1 } }")
+    void adjustTestMileage(Long testid, int increment);
+
+    // An Annotation using MongoDB Query Language - opens up more query operators
+    @Query("{ 'vehicle.make': ?0, 'vehicle.model': ?1 }")
+    List<VehicleInspection> findByVehicleMakeAndModel(String make, String model);
+
+
+    // Fetch whole collection as a stream.
     Stream<VehicleInspection> findAllBy();
 }

memex/src/main/java/com/johnlpage/memex/VehicleInspection/repository/VehicleRepository.java

@@ -8,13 +8,14 @@
 import org.springframework.data.mongodb.repository.MongoRepository;
 import org.springframework.stereotype.Repository;
 
-/* The repository lets you define simple operations by name of function or by Javascript
-versions of MongoDB queries
+/* The Vehicle Model is not top level, Vehicles are a child of VehicleInspection
+   This shows how you can still have a Vehicle repository that works on a child
+   element including arrays.
 */
 @Repository
 public interface VehicleRepository extends MongoRepository<Vehicle, Long> {
 
-    // We don't have a separate vehicle collection so any Queries need to be sent to VehicleInspection
+    // As we don't have a vehicle collection all Queries need to be sent to VehicleInspection
 
     // VehicleInspection - Start with matching nothing then use $unionWith to swap collections
     // Find inside the embedded object then use replaceWith to just keep the vehicle object
@@ -30,6 +31,7 @@ public interface VehicleRepository extends MongoRepository<Vehicle, Long> {
     Optional<Vehicle> findByVehicleId(Long id);
 
     // Fetch a Vehicle then add all it's inspections to it. - N.B make sure this is indexed.
+    // This is a pivot compared to the storage format
 
     @Aggregation(
             pipeline = {

memex/src/main/java/com/johnlpage/memex/generics/repository/OptimizedMongoQueryRepositoryImpl.java

@@ -97,6 +97,7 @@ public List<T> mongoDbNativeQuery(String jsonString, Class<T> clazz) {
     }
 
     public int costMongoDbNativeQuery(String jsonString, Class<T> clazz) {
+
         Document queryRequest = Document.parse(jsonString);
         Document filter = queryRequest.get("filter", new Document());
         Document projection = queryRequest.get("projection", new Document());

memex/src/main/java/com/johnlpage/memex/generics/service/HistoryTriggerService.java

@@ -23,6 +23,9 @@
 import org.springframework.stereotype.Service;
 
 /* This trigger writes out a change history for documents modified in OptimizedMonogoLoadRepository*/
+//TODO - Change this to diff all arrays with prior version and store only elements that
+//Have Changed, for elements that are the same store the BSON MinKey byte
+//This will need new aggreagtion based mering code to match
 
 @Service
 public abstract class HistoryTriggerService<T> extends PostWriteTriggerService<T> {

memex/src/test/resources/features/inspections.rest.mongo-query.feature

@@ -46,13 +46,27 @@ Feature: Vehicle Inspection REST API - Native MongoDB Query Execution
     And each item in the response array should contain "vehicle.model": "Corolla"
 
   @post @rainy_day
-  Scenario: Fail to execute a native MongoDB query due to invalid syntax
+  Scenario: Fail to execute a native MongoDB query due to invalid query syntax
     When I send a POST request to "/api/inspections/query" with the payload:
-      """{
+      """
+      {
         "filter": {
           "$invalid_operator": "value"
         }
       }
       """
     Then the response status code should be 500
-    And the response should contain "Internal Server Error"
+    And the response should contain "unknown top level operator"
+
+  @post @rainy_day
+  Scenario: Fail to execute a native MongoDB query due to invalid JSON
+    When I send a POST request to "/api/inspections/query" with the payload:
+      """
+
+       "filter": {
+          "vehicle.model": "Corolla"
+         }
+      }
+      """
+    Then the response status code should be 500
+    And the response should contain "readStartDocument"

memex/templates/repository/Repository.java.template

@@ -22,28 +22,67 @@ public interface __className__Repository
         OptimizedMongoDownstreamRepository<__className__>,
         MongoHistoryRepository<__className__, __idType__> {
 
-    /*
-     * EXAMPLE REPOSITORY METHODS
-     *
-     * // Find by field using auto-generated query
-     * List<__className__> findAllBySomeFieldGreaterThan(Long value);
-     *
-     * // Custom query for fields that are explicit
-     * @Query("{ 'someField': ?0 }")
-     * List<__className__> findBySomeField(String value);
-     *
-     * // Custom aggregation
-     * @Aggregation(pipeline = {
-     *     "{ '$match': { 'someField': ?0 } }",
-     *     "{ '$group': { '_id': null, 'average': { '$avg': '$numericField' } } }"
-     * })
-     * List<Document> findAverageBySomeField(String value);
-     *
-     * // Simple efficient update without reading whole document
-     * @Query("{ 'id' : ?0 }")
-     * @Update("{ '$inc' : { 'counter' : ?1 } }")
-     * void incrementCounter(__idType__ id, int increment);
-     */
+
+/*
+ * =====================================================================
+ * SPRING DATA MONGODB REPOSITORY QUERY EXAMPLES
+ * =====================================================================
+ *
+ * These examples demonstrate the various ways to define queries in a
+ * Spring Data MongoDB repository interface. Replace the placeholder
+ * names with your actual field names and types.
+ *
+ * Terminology:
+ *   - FieldA, FieldB      : Top-level fields on the document
+ *   - SubObject            : A nested/embedded document
+ *   - SubObject.FieldA     : A field within the nested document
+ *
+ * ---------------------------------------------------------------------
+ * 1. AUTOMATICALLY DERIVED QUERIES
+ * ---------------------------------------------------------------------
+ * Spring Data parses the method name to generate the query.
+ *
+ *   // Find where a top-level numeric field exceeds a threshold
+ *   List<MyDocument> findByFieldAGreaterThan(Long value);
+ *
+ *   // Find by two fields within a nested subdocument (AND)
+ *   List<MyDocument> findBySubObjectFieldAAndSubObjectFieldB(
+ *       String fieldAValue, String fieldBValue);
+ *
+ * ---------------------------------------------------------------------
+ * 2. ANNOTATION-BASED AGGREGATION
+ * ---------------------------------------------------------------------
+ * Use @Aggregation for pipelines such as $group, $project, $unwind.
+ * Returns Document when the result shape differs from the entity.
+ *
+ *   @Aggregation(pipeline = {
+ *       "{ '$match':  { 'subObject.fieldA': ?0 } }",
+ *       "{ '$group':  { '_id': null, 'averageFieldB': { '$avg': '$subObject.fieldB' } } }"
+ *   })
+ *   List<Document> findAverageFieldBByFieldA(String fieldAValue);
+ *
+ * ---------------------------------------------------------------------
+ * 3. ANNOTATION-BASED UPDATE (WITHOUT FULL DOCUMENT READ/WRITE)
+ * ---------------------------------------------------------------------
+ * Combines @Query to match and @Update to modify in place.
+ * Efficient for targeted field updates; bypasses entity serialisation.
+ *
+ *   @Query("{ 'fieldA': ?0 }")
+ *   @Update("{ '$inc': { 'fieldB': ?1 } }")
+ *   void adjustFieldB(Long fieldAValue, int increment);
+ *
+ * ---------------------------------------------------------------------
+ * 4. @Query WITH MONGODB QUERY LANGUAGE (MQL)
+ * ---------------------------------------------------------------------
+ * Gives access to the full range of MQL operators while still
+ * binding method parameters positionally.
+ *
+ *   @Query("{ 'subObject.fieldA': ?0, 'subObject.fieldB': ?1 }")
+ *   List<MyDocument> findBySubObjectFieldAAndFieldB(
+ *       String fieldAValue, String fieldBValue);
+ *
+ * =====================================================================
+ */
 
     // Streaming version for large result sets
     Stream<__className__> findAllBy();