Home | History | Annotate | Download | only in invalidation 
      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_INVALIDATION_H_
      6 #define COMPONENTS_INVALIDATION_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/ack_handle.h"
     16 #include "components/invalidation/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_INVALIDATION_H_
    128