components/invalidation/public/invalidation.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_H_
   6 #define COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/memory/scoped_ptr.h"
  12 #include "base/memory/weak_ptr.h"
  13 #include "base/sequenced_task_runner.h"
  14 #include "base/values.h"
  15 #include "components/invalidation/public/ack_handle.h"
  16 #include "components/invalidation/public/invalidation_export.h"
  17 #include "google/cacheinvalidation/include/types.h"
  18
  19 namespace syncer {
  20
  21 class DroppedInvalidationTracker;
  22 class AckHandler;
  23
  24 // Represents a local invalidation, and is roughly analogous to
  25 // invalidation::Invalidation.  Unlike invalidation::Invalidation, this class
  26 // supports "local" ack-tracking and simple serialization to pref values.
  27 class INVALIDATION_EXPORT Invalidation {
  28  public:
  29   // Factory functions.
  30   static Invalidation Init(const invalidation::ObjectId& id,
  31                            int64 version,
  32                            const std::string& payload);
  33   static Invalidation InitUnknownVersion(const invalidation::ObjectId& id);
  34   static Invalidation InitFromDroppedInvalidation(const Invalidation& dropped);
  35   static scoped_ptr<Invalidation> InitFromValue(
  36       const base::DictionaryValue& value);
  37
  38   ~Invalidation();
  39
  40   // Compares two invalidations.  The comparison ignores ack-tracking state.
  41   bool Equals(const Invalidation& other) const;
  42
  43   invalidation::ObjectId object_id() const;
  44   bool is_unknown_version() const;
  45
  46   // Safe to call only if is_unknown_version() returns false.
  47   int64 version() const;
  48
  49   // Safe to call only if is_unknown_version() returns false.
  50   const std::string& payload() const;
  51
  52   const AckHandle& ack_handle() const;
  53
  54   // Sets the AckHandler to be used to track this Invalidation.
  55   //
  56   // This should be set by the class that generates the invalidation.  Clients
  57   // of the Invalidations API should not need to call this.
  58   //
  59   // Note that some sources of invalidations do not support ack tracking, and do
  60   // not set the ack_handler.  This will be hidden from users of this class.
  61   void SetAckHandler(
  62       base::WeakPtr<AckHandler> handler,
  63       scoped_refptr<base::SequencedTaskRunner> handler_task_runner);
  64
  65   // Returns whether or not this instance supports ack tracking.  This will
  66   // depend on whether or not the source of invaliadations supports
  67   // invalidations.
  68   //
  69   // Clients can safely ignore this flag.  They can assume that all
  70   // invalidations support ack tracking.  If they're wrong, then invalidations
  71   // will be less reliable, but their behavior will be no less correct.
  72   bool SupportsAcknowledgement() const;
  73
  74   // Acknowledges the receipt of this invalidation.
  75   //
  76   // Clients should call this on a received invalidation when they have fully
  77   // processed the invalidation and persisted the results to disk.  Once this
  78   // function is called, the invalidations system is under no obligation to
  79   // re-deliver this invalidation in the event of a crash or restart.
  80   void Acknowledge() const;
  81
  82   // Informs the ack tracker that this invalidation will not be serviced.
  83   //
  84   // If a client's buffer reaches its limit and it is forced to start dropping
  85   // invalidations, it should call this function before dropping its
  86   // invalidations in order to allow the ack tracker to drop the invalidation,
  87   // too.
  88   //
  89   // To indicate recovery from a drop event, the client should call
  90   // Acknowledge() on the most recently dropped inavlidation.
  91   void Drop();
  92
  93   scoped_ptr<base::DictionaryValue> ToValue() const;
  94   std::string ToString() const;
  95
  96  private:
  97   Invalidation(const invalidation::ObjectId& id,
  98                bool is_unknown_version,
  99                int64 version,
 100                const std::string& payload,
 101                AckHandle ack_handle);
 102
 103   // The ObjectId to which this invalidation belongs.
 104   invalidation::ObjectId id_;
 105
 106   // This flag is set to true if this is an unknown version invalidation.
 107   bool is_unknown_version_;
 108
 109   // The version number of this invalidation.  Should not be accessed if this is
 110   // an unkown version invalidation.
 111   int64 version_;
 112
 113   // The payaload associated with this invalidation.  Should not be accessed if
 114   // this is an unknown version invalidation.
 115   std::string payload_;
 116
 117   // A locally generated unique ID used to manage local acknowledgements.
 118   AckHandle ack_handle_;
 119
 120   // The acknowledgement tracking handler and its thread.
 121   base::WeakPtr<AckHandler> ack_handler_;
 122   scoped_refptr<base::SequencedTaskRunner> ack_handler_task_runner_;
 123 };
 124
 125 }  // namespace syncer
 126
 127 #endif  // COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_H_