COH-23078: Document Repository API features

[git-p4: depot-paths = "//dev/coherence-ce/main/": change = 85784]

prj/coherence-core/src/main/java/com/oracle/coherence/repository/AbstractRepository.java

@@ -74,6 +74,7 @@ public abstract class AbstractRepository<ID, T>
     {
     // ---- abstract methods ------------------------------------------------
 
+    // # tag::abstract[]
     /**
      * Return the {@link NamedMap} that is used as the underlying entity store.
      *
@@ -96,6 +97,7 @@ public abstract class AbstractRepository<ID, T>
      * @return the type of entities in this repository
      */
     protected abstract Class<? extends T> getEntityType();
+    // # end::abstract[]
 
     // ---- CRUD support ----------------------------------------------------
 
@@ -116,7 +118,7 @@ public T findById(ID id)
      *
      * @return all entities in this repository
      */
-    public Collection<? extends T> findAll()
+    public Collection<T> findAll()
         {
         return getMapInternal().values();
         }

prj/coherence-core/src/main/java/com/oracle/coherence/repository/EntityFactory.java

@@ -17,6 +17,7 @@
  * @author Aleks Seovic  2021.02.01
  * @since 21.06
  */
+// tag::doc[]
 @FunctionalInterface
 public interface EntityFactory<ID, T>
         extends Serializable
@@ -30,3 +31,4 @@ public interface EntityFactory<ID, T>
      */
     T create(ID id);
     }
+// end::doc[]

prj/coherence-core/src/test/java/com/oracle/coherence/repository/AbstractRepositoryTest.java

@@ -876,12 +876,36 @@ public void testGlobalListener() throws InterruptedException
         assertThat(cRemove.get(), is(5));
         }
 
-
     // ---- helpers ---------------------------------------------------------
 
     @SafeVarargs
     private static <T> Set<T> setOf(T... values)
         {
         return Stream.of(values).collect(Collectors.toSet());
         }
+
+    /**
+     * Not used directly, but references from the documentation
+     * so we want to make sure it compiles.
+     */
+    // tag::listener[]
+    public static class PeopleListener
+            implements PeopleRepository.Listener<Person>
+        {
+        public void onInserted(Person personNew)
+            {
+            // handle INSERT event
+            }
+
+        public void onUpdated(Person personOld, Person personNew)
+            {
+            // handle UPDATE event
+            }
+
+        public void onRemoved(Person personOld)
+            {
+            // handle REMOVE event
+            }
+        }
+    // end::listener[]
     }

prj/coherence-core/src/test/java/com/oracle/coherence/repository/PeopleRepository.java

@@ -17,6 +17,7 @@
  * @author Aleks Seovic  2021.02.12
  */
 @Accelerated
+// tag::doc[]
 public class PeopleRepository
         extends AbstractRepository<String, Person>
     {
@@ -27,18 +28,19 @@ public PeopleRepository(NamedMap<String, Person> people)
         this.people = people;
         }
 
-    protected NamedMap<String, Person> getMap()
+    protected NamedMap<String, Person> getMap()            // <1>
         {
         return people;
         }
 
-    protected String getId(Person entity)
+    protected String getId(Person person)                  // <2>
         {
-        return entity.getSsn();
+        return person.getSsn();
         }
 
-    protected Class<? extends Person> getEntityType()
+    protected Class<? extends Person> getEntityType()      // <3>
         {
         return Person.class;
         }
     }
+// end::doc[]

prj/docs/core/01_overview.adoc

@@ -37,5 +37,12 @@ Recover data from Coherence's Persistence mechanism in parallel.
 Implement versioned data classes that can evolve over time.
 --
 
+[CARD]
+.Repository API
+[icon=fa-sitemap,link=docs/core/05_repository.adoc]
+--
+Higher level, DDD-friendly data access API.
+--
+
 ====