Simplify and document new content provider implementation

[lgpl/argeo-commons.git] / org.argeo.api.acr / src / org / argeo / api / acr / spi / ContentProvider.java

diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/spi/ContentProvider.java b/org.argeo.api.acr/src/org/argeo/api/acr/spi/ContentProvider.java
index 25b9be5c2081b924b7f08a0d4f0ce72b8a5e1559..56610ef4b097c917ceec3a155fc59e95b1f5893d 100644 (file)
--- a/org.argeo.api.acr/src/org/argeo/api/acr/spi/ContentProvider.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/spi/ContentProvider.java
@@ -6,16 +6,50 @@ import java.util.Spliterator;
 import javax.xml.namespace.NamespaceContext;
 
 import org.argeo.api.acr.Content;
+import org.argeo.api.acr.ContentNotFoundException;
 import org.argeo.api.acr.search.BasicSearch;
 
+/**
+ * A prover of {@link Content}, which can be mounted in a
+ * {@link ProvidedRepository}.
+ */
 public interface ContentProvider extends NamespaceContext {
 
-       ProvidedContent get(ProvidedSession session, String relativePath);
-
-       boolean exists(ProvidedSession session, String relativePath);
+       /**
+        * Return the content at this path, relative to the mount path.
+        * 
+        * @return the content at this relative path, never <code>null</code>
+        * @throws ContentNotFoundException if there is no content at this relative path
+        */
+       ProvidedContent get(ProvidedSession session, String relativePath) throws ContentNotFoundException;
+
+       /**
+        * Whether a content exist at his relative path. The default implementation call
+        * {@link #get(ProvidedSession, String)} and check whether a
+        * {@link ContentNotFoundException} is thrown or not. It should be overridden as
+        * soon as there is a mechanism to check existence before actually getting the
+        * content.
+        */
+       default boolean exists(ProvidedSession session, String relativePath) {
+               try {
+                       get(session, relativePath);
+                       return true;
+               } catch (ContentNotFoundException e) {
+                       return false;
+               }
+       }
 
+       /** The absolute path where this provider is mounted. */
        String getMountPath();
 
+       /**
+        * Search content within this provider. The default implementation throws an
+        * {@link UnsupportedOperationException}.
+        */
+       default Spliterator<Content> search(ProvidedSession session, BasicSearch search, String relPath) {
+               throw new UnsupportedOperationException();
+       }
+
        /*
         * NAMESPACE CONTEXT
         */
@@ -25,16 +59,4 @@ public interface ContentProvider extends NamespaceContext {
                return prefixes.hasNext() ? prefixes.next() : null;
        }
 
-       default Spliterator<Content> search(ProvidedSession session, BasicSearch search, String relPath) {
-               throw new UnsupportedOperationException();
-       }
-
-//     default ContentName parsePrefixedName(String nameWithPrefix) {
-//             return NamespaceUtils.parsePrefixedName(this, nameWithPrefix);
-//     }
-//
-//     default String toPrefixedName(QName name) {
-//             return NamespaceUtils.toPrefixedName(this, name);
-//     }
-
 }