Merge pull request #164 from morganchen12/joins

Support for joins

Author: morganchen12

FirebaseDatabaseUI/FirebaseArray.h

@@ -24,7 +24,7 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-@protocol FIRDataObservable
+@protocol FIRDataObservable <NSObject>
 @required
 
 - (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType
@@ -33,6 +33,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (void)removeObserverWithHandle:(FIRDatabaseHandle)handle;
 
+- (id<FIRDataObservable>)child:(NSString *)path;
+
 @end
 
 @interface FIRDatabaseQuery (FIRDataObservable) <FIRDataObservable>
@@ -71,10 +73,25 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Initalizes FirebaseArray with a Firebase query (FIRDatabaseQuery) or database reference
  * (FIRDatabaseReference).
- * @param query A query or Firebase database reference
+ * @param query    A query or Firebase database reference
+ * @param delegate An object conforming to FirebaseArrayDelegate that should receive delegate messages.
+ * @return A FirebaseArray instance
+ */
+- (instancetype)initWithQuery:(id<FIRDataObservable>)query
+                     delegate:(nullable id<FirebaseArrayDelegate>)delegate NS_DESIGNATED_INITIALIZER;
+
+/**
+ * Initalizes FirebaseArray with a Firebase query (FIRDatabaseQuery) or database reference
+ * (FIRDatabaseReference).
+ * @param query    A query or Firebase database reference
  * @return A FirebaseArray instance
  */
-- (instancetype)initWithQuery:(id<FIRDataObservable>)query NS_DESIGNATED_INITIALIZER;
+- (instancetype)initWithQuery:(id<FIRDataObservable>)query;
+
+/**
+ * See `initWithQuery:`
+ */
++ (instancetype)arrayWithQuery:(id<FIRDataObservable>)query;
 
 - (instancetype)init NS_UNAVAILABLE;
 

FirebaseDatabaseUI/FirebaseArray.m

@@ -39,19 +39,27 @@ @implementation FirebaseArray
 
 #pragma mark - Initializer methods
 
-- (instancetype)initWithQuery:(FIRDatabaseQuery *)query {
+- (instancetype)initWithQuery:(FIRDatabaseQuery *)query delegate:(id<FirebaseArrayDelegate>)delegate {
   NSParameterAssert(query != nil);
   self = [super init];
   if (self) {
     self.snapshots = [NSMutableArray array];
     self.query = query;
     self.handles = [NSMutableSet setWithCapacity:4];
-
+    self.delegate = delegate;
     [self initListeners];
   }
   return self;
 }
 
+- (instancetype)initWithQuery:(id<FIRDataObservable>)query {
+  return [self initWithQuery:query delegate:nil];
+}
+
++ (instancetype)arrayWithQuery:(id<FIRDataObservable>)query {
+  return [[self alloc] initWithQuery:query];
+}
+
 #pragma mark - Memory management methods
 
 - (void)dealloc {
@@ -130,6 +138,7 @@ - (void)initListeners {
                 toIndex = prevIndex + 1;
             }
         }
+
         [self.snapshots insertObject:snapshot atIndex:toIndex];
 
         if ([self.delegate respondsToSelector:@selector(array:didMoveObject:fromIndex:toIndex:)]) {

FirebaseDatabaseUI/FirebaseArrayDelegate.h

@@ -22,52 +22,43 @@
 
 /**
  * A protocol to allow instances of FirebaseArray to raise events through a
- * delegate. Raises all
- * Firebase events except FIRDataEventTypeValue.
+ * delegate. Raises all Firebase events except @c FIRDataEventTypeValue.
  */
 @protocol FirebaseArrayDelegate<NSObject>
 
 @optional
 
 /**
  * Delegate method which is called whenever an object is added to a
- * FirebaseArray. On a
- * FirebaseArray synchronized to a Firebase reference, this corresponds to an
- * [FIRDataEventTypeChildAdded](https://www.firebase.com/docs/ios/guide/retrieving-data.html#section-event-types)
- * event being raised.
+ * FirebaseArray. On a FirebaseArray synchronized to a Firebase reference, 
+ * this corresponds to a @c FIRDataEventTypeChildAdded event being raised.
  * @param object The object added to the FirebaseArray
  * @param index The index the child was added at
  */
 - (void)array:(FirebaseArray *)array didAddObject:(id)object atIndex:(NSUInteger)index;
 
 /**
- * Delegate method which is called whenever an object is chinged in a
- * FirebaseArray. On a
- * FirebaseArray synchronized to a Firebase reference, this corresponds to an
- * [FIRDataEventTypeChildChanged](https://www.firebase.com/docs/ios/guide/retrieving-data.html#section-event-types)
- * event being raised.
+ * Delegate method which is called whenever an object is changed in a
+ * FirebaseArray. On a FirebaseArray synchronized to a Firebase reference, 
+ * this corresponds to a @c FIRDataEventTypeChildChanged event being raised.
  * @param object The object that changed in the FirebaseArray
  * @param index The index the child was changed at
  */
 - (void)array:(FirebaseArray *)array didChangeObject:(id)object atIndex:(NSUInteger)index;
 
 /**
  * Delegate method which is called whenever an object is removed from a
- * FirebaseArray. On a
- * FirebaseArray synchronized to a Firebase reference, this corresponds to an
- * [FIRDataEventTypeChildRemoved](https://www.firebase.com/docs/ios/guide/retrieving-data.html#section-event-types)
- * event being raised.
+ * FirebaseArray. On a FirebaseArray synchronized to a Firebase reference, 
+ * this corresponds to a @c FIRDataEventTypeChildRemoved event being raised.
  * @param object The object removed from the FirebaseArray
  * @param index The index the child was removed at
  */
 - (void)array:(FirebaseArray *)array didRemoveObject:(id)object atIndex:(NSUInteger)index;
 
 /**
  * Delegate method which is called whenever an object is moved within a
- * FirebaseArray. On a
- * FirebaseArray synchronized to a Firebase reference, this corresponds to an
- * [FIRDataEventTypeChildMoved](https://www.firebase.com/docs/ios/guide/retrieving-data.html#section-event-types)
- * event being raised.
+ * FirebaseArray. On a FirebaseArray synchronized to a Firebase reference, 
+ * this corresponds to a @c FIRDataEventTypeChildMoved event being raised.
  * @param object The object that has moved locations in the FirebaseArray
  * @param fromIndex The index the child is being moved from
  * @param toIndex The index the child is being moved to

FirebaseDatabaseUI/FirebaseDatabaseUI.h

@@ -27,5 +27,6 @@ FOUNDATION_EXPORT const unsigned char FirebaseDatabaseUIVersionString[];
 #import <FirebaseDatabaseUI/FirebaseCollectionViewDataSource.h>
 #import <FirebaseDatabaseUI/FirebaseDataSource.h>
 #import <FirebaseDatabaseUI/FirebaseTableViewDataSource.h>
-
-
+#import <FirebaseDatabaseUI/FirebaseIndexArray.h>
+#import <FirebaseDatabaseUI/FirebaseIndexTableViewDataSource.h>
+#import <FirebaseDatabaseUI/FirebaseIndexCollectionViewDataSource.h>

FirebaseDatabaseUI/FirebaseIndexArray.h

@@ -0,0 +1,175 @@
+// clang-format off
+
+//
+//  Copyright (c) 2016 Google Inc.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+// clang-format on
+
+#import "FirebaseArray.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class FirebaseIndexArray;
+
+/**
+ * A protocol to allow instances of FirebaseIndexArray to raise events through a
+ * delegate. Raises all Firebase events except @c FIRDataEventTypeValue.
+ */
+@protocol FirebaseIndexArrayDelegate <NSObject>
+
+@optional
+
+/**
+ * Delegate method called when the database reference at an index has 
+ * finished loading its contents.
+ * @param array The array containing the reference.
+ * @param ref The reference that was loaded.
+ * @param object The database reference's contents.
+ * @param index The index of the reference that was loaded.
+ */
+- (void)array:(FirebaseIndexArray *)array
+    reference:(FIRDatabaseReference *)ref
+didLoadObject:(FIRDataSnapshot *)object
+      atIndex:(NSUInteger)index;
+
+/**
+ * Delegate method called when the database reference at an index has 
+ * failed to load contents.
+ * @param array The array containing the reference.
+ * @param ref The reference that failed to load.
+ * @param index The index in the array of the reference that failed to load.
+ * @param error The error that occurred.
+ */
+- (void)array:(FirebaseIndexArray *)array
+    reference:(FIRDatabaseReference *)ref
+      atIndex:(NSUInteger)index
+didFailLoadWithError:(NSError *)error;
+
+/**
+ * Delegate method which is called whenever an object is added to a
+ * FirebaseArray. On a FirebaseArray synchronized to a Firebase reference, 
+ * this corresponds to a @c FIRDataEventTypeChildAdded event being raised.
+ * @param ref The database reference added to the array
+ * @param index The index the reference was added at
+ */
+- (void)array:(FirebaseIndexArray *)array didAddReference:(FIRDatabaseReference *)ref atIndex:(NSUInteger)index;
+
+/**
+ * Delegate method which is called whenever an object is changed in a
+ * FirebaseArray. On a FirebaseArray synchronized to a Firebase reference, 
+ * this corresponds to a @c FIRDataEventTypeChildChanged event being raised.
+ * @param ref The database reference that changed in the array
+ * @param index The index the reference was changed at
+ */
+- (void)array:(FirebaseIndexArray *)array didChangeReference:(FIRDatabaseReference *)ref atIndex:(NSUInteger)index;
+
+/**
+ * Delegate method which is called whenever an object is removed from a
+ * FirebaseArray. On a FirebaseArray synchronized to a Firebase reference, 
+ * this corresponds to a @c FIRDataEventTypeChildRemoved event being raised.
+ * @param ref The database reference removed from the array
+ * @param index The index the reference was removed at
+ */
+- (void)array:(FirebaseIndexArray *)array didRemoveReference:(FIRDatabaseReference *)ref atIndex:(NSUInteger)index;
+
+/**
+ * Delegate method which is called whenever an object is moved within a
+ * FirebaseArray. On a FirebaseArray synchronized to a Firebase reference, 
+ * this corresponds to a @c FIRDataEventTypeChildMoved event being raised.
+ * @param ref The database reference that has moved locations
+ * @param fromIndex The index the reference is being moved from
+ * @param toIndex The index the reference is being moved to
+ */
+- (void)array:(FirebaseIndexArray *)array didMoveReference:(FIRDatabaseReference *)ref fromIndex:(NSUInteger)fromIndex toIndex:(NSUInteger)toIndex;
+
+/**
+ * Delegate method which is called whenever the backing query is canceled. This error is fatal
+ * and the index array will become unusable afterward, so please handle it appropriately
+ * (i.e. by displaying a modal error explaining why there's no content).
+ * @param error the error that was raised
+ */
+- (void)array:(FirebaseIndexArray *)array queryCancelledWithError:(NSError *)error;
+
+@end
+
+/**
+ * A FirebaseIndexArray instance uses a query's contents to query children of
+ * a separate database reference, which is useful for displaying an indexed list
+ * of data as described in https://firebase.google.com/docs/database/ios/structure-data
+ */
+@interface FirebaseIndexArray : NSObject
+
+/**
+ * An immutable copy of the loaded contents in the array. Returns an
+ * empty array if no contents have loaded yet.
+ */
+@property(nonatomic, copy, readonly) NSArray<FIRDataSnapshot *> *items;
+
+/**
+ * The delegate that this array should forward events to.
+ */
+@property(nonatomic, weak) id<FirebaseIndexArrayDelegate> delegate;
+
+/**
+ * Returns the number of items in the array.
+ */
+@property(nonatomic, readonly) NSUInteger count;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+/**
+ * Initializes a FirebaseIndexArray with an index query and a data query.
+ * The array expects the keys of the children of the index query to match exactly children
+ * of the data query.
+ * @param index A Firebase database query whose childrens' keys are all children 
+ *   of the data query.
+ * @param data  A Firebase database reference whose children will be fetched and used
+ *   to populate the array's contents according to the index query.
+ * @param delegate The delegate that events should be forwarded to.
+ */
+- (instancetype)initWithIndex:(id<FIRDataObservable>)index
+                         data:(id<FIRDataObservable>)data
+                     delegate:(nullable id<FirebaseIndexArrayDelegate>)delegate NS_DESIGNATED_INITIALIZER;
+
+/**
+ * Initializes a FirebaseIndexArray with an index query and a data query.
+ * The array expects the keys of the children of the index query to be children
+ * of the data query.
+ * @param index A Firebase database query whose childrens' keys are all children
+ *   of the data query.
+ * @param data  A Firebase database reference whose children will be fetched and used
+ *   to populate the array's contents according to the index query.
+ */
+- (instancetype)initWithIndex:(id<FIRDataObservable>)index
+                         data:(id<FIRDataObservable>)data;
+
+/**
+ * Returns the snapshot at the given index, if it has loaded.
+ * Raises a fatal error if the index is out of bounds.
+ * @param index The index of the requested snapshot.
+ * @return A snapshot, or nil if one has not yet been loaded.
+ */
+- (nullable FIRDataSnapshot *)objectAtIndex:(NSUInteger)index;
+
+/**
+ * Removes all observers from all queries managed by this array and renders this array
+ * unusable.
+ */
+- (void)invalidate;
+
+@end
+
+NS_ASSUME_NONNULL_END