invalidation_service.h revision 5f1c94371a64b3196d4be9466099bb892df9b88e 
1// Copyright 2014 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 COMPONENTS_INVALIDATION_INVALIDATION_SERVICE_H_
6#define COMPONENTS_INVALIDATION_INVALIDATION_SERVICE_H_
7
8#include "base/callback_forward.h"
9#include "components/invalidation/invalidation_util.h"
10#include "components/invalidation/invalidator_state.h"
11
12class IdentityProvider;
13
14namespace syncer {
15class InvalidationHandler;
16}  // namespace syncer
17
18namespace invalidation {
19class InvalidationLogger;
20
21// Interface for classes that handle invalidation registrations and send out
22// invalidations to register handlers.
23//
24// Invalidation clients should follow the pattern below:
25//
26// When starting the client:
27//
28//   frontend->RegisterInvalidationHandler(client_handler);
29//
30// When the set of IDs to register changes for the client during its lifetime
31// (i.e., between calls to RegisterInvalidationHandler(client_handler) and
32// UnregisterInvalidationHandler(client_handler):
33//
34//   frontend->UpdateRegisteredInvalidationIds(client_handler, client_ids);
35//
36// When shutting down the client for browser shutdown:
37//
38//   frontend->UnregisterInvalidationHandler(client_handler);
39//
40// Note that there's no call to UpdateRegisteredIds() -- this is because the
41// invalidation API persists registrations across browser restarts.
42//
43// When permanently shutting down the client, e.g. when disabling the related
44// feature:
45//
46//   frontend->UpdateRegisteredInvalidationIds(client_handler, ObjectIdSet());
47//   frontend->UnregisterInvalidationHandler(client_handler);
48//
49// If an invalidation handler cares about the invalidator state, it should also
50// do the following when starting the client:
51//
52//   invalidator_state = frontend->GetInvalidatorState();
53//
54// It can also do the above in OnInvalidatorStateChange(), or it can use the
55// argument to OnInvalidatorStateChange().
56//
57// It is an error to have registered handlers when an
58// InvalidationFrontend is shut down; clients must ensure that they
59// unregister themselves before then. (Depending on the
60// InvalidationFrontend, shutdown may be equivalent to destruction, or
61// a separate function call like Shutdown()).
62//
63// NOTE(akalin): Invalidations that come in during browser shutdown may get
64// dropped.  This won't matter once we have an Acknowledge API, though: see
65// http://crbug.com/78462 and http://crbug.com/124149.
66class InvalidationService {
67 public:
68  virtual ~InvalidationService() {}
69
70  // Starts sending notifications to |handler|.  |handler| must not be NULL,
71  // and it must not already be registered.
72  //
73  // Handler registrations are persisted across restarts of sync.
74  virtual void RegisterInvalidationHandler(
75      syncer::InvalidationHandler* handler) = 0;
76
77  // Updates the set of ObjectIds associated with |handler|.  |handler| must
78  // not be NULL, and must already be registered.  An ID must be registered for
79  // at most one handler.
80  //
81  // Registered IDs are persisted across restarts of sync.
82  virtual void UpdateRegisteredInvalidationIds(
83      syncer::InvalidationHandler* handler,
84      const syncer::ObjectIdSet& ids) = 0;
85
86  // Stops sending notifications to |handler|.  |handler| must not be NULL, and
87  // it must already be registered.  Note that this doesn't unregister the IDs
88  // associated with |handler|.
89  //
90  // Handler registrations are persisted across restarts of sync.
91  virtual void UnregisterInvalidationHandler(
92      syncer::InvalidationHandler* handler) = 0;
93
94  // Returns the current invalidator state.  When called from within
95  // InvalidationHandler::OnInvalidatorStateChange(), this must return
96  // the updated state.
97  virtual syncer::InvalidatorState GetInvalidatorState() const = 0;
98
99  // Returns the ID belonging to this invalidation client.  Can be used to
100  // prevent the receipt of notifications of our own changes.
101  virtual std::string GetInvalidatorClientId() const = 0;
102
103  // Return the logger used to debug invalidations
104  virtual InvalidationLogger* GetInvalidationLogger() = 0;
105
106  // Triggers requests of internal status.
107  virtual void RequestDetailedStatus(
108      base::Callback<void(const base::DictionaryValue&)> post_caller) const = 0;
109
110  // Returns the identity provider.
111  virtual IdentityProvider* GetIdentityProvider() = 0;
112};
113
114}  // namespace invalidation
115
116#endif  // COMPONENTS_INVALIDATION_INVALIDATION_SERVICE_H_
117