Adds documentation and interfaces to AnnotationDataAccess

core/annotation/src/main/java/datawave/annotation/data/v1/AnnotationReader.java

@@ -0,0 +1,89 @@
+package datawave.annotation.data.v1;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Optional;
+
+import datawave.annotation.protobuf.v1.Annotation;
+
+/**
+ * Read-only contract for annotation data stores.
+ * <p>
+ * Implementations retrieve annotations by document identity ({@code shard}, {@code datatype}, and {@code uid}), annotation type, annotation id, and annotation
+ * source id. Methods return empty results when no matching data is visible to the implementation.
+ */
+public interface AnnotationReader {
+
+    /**
+     * Retrieves a single annotation for a document when both the annotation type and annotation id are known.
+     *
+     * @param shard
+     *            the shard for the annotated document
+     * @param datatype
+     *            the datatype for the annotated document
+     * @param uid
+     *            the unique id for the annotated document
+     * @param annotationType
+     *            the annotation type to search
+     * @param annotationUid
+     *            the annotation id to retrieve
+     * @return the matching annotation, or {@link Optional#empty()} when it is not found
+     */
+    Optional<Annotation> getAnnotation(String shard, String datatype, String uid, String annotationType, String annotationUid);
+
+    /**
+     * Retrieves a single annotation for a document by annotation id without requiring the caller to know the annotation type.
+     *
+     * @param shard
+     *            the shard for the annotated document
+     * @param datatype
+     *            the datatype for the annotated document
+     * @param uid
+     *            the unique id for the annotated document
+     * @param annotationId
+     *            the annotation id to retrieve
+     * @return the matching annotation, or {@link Optional#empty()} when it is not found
+     */
+    Optional<Annotation> getAnnotation(String shard, String datatype, String uid, String annotationId);
+
+    /**
+     * Lists the distinct annotation types currently available for a document.
+     *
+     * @param shard
+     *            the shard for the annotated document
+     * @param datatype
+     *            the datatype for the annotated document
+     * @param uid
+     *            the unique id for the annotated document
+     * @return the distinct annotation types visible for the document, never {@code null}
+     */
+    Collection<String> getAnnotationTypes(String shard, String datatype, String uid);
+
+    /**
+     * Retrieves all annotations currently available for a document.
+     *
+     * @param shard
+     *            the shard for the annotated document
+     * @param datatype
+     *            the datatype for the annotated document
+     * @param uid
+     *            the unique id for the annotated document
+     * @return the annotations visible for the document, never {@code null}
+     */
+    List<Annotation> getAnnotations(String shard, String datatype, String uid);
+
+    /**
+     * Retrieves all annotations of a specific type for a document.
+     *
+     * @param shard
+     *            the shard for the annotated document
+     * @param datatype
+     *            the datatype for the annotated document
+     * @param uid
+     *            the unique id for the annotated document
+     * @param annotationType
+     *            the annotation type to retrieve
+     * @return the matching annotations visible for the document and type, never {@code null}
+     */
+    List<Annotation> getAnnotationsForType(String shard, String datatype, String uid, String annotationType);
+}

core/annotation/src/main/java/datawave/annotation/data/v1/AnnotationSourceReader.java

@@ -0,0 +1,22 @@
+package datawave.annotation.data.v1;
+
+import java.util.Optional;
+
+import datawave.annotation.protobuf.v1.AnnotationSource;
+
+/**
+ * Read-only contract for annotation source data stores.
+ * <p>
+ * Implementations retrieve annotation sources by annotation source id. Methods return empty results when no matching data is visible to the implementation.
+ */
+public interface AnnotationSourceReader {
+
+    /**
+     * Retrieves the annotation source identified by its analytic hash.
+     *
+     * @param analyticHash
+     *            the analytic hash assigned to the source
+     * @return the matching annotation source, or {@link Optional#empty()} when it is not found
+     */
+    Optional<AnnotationSource> getAnnotationSource(String analyticHash);
+}

