sync/sessions/sync_session.h

   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
  34 namespace syncer {
  35 class ModelSafeWorker;
  36
  37 namespace sessions {
  38
  39 class NudgeTracker;
  40
  41 class 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 OnSilencedUntil(const base::TimeTicks& silenced_until) = 0;
  51
  52     // Silenced intervals can be out of phase with individual sessions, so the
  53     // delegate is the only thing that can give an authoritative answer for
  54     // "is syncing silenced right now". This shouldn't be necessary very often
  55     // as the delegate ensures no session is started if syncing is silenced.
  56     // ** Note **  This will return true if silencing commenced during this
  57     // session and the interval has not yet elapsed, but the contract here is
  58     // solely based on absolute time values. So, this cannot be used to infer
  59     // that any given session _instance_ is silenced.  An example of reasonable
  60     // use is for UI reporting.
  61     virtual bool IsSyncingCurrentlySilenced() = 0;
  62
  63     // The client has been instructed to change its short poll interval.
  64     virtual void OnReceivedShortPollIntervalUpdate(
  65         const base::TimeDelta& new_interval) = 0;
  66
  67     // The client has been instructed to change its long poll interval.
  68     virtual void OnReceivedLongPollIntervalUpdate(
  69         const base::TimeDelta& new_interval) = 0;
  70
  71     // The client has been instructed to change its sessions commit
  72     // delay.
  73     virtual void OnReceivedSessionsCommitDelay(
  74         const base::TimeDelta& new_delay) = 0;
  75
  76     // The client needs to cease and desist syncing at once.  This occurs when
  77     // the Syncer detects that the backend store has fundamentally changed or
  78     // is a different instance altogether (e.g. swapping from a test instance
  79     // to production, or a global stop syncing operation has wiped the store).
  80     // TODO(lipalani) : Replace this function with the one below. This function
  81     // stops the current sync cycle and purges the client. In the new model
  82     // the former would be done by the |SyncProtocolError| and
  83     // the latter(which is an action) would be done in ProfileSyncService
  84     // along with the rest of the actions.
  85     virtual void OnShouldStopSyncingPermanently() = 0;
  86
  87     // Called for the syncer to respond to the error sent by the server.
  88     virtual void OnSyncProtocolError(
  89         const sessions::SyncSessionSnapshot& snapshot) = 0;
  90
  91     // Called when the server wants to change the number of hints the client
  92     // will buffer locally.
  93     virtual void OnReceivedClientInvalidationHintBufferSize(int size) = 0;
  94
  95    protected:
  96     virtual ~Delegate() {}
  97   };
  98
  99   // Build a session with a nudge tracker.  Used for sync cycles with origin of
 100   // GU_TRIGGER (ie. notification, local change, and/or refresh request)
 101   static SyncSession* BuildForNudge(SyncSessionContext* context,
 102                                     Delegate* delegate,
 103                                     const SyncSourceInfo& source,
 104                                     const NudgeTracker* nudge_tracker);
 105
 106   // Build a session without a nudge tracker.  Used for poll or configure type
 107   // sync cycles.
 108   static SyncSession* Build(SyncSessionContext* context,
 109                             Delegate* delegate,
 110                             const SyncSourceInfo& source);
 111
 112   ~SyncSession();
 113
 114   // Builds a thread-safe and read-only copy of the current session state.
 115   SyncSessionSnapshot TakeSnapshot() const;
 116
 117   // Builds and sends a snapshot to the session context's listeners.
 118   void SendEventNotification(SyncEngineEvent::EventCause cause);
 119
 120   // TODO(akalin): Split this into context() and mutable_context().
 121   SyncSessionContext* context() const { return context_; }
 122   Delegate* delegate() const { return delegate_; }
 123   const StatusController& status_controller() const {
 124     return *status_controller_.get();
 125   }
 126   StatusController* mutable_status_controller() {
 127     return status_controller_.get();
 128   }
 129
 130   const SyncSourceInfo& source() const { return source_; }
 131
 132   const NudgeTracker* nudge_tracker() const { return nudge_tracker_; }
 133
 134  private:
 135   SyncSession(SyncSessionContext* context,
 136               Delegate* delegate,
 137               const SyncSourceInfo& source,
 138               const NudgeTracker* nudge_tracker);
 139
 140   // The context for this session, guaranteed to outlive |this|.
 141   SyncSessionContext* const context_;
 142
 143   // The source for initiating this sync session.
 144   SyncSourceInfo source_;
 145
 146   // The delegate for this session, must never be NULL.
 147   Delegate* const delegate_;
 148
 149   // Our controller for various status and error counters.
 150   scoped_ptr<StatusController> status_controller_;
 151
 152   const NudgeTracker* nudge_tracker_;
 153
 154   DISALLOW_COPY_AND_ASSIGN(SyncSession);
 155 };
 156
 157 }  // namespace sessions
 158 }  // namespace syncer
 159
 160 #endif  // SYNC_SESSIONS_SYNC_SESSION_H_