src/components/invalidation/invalidation_service.h

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