Refactored api for consistent method conventions

ical4j-connector-api/src/main/java/org/ical4j/connector/CalendarCollection.java

@@ -36,12 +36,9 @@
 import net.fortuna.ical4j.model.component.VFreeBusy;
 import net.fortuna.ical4j.model.property.Uid;
 import net.fortuna.ical4j.util.Calendars;
-import org.ical4j.connector.local.LocalCalendarCollection;
-import org.slf4j.LoggerFactory;
 
 import java.time.Instant;
 import java.time.temporal.Temporal;
-import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -121,34 +118,44 @@ default Calendar getFreeBusy(Temporal start, Temporal end) {
      * @return the UID extracted from the specified calendar
      * @throws ObjectStoreException when an unexpected error occurs (implementation-specific)
      * @throws ConstraintViolationException if the specified calendar has no single unique identifier (UID)
+     * @deprecated use {@link ObjectCollection#add(Object)}
      */
-    Uid addCalendar(Calendar calendar) throws ObjectStoreException, ConstraintViolationException;
+    @Deprecated
+    default Uid addCalendar(Calendar calendar) throws ObjectStoreException, ConstraintViolationException {
+        return new Uid(add(calendar));
+    }
 
     /**
      * Returns the calendar object with the specified UID.
      * @param uid the UID associated with the returned calendar
      * @return a calendar object or null if no calendar with the specified UID exists
+     * @deprecated use {@link ObjectCollection#getAll(String...)}
      */
-    Calendar getCalendar(String uid) throws ObjectNotFoundException;
+    @Deprecated
+    default Calendar getCalendar(String uid) throws ObjectNotFoundException {
+        return get(uid).orElse(null);
+    }
 
+    /**
+     *
+     * @param uids
+     * @return
+     * @deprecated use {@link ObjectCollection#getAll(String...)}
+     */
+    @Deprecated
     default List<Calendar> getCalendars(String... uids) {
-        List<Calendar> calendars = new ArrayList<>();
-        for (String uid : uids) {
-            try {
-                calendars.add(getCalendar(uid));
-            } catch (ObjectNotFoundException e) {
-                LoggerFactory.getLogger(LocalCalendarCollection.class).warn("Calendar not found: " + uid);
-            }
-        }
-        return calendars;
+        return getAll(uids);
     }
 
     /**
      * @param uid the UID of the calendar to remove
      * @return the calendar that was successfully removed from the collection
-     * @throws ObjectStoreException where an unexpected error occurs
+     * @deprecated use {@link ObjectCollection#removeAll(String...)}
      */
-    Calendar removeCalendar(String uid) throws FailedOperationException, ObjectStoreException, ObjectNotFoundException;
+    @Deprecated
+    default Calendar removeCalendar(String uid) throws FailedOperationException {
+        return removeAll(uid).get(0);
+    }
 
     /**
      * Merges the specified calendar object with this collection. This is done by
@@ -163,7 +170,6 @@ default List<Calendar> getCalendars(String... uids) {
     /**
      * Exports the entire collection as a single calendar object.
      * @return a calendar object instance that contains all calendars in the collection
-     * @throws ObjectStoreException where an unexpected error occurs
      */
-    Calendar export() throws ObjectStoreException;
+    Calendar export();
 }

ical4j-connector-api/src/main/java/org/ical4j/connector/CardCollection.java

@@ -40,6 +40,7 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * $Id$
@@ -56,8 +57,12 @@ public interface CardCollection extends ObjectCollection<VCard> {
      * @return the UID extracted from the vCard
      * @throws ObjectStoreException where an unexpected error occurs
      * @throws ConstraintViolationException where the specified object is not valid
+     * @deprecated use {@link ObjectCollection#add(Object)}
      */
-    Uid addCard(VCard card) throws ObjectStoreException, ConstraintViolationException;
+    @Deprecated
+    default Uid addCard(VCard card) throws ObjectStoreException, ConstraintViolationException {
+        return new Uid(add(card));
+    }
 
     /**
      *
@@ -75,11 +80,37 @@ public interface CardCollection extends ObjectCollection<VCard> {
      * @return the card object that was removed from the collection
      * @throws ObjectNotFoundException
      * @throws FailedOperationException
+     * @deprecated use {@link ObjectCollection#removeAll(String...)}
+     *
      */
-    VCard removeCard(String uid) throws ObjectNotFoundException, FailedOperationException;
+    @Deprecated
+    default VCard removeCard(String uid) throws ObjectNotFoundException, FailedOperationException {
+        List<VCard> result = removeAll(uid);
+        return result.get(0);
+    }
 
-    VCard getCard(String uid) throws ObjectNotFoundException, FailedOperationException;
+    /**
+     *
+     * @param uid
+     * @return
+     * @throws ObjectNotFoundException
+     * @throws FailedOperationException
+     * @deprecated use {@link ObjectCollection#getAll(String...)}
+     */
+    @Deprecated
+    default VCard getCard(String uid) throws ObjectNotFoundException, FailedOperationException {
+        Optional<VCard> card = get(uid);
+        return card.orElse(null);
+    }
 
+    /**
+     *
+     * @param uids
+     * @return
+     * @throws FailedOperationException
+     * @deprecated use {@link ObjectCollection#getAll(String...)}
+     */
+    @Deprecated
     default VCardList getCards(String... uids) throws FailedOperationException {
         List<VCard> cards = new ArrayList<>();
         for (String uid : uids) {
@@ -95,7 +126,6 @@ default VCardList getCards(String... uids) throws FailedOperationException {
     /**
      * Exports the entire collection as an array of objects.
      * @return a vCard object array that contains all cards in the collection
-     * @throws ObjectStoreException where an unexpected error occurs
      */
-    VCard[] export() throws ObjectStoreException;
+    VCard[] export();
 }

ical4j-connector-api/src/main/java/org/ical4j/connector/ObjectCollection.java

@@ -34,7 +34,9 @@
 
 import net.fortuna.ical4j.filter.FilterExpression;
 
+import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * Implementors provide support for a persistent collection of objects. A collection will typically support
@@ -67,22 +69,65 @@ public interface ObjectCollection<T> extends ObjectCollectionListenerSupport<T>
      * Return a list of object identifiers in the collection
      * @return a list of object identifiers
      */
-    List<String> listObjectUids();
+    List<String> listObjectUIDs();
 
     /**
-     * Returns all objects stored in the collection.
-     * @return an array of collection objects
-     * @throws ObjectStoreException where an unexpected error occurs
+     * Returns a list of objects found with the specified UIDs. Where no UID is specified all objects
+     * are returned.
+     * @param uid zero or more
+     * @return a list of all found objects
      */
-    Iterable<T> getComponents() throws ObjectStoreException;
+    default List<T> getAll(String...uid) {
+        List<T> result = new ArrayList<>();
+        if (uid.length > 0) {
+            for (String u : uid) {
+                Optional<T> cal = get(u);
+                cal.ifPresent(result::add);
+            }
+        } else {
+            for (String u : listObjectUIDs()) {
+                Optional<T> cal = get(u);
+                cal.ifPresent(result::add);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Return a single object with the specified UID if it exists.
+     * @param uid
+     * @return an optional reference to an existing object
+     */
+    Optional<T> get(String uid);
+
+    /**
+     * Add a single object entity identified by an embedded UID value.
+     * @param object
+     * @return the UID discovered in the object entity
+     * @throws ObjectStoreException
+     */
+    String add(T object) throws ObjectStoreException;
+
+    /**
+     * Remove one or more objects found matching the specified UIDs. Where no UID is specified no
+     * action will be performed.
+     *
+     * Removal of all objects from a collection may be achieved as follows:
+     *
+     * <code>collection.removeAll(collection.listObjectUIDs().toArray(new String[0]))</code>
+     *
+     * @param uid
+     * @return a list of found objects that were removed
+     */
+    List<T> removeAll(String...uid) throws FailedOperationException;
 
     /**
      * Returns a subset of objects that satisfy the specified filter expression.
      * @param filterExpression an iCal4j component filter expression
      * @return an iterable of objects matching the specified filter expressions
      * @throws ObjectStoreException when an unexpected error occurs.
      */
-    default Iterable<T> query(FilterExpression filterExpression) throws ObjectStoreException {
+    default List<T> query(FilterExpression filterExpression) {
         throw new UnsupportedOperationException("Collection filtering not yet supported");
     }
 

ical4j-connector-api/src/main/java/org/ical4j/connector/local/AbstractLocalObjectCollection.java

@@ -16,9 +16,9 @@ public abstract class AbstractLocalObjectCollection<T> extends AbstractObjectCol
 
     public AbstractLocalObjectCollection(File root) throws IOException {
         this.root = Objects.requireNonNull(root);
-        if (!root.isDirectory()) {
-            throw new IllegalArgumentException("Root must be a directory");
-        }
+//        if (!root.isDirectory()) {
+//            throw new IllegalArgumentException("Root must be a directory");
+//        }
         File configRoot = new File(root, LocalCollectionConfiguration.DEFAULT_CONFIG_DIR);
         if ((configRoot.exists() && !configRoot.isDirectory()) ||
                 (!configRoot.exists() && !configRoot.mkdirs())) {