1 // Copyright 2012 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 SYNC_INTERNAL_API_PUBLIC_BASE_INVALIDATION_H_ 6 #define SYNC_INTERNAL_API_PUBLIC_BASE_INVALIDATION_H_ 7 8 #include <string> 9 10 #include "base/basictypes.h" 11 #include "base/memory/scoped_ptr.h" 12 #include "base/values.h" 13 #include "google/cacheinvalidation/include/types.h" 14 #include "sync/base/sync_export.h" 15 #include "sync/internal_api/public/base/ack_handle.h" 16 #include "sync/internal_api/public/util/weak_handle.h" 17 18 namespace syncer { 19 20 class DroppedInvalidationTracker; 21 class AckHandler; 22 23 // Represents a local invalidation, and is roughly analogous to 24 // invalidation::Invalidation. Unlike invalidation::Invalidation, this class 25 // supports "local" ack-tracking and simple serialization to pref values. 26 class SYNC_EXPORT Invalidation { 27 public: 28 // Factory functions. 29 static Invalidation Init( 30 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 set_ack_handler(syncer::WeakHandle<AckHandler> ack_handler); 62 63 // Returns whether or not this instance supports ack tracking. This will 64 // depend on whether or not the source of invaliadations supports 65 // invalidations. 66 // 67 // Clients can safely ignore this flag. They can assume that all 68 // invalidations support ack tracking. If they're wrong, then invalidations 69 // will be less reliable, but their behavior will be no less correct. 70 bool SupportsAcknowledgement() const; 71 72 // Acknowledges the receipt of this invalidation. 73 // 74 // Clients should call this on a received invalidation when they have fully 75 // processed the invalidation and persisted the results to disk. Once this 76 // function is called, the invalidations system is under no obligation to 77 // re-deliver this invalidation in the event of a crash or restart. 78 void Acknowledge() const; 79 80 // Informs the ack tracker that this invalidation will not be serviced. 81 // 82 // If a client's buffer reaches its limit and it is forced to start dropping 83 // invalidations, it should call this function before dropping its 84 // invalidations in order to allow the ack tracker to drop the invalidation, 85 // too. 86 // 87 // The drop record will be tracked by the specified 88 // DroppedInvalidationTracker. The caller should hang on to this tracker. It 89 // will need to use it when it recovers from this drop event, or if it needs 90 // to record another drop event for the same ObjectID. Refer to the 91 // documentation of DroppedInvalidationTracker for more details. 92 void Drop(DroppedInvalidationTracker* tracker) const; 93 94 scoped_ptr<base::DictionaryValue> ToValue() const; 95 std::string ToString() const; 96 97 private: 98 Invalidation(const invalidation::ObjectId& id, 99 bool is_unknown_version, 100 int64 version, 101 const std::string& payload, 102 AckHandle ack_handle); 103 104 // The ObjectId to which this invalidation belongs. 105 invalidation::ObjectId id_; 106 107 // This flag is set to true if this is an unknown version invalidation. 108 bool is_unknown_version_; 109 110 // The version number of this invalidation. Should not be accessed if this is 111 // an unkown version invalidation. 112 int64 version_; 113 114 // The payaload associated with this invalidation. Should not be accessed if 115 // this is an unknown version invalidation. 116 std::string payload_; 117 118 // A locally generated unique ID used to manage local acknowledgements. 119 AckHandle ack_handle_; 120 syncer::WeakHandle<AckHandler> ack_handler_; 121 }; 122 123 } // namespace syncer 124 125 #endif // SYNC_INTERNAL_API_PUBLIC_BASE_INVALIDATION_H_ 126