Firestore project: Import of API interfaces. (#1938)

zxu123 · web-flow · commit 55acc03aed36 · 2018-10-12T16:54:48.000-04:00
- 216873604 fix a style (clang-format) for GitHub sync. by zxu &lt;zxu&gt;
  - 216859139 Implement the header of SetOptions, which will be of non-... by zxu &lt;zxu&gt;
  - 216760495 Implement the JNI part of FieldPath: by zxu &lt;zxu&gt;
  - 216580771 Implement the header of FieldPath, which will be of non-w... by zxu &lt;zxu&gt;
  - 215276303 Implement the JNI call part of Transaction Android wrapper. by zxu &lt;zxu&gt;
  - 215271876 Implement the header and common part of Transaction Andro... by zxu &lt;zxu&gt;
  - 214817327 Implement the JNI call part of WriteBatch Android wrapper. by zxu &lt;zxu&gt;
  - 214809271 Implement the header and common part of WriteBatch Androi... by zxu &lt;zxu&gt;
  - 214660417 Implement the JNI call part of the DocumentChange Android... by zxu &lt;zxu&gt;
  - 214648904 Implement the header and common part of DocumentChange An... by zxu &lt;zxu&gt;

ORIGINAL_AUTHOR=Firebase &lt;firebase-noreply&gt;
PiperOrigin-RevId: 216873604
diff --git a/Firestore/core/include/firebase/firestore/document_change.h b/Firestore/core/include/firebase/firestore/document_change.h
@@ -17,16 +17,88 @@
 #ifndef FIRESTORE_CORE_INCLUDE_FIREBASE_FIRESTORE_DOCUMENT_CHANGE_H_
 #define FIRESTORE_CORE_INCLUDE_FIREBASE_FIRESTORE_DOCUMENT_CHANGE_H_
 
+#include <cstddef>
+
+#include "firebase/firestore/document_snapshot.h"
+
 namespace firebase {
 namespace firestore {
 
+class DocumentChangeInternal;
+
 /**
  * A DocumentChange represents a change to the documents matching a query. It
  * contains the document affected and the type of change that occurred (added,
  * modified, or removed).
  */
-// TODO(zxu123): add more methods to complete the class and make it useful.
-class DocumentChange {};
+class DocumentChange {
+ public:
+  enum class Type {
+    kAdded,
+    kModified,
+    kRemoved,
+  };
+
+  static const constexpr std::size_t npos = static_cast<std::size_t>(-1);
+
+  /**
+   * @brief Default constructor. This creates an invalid DocumentChange.
+   * Attempting to perform any operations on this instance will fail (and cause
+   * a crash) unless a valid DocumentChange has been assigned to it.
+   */
+  DocumentChange();
+
+  /** @brief Copy constructor. */
+  DocumentChange(const DocumentChange& value);
+
+  /** @brief Move constructor. */
+  DocumentChange(DocumentChange&& value);
+
+  virtual ~DocumentChange();
+
+  /** @brief Copy assignment operator. */
+  DocumentChange& operator=(const DocumentChange& value);
+
+  /** @brief Move assignment operator. */
+  DocumentChange& operator=(DocumentChange&& value);
+
+  /**
+   * Returns the type of change that occurred (added, modified, or removed).
+   */
+  virtual Type type() const;
+
+  /**
+   * @brief The document affected by this change.
+   *
+   * Returns the newly added or modified document if this DocumentChange is for
+   * an updated document. Returns the deleted document if this document change
+   * represents a removal.
+   */
+  virtual DocumentSnapshot document() const;
+
+  /**
+   * The index of the changed document in the result set immediately prior to
+   * this DocumentChange (i.e. supposing that all prior DocumentChange objects
+   * have been applied). Returns npos for 'added' events.
+   */
+  virtual std::size_t old_index() const;
+
+  /**
+   * The index of the changed document in the result set immediately after this
+   * DocumentChange (i.e. supposing that all prior DocumentChange objects and
+   * the current DocumentChange object have been applied). Returns npos for
+   * 'removed' events.
+   */
+  virtual std::size_t new_index() const;
+
+ protected:
+  explicit DocumentChange(DocumentChangeInternal* internal);
+
+ private:
+  friend class FirestoreInternal;
+
+  DocumentChangeInternal* internal_ = nullptr;
+};
 
 }  // namespace firestore
 }  // namespace firebase
diff --git a/Firestore/core/include/firebase/firestore/document_reference.h b/Firestore/core/include/firebase/firestore/document_reference.h
@@ -387,6 +387,8 @@ class DocumentReference {
   friend class DocumentSnapshotInternal;
   friend class FieldValueInternal;
   friend class FirestoreInternal;
+  friend class TransactionInternal;
+  friend class WriteBatchInternal;
 
   // TODO(zxu123): investigate possibility to use std::unique_ptr or
   // firebase::UniquePtr.
diff --git a/Firestore/core/include/firebase/firestore/document_snapshot.h b/Firestore/core/include/firebase/firestore/document_snapshot.h
@@ -223,9 +223,11 @@ class DocumentSnapshot {
   explicit DocumentSnapshot(DocumentSnapshotInternal* internal);
 
  private:
+  friend class DocumentChangeInternal;
   friend class EventListenerInternal;
   friend class FirestoreInternal;
   friend class QueryInternal;
+  friend class TransactionInternal;
   friend class Wrapper;
 
   DocumentSnapshotInternal* internal_ = nullptr;
diff --git a/Firestore/core/include/firebase/firestore/field_path.h b/Firestore/core/include/firebase/firestore/field_path.h
@@ -19,19 +19,71 @@
 
 #include <string>
 
+#if !defined(_STLPORT_VERSION)
+#include <initializer_list>
+#endif  // !defined(_STLPORT_VERSION)
+
 namespace firebase {
 namespace firestore {
 
-class FieldPathInternal;
+namespace model {
+class FieldPath;
+}  // namespace model
 
 /**
  * A FieldPath refers to a field in a document. The path may consist of a single
  * field name (referring to a top level field in the document), or a list of
  * field names (referring to a nested field in the document).
  */
-// TODO(zxu123): add more methods to complete the class and make it useful.
 class FieldPath {
- private:
+ public:
+  using FieldPathInternal = ::firebase::firestore::model::FieldPath;
+
+  /**
+   * Default constructor. This creates an invalid FieldPath. Attempting to
+   * perform any operations on this path will fail (and cause a crash) unless a
+   * valid FieldPath has been assigned to it.
+   */
+  FieldPath();
+
+#if !defined(_STLPORT_VERSION)
+  /**
+   * Creates a FieldPath from the provided field names. If more than one field
+   * name is provided, the path will point to a nested field in a document.
+   *
+   * @param field_names A list of field names.
+   */
+  FieldPath(std::initializer_list<std::string> field_names);
+#endif  // !defined(_STLPORT_VERSION)
+
+  /**
+   * Copy constructor.
+   */
+  FieldPath(const FieldPath& path);
+
+  /**
+   * Move constructor.
+   */
+  FieldPath(FieldPath&& path);
+
+  virtual ~FieldPath();
+
+  /**
+   * Copy assignment operator.
+   */
+  FieldPath& operator=(const FieldPath& path);
+
+  /**
+   * Move assignment operator.
+   */
+  FieldPath& operator=(FieldPath&& path);
+
+  /**
+   * A special sentinel FieldPath to refer to the ID of a document. It can be
+   * used in queries to sort or filter by the document ID.
+   */
+  static FieldPath DocumentId();
+
   /**
    * Parses a field path string into a FieldPath, treating dots as separators.
    *
@@ -40,8 +92,25 @@ class FieldPath {
    */
   static FieldPath FromDotSeparatedString(const std::string& path);
 
+  /**
+   * Returns a string representation of this FieldPath.
+   */
+  virtual std::string ToString() const;
+
+ protected:
+  explicit FieldPath(FieldPathInternal* internal);
+
+ private:
+  friend bool operator==(const FieldPath& lhs, const FieldPath& rhs);
+  friend bool operator!=(const FieldPath& lhs, const FieldPath& rhs);
+  friend bool operator<(const FieldPath& lhs, const FieldPath& rhs);
+  friend bool operator>(const FieldPath& lhs, const FieldPath& rhs);
+  friend bool operator<=(const FieldPath& lhs, const FieldPath& rhs);
+  friend bool operator>=(const FieldPath& lhs, const FieldPath& rhs);
+
   friend class Query;
   friend class QueryInternal;
+  friend class FieldPathConverter;
 
   FieldPathInternal* internal_ = nullptr;
 };
diff --git a/Firestore/core/include/firebase/firestore/set_options.h b/Firestore/core/include/firebase/firestore/set_options.h
@@ -17,6 +17,11 @@
 #ifndef FIRESTORE_CORE_INCLUDE_FIREBASE_FIRESTORE_SET_OPTIONS_H_
 #define FIRESTORE_CORE_INCLUDE_FIREBASE_FIRESTORE_SET_OPTIONS_H_
 
+#include <string>
+#include <vector>
+
+#include "firebase/firestore/field_path.h"
+
 namespace firebase {
 namespace firestore {
 
@@ -27,11 +32,74 @@ namespace firestore {
  * granular merges instead of overwriting the target documents in their
  * entirety.
  */
-// TODO(zxu123): add more methods to complete the class and make it useful.
 class SetOptions {
  public:
-  SetOptions() {
-  }
+  enum class Type {
+    kOverwrite,
+    kMergeAll,
+    kMergeSpecific,
+  };
+
+  /**
+   * Default constructor. This creates an invalid SetOptions. Attempting
+   * to perform any operations on this instance will fail (and cause a crash)
+   * unless a valid SetOptions has been assigned to it.
+   */
+  SetOptions() = default;
+
+  /** Copy constructor. */
+  SetOptions(const SetOptions& value) = default;
+
+  /** Move constructor. */
+  SetOptions(SetOptions&& value) = default;
+
+  virtual ~SetOptions();
+
+  /** Copy assignment operator. */
+  SetOptions& operator=(const SetOptions& value) = default;
+
+  /** Move assignment operator. */
+  SetOptions& operator=(SetOptions&& value) = default;
+
+  /**
+   * Returns an instance that can be used to change the behavior of set() calls
+   * to only replace the values specified in its data argument. Fields omitted
+   * from the set() call will remain untouched.
+   */
+  static SetOptions Merge();
+
+  /**
+   * Returns an instance that can be used to change the behavior of set() calls
+   * to only replace the fields under fieldPaths. Any field that is not
+   * specified in fieldPaths is ignored and remains untouched.
+   *
+   * It is an error to pass a SetOptions object to a set() call that is missing
+   * a value for any of the fields specified here.
+   *
+   * @param fields The list of fields to merge. Fields can contain dots to
+   * reference nested fields within the document.
+   */
+  static SetOptions MergeField(const std::vector<std::string>& fields);
+
+  /**
+   * Returns an instance that can be used to change the behavior of set() calls
+   * to only replace the fields under fieldPaths. Any field that is not
+   * specified in fieldPaths is ignored and remains untouched.
+   *
+   * It is an error to pass a SetOptions object to a set() call that is missing
+   * a value for any of the fields specified here in its to data argument.
+   *
+   * @param fields The list of fields to merge.
+   */
+  static SetOptions MergeField(const std::vector<FieldPath>& fields);
+
+ private:
+  friend class SetOptionsInternal;
+
+  SetOptions(Type type, std::vector<FieldPath> fields);
+
+  Type type_ = Type::kOverwrite;
+  std::vector<FieldPath> fields_;
 };
 
 }  // namespace firestore
diff --git a/Firestore/core/include/firebase/firestore/transaction.h b/Firestore/core/include/firebase/firestore/transaction.h
diff --git a/Firestore/core/include/firebase/firestore/write_batch.h b/Firestore/core/include/firebase/firestore/write_batch.h
