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
18namespace syncer {
19
20class DroppedInvalidationTracker;
21class 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.
26class 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