components/keyed_service/ios/browser_state_keyed_service_factory.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_KEYED_SERVICE_IOS_BROWSER_STATE_KEYED_SERVICE_FACTORY_H_
   6 #define COMPONENTS_KEYED_SERVICE_IOS_BROWSER_STATE_KEYED_SERVICE_FACTORY_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/compiler_specific.h"
  10 #include "components/keyed_service/core/keyed_service_export.h"
  11 #include "components/keyed_service/core/keyed_service_factory.h"
  12
  13 class BrowserStateDependencyManager;
  14 class KeyedService;
  15
  16 namespace web {
  17 class BrowserState;
  18 }
  19
  20 // Base class for Factories that take a BrowserState object and return some
  21 // service on a one-to-one mapping. Each factory that derives from this class
  22 // *must* be a Singleton (only unit tests don't do that).
  23 //
  24 // We do this because services depend on each other and we need to control
  25 // shutdown/destruction order. In each derived classes' constructors, the
  26 // implementors must explicitly state which services are depended on.
  27 class KEYED_SERVICE_EXPORT BrowserStateKeyedServiceFactory
  28     : public KeyedServiceFactory {
  29  public:
  30   // A function that supplies the instance of a KeyedService for a given
  31   // BrowserState. This is used primarily for testing, where we want to feed
  32   // a specific mock into the BSKSF system.
  33   typedef KeyedService* (*TestingFactoryFunction)(web::BrowserState* context);
  34
  35   // Associates |factory| with |context| so that |factory| is used to create
  36   // the KeyedService when requested.  |factory| can be NULL to signal that
  37   // KeyedService should be NULL. Multiple calls to SetTestingFactory() are
  38   // allowed; previous services will be shut down.
  39   void SetTestingFactory(web::BrowserState* context,
  40                          TestingFactoryFunction factory);
  41
  42   // Associates |factory| with |context| and immediately returns the created
  43   // KeyedService. Since the factory will be used immediately, it may not be
  44   // NULL.
  45   KeyedService* SetTestingFactoryAndUse(web::BrowserState* context,
  46                                         TestingFactoryFunction factory);
  47
  48  protected:
  49   // BrowserStateKeyedServiceFactories must communicate with a
  50   // BrowserStateDependencyManager. For all non-test code, write your subclass
  51   // constructors like this:
  52   //
  53   //   MyServiceFactory::MyServiceFactory()
  54   //     : BrowserStateKeyedServiceFactory(
  55   //         "MyService",
  56   //         BrowserStateDependencyManager::GetInstance()) {
  57   //   }
  58   BrowserStateKeyedServiceFactory(const char* name,
  59                                   /*BrowserState*/DependencyManager* manager);
  60   ~BrowserStateKeyedServiceFactory() override;
  61
  62   // Common implementation that maps |context| to some service object. Deals
  63   // with incognito and testing contexts per subclass instructions.  If |create|
  64   // is true, the service will be created using BuildServiceInstanceFor() if it
  65   // doesn't already exist.
  66   KeyedService* GetServiceForBrowserState(web::BrowserState* context,
  67                                           bool create);
  68
  69   // Interface for people building a concrete FooServiceFactory: --------------
  70
  71   // Finds which browser state (if any) to use.
  72   virtual web::BrowserState* GetBrowserStateToUse(
  73       web::BrowserState* context) const;
  74
  75   // By default, we create instances of a service lazily and wait until
  76   // GetForBrowserState() is called on our subclass. Some services need to be
  77   // created as soon as the BrowserState has been brought up.
  78   virtual bool ServiceIsCreatedWithBrowserState() const;
  79
  80   // By default, TestingBrowserStates will be treated like normal contexts.
  81   // You can override this so that by default, the service associated with the
  82   // TestingBrowserState is NULL. (This is just a shortcut around
  83   // SetTestingFactory() to make sure our contexts don't directly refer to the
  84   // services they use.)
  85   bool ServiceIsNULLWhileTesting() const override;
  86
  87   // Interface for people building a type of BrowserStateKeyedFactory: -------
  88
  89   // All subclasses of BrowserStateKeyedServiceFactory must return a
  90   // KeyedService instead of just a BrowserStateKeyedBase.
  91   virtual KeyedService* BuildServiceInstanceFor(
  92       web::BrowserState* context) const = 0;
  93
  94   // A helper object actually listens for notifications about BrowserState
  95   // destruction, calculates the order in which things are destroyed and then
  96   // does a two pass shutdown.
  97   //
  98   // First, BrowserStateShutdown() is called on every ServiceFactory and will
  99   // usually call KeyedService::Shutdown(), which gives each
 100   // KeyedService a chance to remove dependencies on other
 101   // services that it may be holding.
 102   //
 103   // Secondly, BrowserStateDestroyed() is called on every ServiceFactory
 104   // and the default implementation removes it from |mapping_| and deletes
 105   // the pointer.
 106   virtual void BrowserStateShutdown(web::BrowserState* context);
 107   virtual void BrowserStateDestroyed(web::BrowserState* context);
 108
 109  private:
 110   // Registers any user preferences on this service. This is called by
 111   // RegisterProfilePrefsIfNecessary() and should be overriden by any service
 112   // that wants to register profile-specific preferences.
 113   virtual void RegisterProfilePrefs(
 114       user_prefs::PrefRegistrySyncable* registry) {}
 115
 116   // KeyedServiceFactory:
 117   KeyedService* BuildServiceInstanceFor(
 118       base::SupportsUserData* context) const final;
 119   bool IsOffTheRecord(base::SupportsUserData* context) const final;
 120
 121   // KeyedServiceBaseFactory:
 122   user_prefs::PrefRegistrySyncable* GetAssociatedPrefRegistry(
 123       base::SupportsUserData* context) const final;
 124   base::SupportsUserData* GetContextToUse(
 125       base::SupportsUserData* context) const final;
 126   bool ServiceIsCreatedWithContext() const final;
 127   void ContextShutdown(base::SupportsUserData* context) final;
 128   void ContextDestroyed(base::SupportsUserData* context) final;
 129   void RegisterPrefs(user_prefs::PrefRegistrySyncable* registry) final;
 130
 131   DISALLOW_COPY_AND_ASSIGN(BrowserStateKeyedServiceFactory);
 132 };
 133
 134 #endif  // COMPONENTS_KEYED_SERVICE_IOS_BROWSER_STATE_KEYED_SERVICE_FACTORY_H_