src/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/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/status_controller.h"
  31 #include "sync/sessions/sync_session_context.h"
  32
  33 namespace syncer {
  34 class ModelSafeWorker;
  35
  36 namespace sessions {
  37
  38 class NudgeTracker;
  39
  40 class SYNC_EXPORT_PRIVATE SyncSession {
  41  public:
  42   // The Delegate services events that occur during the session requiring an
  43   // explicit (and session-global) action, as opposed to events that are simply
  44   // recorded in per-session state.
  45   class SYNC_EXPORT_PRIVATE Delegate {
  46    public:
  47     // The client was throttled and should cease-and-desist syncing activity
  48     // until the specified time.
  49     virtual void OnThrottled(const base::TimeDelta& throttle_duration) = 0;
  50
  51     // Some of the client's types were throttled.
  52     virtual void OnTypesThrottled(
  53         ModelTypeSet types,
  54         const base::TimeDelta& throttle_duration) = 0;
  55
  56     // Silenced intervals can be out of phase with individual sessions, so the
  57     // delegate is the only thing that can give an authoritative answer for
  58     // "is syncing silenced right now". This shouldn't be necessary very often
  59     // as the delegate ensures no session is started if syncing is silenced.
  60     // ** Note **  This will return true if silencing commenced during this
  61     // session and the interval has not yet elapsed, but the contract here is
  62     // solely based on absolute time values. So, this cannot be used to infer
  63     // that any given session _instance_ is silenced.  An example of reasonable
  64     // use is for UI reporting.
  65     virtual bool IsCurrentlyThrottled() = 0;
  66
  67     // The client has been instructed to change its short poll interval.
  68     virtual void OnReceivedShortPollIntervalUpdate(
  69         const base::TimeDelta& new_interval) = 0;
  70
  71     // The client has been instructed to change its long poll interval.
  72     virtual void OnReceivedLongPollIntervalUpdate(
  73         const base::TimeDelta& new_interval) = 0;
  74
  75     // The client has been instructed to change its sessions commit
  76     // delay.
  77     virtual void OnReceivedSessionsCommitDelay(
  78         const base::TimeDelta& new_delay) = 0;
  79
  80     // The client needs to cease and desist syncing at once.  This occurs when
  81     // the Syncer detects that the backend store has fundamentally changed or
  82     // is a different instance altogether (e.g. swapping from a test instance
  83     // to production, or a global stop syncing operation has wiped the store).
  84     // TODO(lipalani) : Replace this function with the one below. This function
  85     // stops the current sync cycle and purges the client. In the new model
  86     // the former would be done by the |SyncProtocolError| and
  87     // the latter(which is an action) would be done in ProfileSyncService
  88     // along with the rest of the actions.
  89     virtual void OnShouldStopSyncingPermanently() = 0;
  90
  91     // Called for the syncer to respond to the error sent by the server.
  92     virtual void OnSyncProtocolError(
  93         const sessions::SyncSessionSnapshot& snapshot) = 0;
  94
  95     // Called when the server wants to change the number of hints the client
  96     // will buffer locally.
  97     virtual void OnReceivedClientInvalidationHintBufferSize(int size) = 0;
  98
  99    protected:
 100     virtual ~Delegate() {}
 101   };
 102
 103   // Build a session without a nudge tracker.  Used for poll or configure type
 104   // sync cycles.
 105   static SyncSession* Build(SyncSessionContext* context,
 106                             Delegate* delegate);
 107   ~SyncSession();
 108
 109   // Builds a thread-safe and read-only copy of the current session state.
 110   SyncSessionSnapshot TakeSnapshot() const;
 111   SyncSessionSnapshot TakeSnapshotWithSource(
 112       sync_pb::GetUpdatesCallerInfo::GetUpdatesSource legacy_updates_source)
 113       const;
 114
 115   // Builds and sends a snapshot to the session context's listeners.
 116   void SendSyncCycleEndEventNotification(
 117       sync_pb::GetUpdatesCallerInfo::GetUpdatesSource source);
 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  private:
 131   SyncSession(SyncSessionContext* context, Delegate* delegate);
 132
 133   // The context for this session, guaranteed to outlive |this|.
 134   SyncSessionContext* const context_;
 135
 136   // The delegate for this session, must never be NULL.
 137   Delegate* const delegate_;
 138
 139   // Our controller for various status and error counters.
 140   scoped_ptr<StatusController> status_controller_;
 141
 142   DISALLOW_COPY_AND_ASSIGN(SyncSession);
 143 };
 144
 145 }  // namespace sessions
 146 }  // namespace syncer
 147
 148 #endif  // SYNC_SESSIONS_SYNC_SESSION_H_