src/chrome/browser/invalidation/invalidation_service.h

   1 // Copyright 2013 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 CHROME_BROWSER_INVALIDATION_INVALIDATION_SERVICE_H_
   6 #define CHROME_BROWSER_INVALIDATION_INVALIDATION_SERVICE_H_
   7
   8 #include "components/browser_context_keyed_service/browser_context_keyed_service.h"
   9 #include "sync/notifier/invalidation_util.h"
  10 #include "sync/notifier/invalidator_state.h"
  11
  12 namespace syncer {
  13 class InvalidationHandler;
  14 }  // namespace syncer
  15
  16 namespace invalidation {
  17 class InvalidationLogger;
  18
  19 // Interface for classes that handle invalidation registrations and send out
  20 // invalidations to register handlers.
  21 //
  22 // Invalidation clients should follow the pattern below:
  23 //
  24 // When starting the client:
  25 //
  26 //   frontend->RegisterInvalidationHandler(client_handler);
  27 //
  28 // When the set of IDs to register changes for the client during its lifetime
  29 // (i.e., between calls to RegisterInvalidationHandler(client_handler) and
  30 // UnregisterInvalidationHandler(client_handler):
  31 //
  32 //   frontend->UpdateRegisteredInvalidationIds(client_handler, client_ids);
  33 //
  34 // When shutting down the client for browser shutdown:
  35 //
  36 //   frontend->UnregisterInvalidationHandler(client_handler);
  37 //
  38 // Note that there's no call to UpdateRegisteredIds() -- this is because the
  39 // invalidation API persists registrations across browser restarts.
  40 //
  41 // When permanently shutting down the client, e.g. when disabling the related
  42 // feature:
  43 //
  44 //   frontend->UpdateRegisteredInvalidationIds(client_handler, ObjectIdSet());
  45 //   frontend->UnregisterInvalidationHandler(client_handler);
  46 //
  47 // If an invalidation handler cares about the invalidator state, it should also
  48 // do the following when starting the client:
  49 //
  50 //   invalidator_state = frontend->GetInvalidatorState();
  51 //
  52 // It can also do the above in OnInvalidatorStateChange(), or it can use the
  53 // argument to OnInvalidatorStateChange().
  54 //
  55 // It is an error to have registered handlers when an
  56 // InvalidationFrontend is shut down; clients must ensure that they
  57 // unregister themselves before then. (Depending on the
  58 // InvalidationFrontend, shutdown may be equivalent to destruction, or
  59 // a separate function call like Shutdown()).
  60 //
  61 // NOTE(akalin): Invalidations that come in during browser shutdown may get
  62 // dropped.  This won't matter once we have an Acknowledge API, though: see
  63 // http://crbug.com/78462 and http://crbug.com/124149.
  64 //
  65 // This class inherits from ProfileKeyedService to make it possible to correctly
  66 // cast from various InvalidationService implementations to ProfileKeyedService
  67 // in InvalidationServiceFactory.
  68 class InvalidationService : public BrowserContextKeyedService {
  69  public:
  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  protected:
 107   virtual ~InvalidationService() { }
 108 };
 109
 110 }  // namespace invalidation
 111
 112 #endif  // CHROME_BROWSER_INVALIDATION_INVALIDATION_SERVICE_H_