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