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