sync_session.h revision 7d4cd473f85ac64c3747c96c277f9e506a0d2246 
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// A class representing an attempt to synchronize the local syncable data
6// store with a sync server. A SyncSession instance is passed as a stateful
7// bundle to and from various SyncerCommands with the goal of converging the
8// client view of data with that of the server. The commands twiddle with
9// session status in response to events and hiccups along the way, set and
10// query session progress with regards to conflict resolution and applying
11// server updates, and access the SyncSessionContext for the current session
12// via SyncSession instances.
13
14#ifndef SYNC_SESSIONS_SYNC_SESSION_H_
15#define SYNC_SESSIONS_SYNC_SESSION_H_
16
17#include <map>
18#include <set>
19#include <string>
20#include <utility>
21#include <vector>
22
23#include "base/basictypes.h"
24#include "base/memory/scoped_ptr.h"
25#include "base/time.h"
26#include "sync/base/sync_export.h"
27#include "sync/internal_api/public/base/model_type.h"
28#include "sync/internal_api/public/engine/model_safe_worker.h"
29#include "sync/internal_api/public/sessions/sync_session_snapshot.h"
30#include "sync/sessions/ordered_commit_set.h"
31#include "sync/sessions/status_controller.h"
32#include "sync/sessions/sync_session_context.h"
33
34namespace syncer {
35class ModelSafeWorker;
36
37namespace sessions {
38
39class NudgeTracker;
40
41class SYNC_EXPORT_PRIVATE SyncSession {
42 public:
43  // The Delegate services events that occur during the session requiring an
44  // explicit (and session-global) action, as opposed to events that are simply
45  // recorded in per-session state.
46  class SYNC_EXPORT_PRIVATE Delegate {
47   public:
48    // The client was throttled and should cease-and-desist syncing activity
49    // until the specified time.
50    virtual void OnThrottled(const base::TimeDelta& throttle_duration) = 0;
51
52    // Some of the client's types were throttled.
53    virtual void OnTypesThrottled(
54        ModelTypeSet types,
55        const base::TimeDelta& throttle_duration) = 0;
56
57    // Silenced intervals can be out of phase with individual sessions, so the
58    // delegate is the only thing that can give an authoritative answer for
59    // "is syncing silenced right now". This shouldn't be necessary very often
60    // as the delegate ensures no session is started if syncing is silenced.
61    // ** Note **  This will return true if silencing commenced during this
62    // session and the interval has not yet elapsed, but the contract here is
63    // solely based on absolute time values. So, this cannot be used to infer
64    // that any given session _instance_ is silenced.  An example of reasonable
65    // use is for UI reporting.
66    virtual bool IsCurrentlyThrottled() = 0;
67
68    // The client has been instructed to change its short poll interval.
69    virtual void OnReceivedShortPollIntervalUpdate(
70        const base::TimeDelta& new_interval) = 0;
71
72    // The client has been instructed to change its long poll interval.
73    virtual void OnReceivedLongPollIntervalUpdate(
74        const base::TimeDelta& new_interval) = 0;
75
76    // The client has been instructed to change its sessions commit
77    // delay.
78    virtual void OnReceivedSessionsCommitDelay(
79        const base::TimeDelta& new_delay) = 0;
80
81    // The client needs to cease and desist syncing at once.  This occurs when
82    // the Syncer detects that the backend store has fundamentally changed or
83    // is a different instance altogether (e.g. swapping from a test instance
84    // to production, or a global stop syncing operation has wiped the store).
85    // TODO(lipalani) : Replace this function with the one below. This function
86    // stops the current sync cycle and purges the client. In the new model
87    // the former would be done by the |SyncProtocolError| and
88    // the latter(which is an action) would be done in ProfileSyncService
89    // along with the rest of the actions.
90    virtual void OnShouldStopSyncingPermanently() = 0;
91
92    // Called for the syncer to respond to the error sent by the server.
93    virtual void OnSyncProtocolError(
94        const sessions::SyncSessionSnapshot& snapshot) = 0;
95
96    // Called when the server wants to change the number of hints the client
97    // will buffer locally.
98    virtual void OnReceivedClientInvalidationHintBufferSize(int size) = 0;
99
100   protected:
101    virtual ~Delegate() {}
102  };
103
104  // Build a session with a nudge tracker.  Used for sync cycles with origin of
105  // GU_TRIGGER (ie. notification, local change, and/or refresh request)
106  static SyncSession* BuildForNudge(SyncSessionContext* context,
107                                    Delegate* delegate,
108                                    const SyncSourceInfo& source,
109                                    const NudgeTracker* nudge_tracker);
110
111  // Build a session without a nudge tracker.  Used for poll or configure type
112  // sync cycles.
113  static SyncSession* Build(SyncSessionContext* context,
114                            Delegate* delegate,
115                            const SyncSourceInfo& source);
116
117  ~SyncSession();
118
119  // Builds a thread-safe and read-only copy of the current session state.
120  SyncSessionSnapshot TakeSnapshot() const;
121
122  // Builds and sends a snapshot to the session context's listeners.
123  void SendEventNotification(SyncEngineEvent::EventCause cause);
124
125  // TODO(akalin): Split this into context() and mutable_context().
126  SyncSessionContext* context() const { return context_; }
127  Delegate* delegate() const { return delegate_; }
128  const StatusController& status_controller() const {
129    return *status_controller_.get();
130  }
131  StatusController* mutable_status_controller() {
132    return status_controller_.get();
133  }
134
135  const SyncSourceInfo& source() const { return source_; }
136
137  const NudgeTracker* nudge_tracker() const { return nudge_tracker_; }
138
139 private:
140  SyncSession(SyncSessionContext* context,
141              Delegate* delegate,
142              const SyncSourceInfo& source,
143              const NudgeTracker* nudge_tracker);
144
145  // The context for this session, guaranteed to outlive |this|.
146  SyncSessionContext* const context_;
147
148  // The source for initiating this sync session.
149  SyncSourceInfo source_;
150
151  // The delegate for this session, must never be NULL.
152  Delegate* const delegate_;
153
154  // Our controller for various status and error counters.
155  scoped_ptr<StatusController> status_controller_;
156
157  const NudgeTracker* nudge_tracker_;
158
159  DISALLOW_COPY_AND_ASSIGN(SyncSession);
160};
161
162}  // namespace sessions
163}  // namespace syncer
164
165#endif  // SYNC_SESSIONS_SYNC_SESSION_H_
166