invalidation_service.h revision 46d4c2bc3267f3f028f39e7e311b0f89aba2e4fd
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/internal_api/public/base/invalidator_state.h" 11#include "sync/notifier/invalidation_util.h" 12 13class IdentityProvider; 14 15namespace syncer { 16class InvalidationHandler; 17} // namespace syncer 18 19namespace invalidation { 20class 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. 71class 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_ 123