core/annotation/src/main/java/datawave/annotation/data/v1/AnnotationSourceWriter.java

@@ -0,0 +1,24 @@
+package datawave.annotation.data.v1;
+
+import java.util.Optional;
+
+import datawave.annotation.protobuf.v1.AnnotationSource;
+
+/**
+ * Write contract for annotation source data stores.
+ * <p>
+ * Implementations are responsible for validating writable annotation data, assigning store-managed identifiers when needed, and persisting annotation source
+ * changes.
+ */
+public interface AnnotationSourceWriter {
+
+    /**
+     * Adds a new annotation source.
+     *
+     * @param annotationSource
+     *            the annotation source to add; callers should not pre-populate store-managed ids
+     * @return the persisted annotation source, including any ids assigned by the writer
+     */
+    Optional<AnnotationSource> addAnnotationSource(AnnotationSource annotationSource);
+
+}

core/annotation/src/main/java/datawave/annotation/data/v1/AnnotationWriter.java

@@ -0,0 +1,50 @@
+package datawave.annotation.data.v1;
+
+import java.util.Optional;
+
+import datawave.annotation.protobuf.v1.Annotation;
+
+/**
+ * Write contract for annotation data stores.
+ * <p>
+ * Implementations are responsible for validating writable annotation data, assigning store-managed identifiers when needed, and persisting annotation changes.
+ */
+public interface AnnotationWriter {
+
+    /**
+     * Adds a new annotation.
+     *
+     * @param annotation
+     *            the annotation to add; callers should not pre-populate store-managed annotation or segment ids
+     * @return the persisted annotation, including any ids assigned by the writer
+     */
+    Optional<Annotation> addAnnotation(Annotation annotation);
+
+    /**
+     * Creates an update for an existing annotation.
+     * <p>
+     * Implementations may preserve previous annotation versions and link the new annotation back to {@code targetAnnotationId} instead of overwriting the
+     * existing annotation in place.
+     *
+     * @param targetAnnotationId
+     *            the id of the existing annotation being updated
+     * @param annotation
+     *            the updated annotation data to persist
+     * @return the persisted update annotation, including any ids assigned by the writer
+     */
+    Optional<Annotation> updateAnnotation(String targetAnnotationId, Annotation annotation);
+
+    /**
+     * Deletes all stored entries for a document annotation id.
+     *
+     * @param shard
+     *            the shard for the annotated document
+     * @param datatype
+     *            the datatype for the annotated document
+     * @param uid
+     *            the unique id for the annotated document
+     * @param annotationId
+     *            the annotation id to delete
+     */
+    void deleteAnnotation(String shard, String datatype, String uid, String annotationId);
+}

core/annotation/src/test/java/datawave/annotation/data/v1/AnnotationDataAccessTest.java

@@ -383,7 +383,7 @@ public void testDeleteAnnotation() {
         assertTrue(existingAnnotation.isPresent());
 
         // Delete the annotation
-        dao.delete(shard, dataType, uid, annotationIdToDelete);
+        dao.deleteAnnotation(shard, dataType, uid, annotationIdToDelete);
 
         // Verify the annotation no longer exists
         Optional<Annotation> deletedAnnotation = dao.getAnnotation(shard, dataType, uid, annotationIdToDelete);
@@ -401,7 +401,7 @@ public void testDeleteAnnotationNotFound() {
         // This should not throw an exception (delete handles empty iterator gracefully)
         // Note: if delete returns null mutation, writer.addMutation is called with null which throws
         try {
-            dao.delete(shard, dataType, uid, annotationId);
+            dao.deleteAnnotation(shard, dataType, uid, annotationId);
             // If we get here, delete handled empty results correctly
         } catch (IllegalArgumentException e) {
             // This is expected if mutationAdapter returns null and writer.addMutation is called with null