components/keyed_service/content/browser_context_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_CONTENT_BROWSER_CONTEXT_KEYED_SERVICE_FACTORY_H_
   6 #define COMPONENTS_KEYED_SERVICE_CONTENT_BROWSER_CONTEXT_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 BrowserContextDependencyManager;
  14 class KeyedService;
  15
  16 namespace content {
  17 class BrowserContext;
  18 }
  19
  20 // Base class for Factories that take a BrowserContext 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 BrowserContextKeyedServiceFactory
  28     : public KeyedServiceFactory {
  29  public:
  30   // Registers preferences used in this service on the pref service of
  31   // |context|. This is the public interface and is safe to be called multiple
  32   // times because testing code can have multiple services of the same type
  33   // attached to a single |context|. Only test code is allowed to call this
  34   // method.
  35   // TODO(gab): This method can be removed entirely when
  36   // PrefService::DeprecatedGetPrefRegistry() is phased out.
  37   void RegisterUserPrefsOnBrowserContextForTest(
  38       content::BrowserContext* context);
  39
  40   // A function that supplies the instance of a KeyedService for a given
  41   // BrowserContext. This is used primarily for testing, where we want to feed
  42   // a specific mock into the BCKSF system.
  43   typedef KeyedService* (*TestingFactoryFunction)(
  44       content::BrowserContext* context);
  45
  46   // Associates |factory| with |context| so that |factory| is used to create
  47   // the KeyedService when requested.  |factory| can be NULL to signal that
  48   // KeyedService should be NULL. Multiple calls to SetTestingFactory() are
  49   // allowed; previous services will be shut down.
  50   void SetTestingFactory(content::BrowserContext* context,
  51                          TestingFactoryFunction factory);
  52
  53   // Associates |factory| with |context| and immediately returns the created
  54   // KeyedService. Since the factory will be used immediately, it may not be
  55   // NULL.
  56   KeyedService* SetTestingFactoryAndUse(content::BrowserContext* context,
  57                                         TestingFactoryFunction factory);
  58
  59  protected:
  60   // BrowserContextKeyedServiceFactories must communicate with a
  61   // BrowserContextDependencyManager. For all non-test code, write your subclass
  62   // constructors like this:
  63   //
  64   //   MyServiceFactory::MyServiceFactory()
  65   //     : BrowserContextKeyedServiceFactory(
  66   //         "MyService",
  67   //         BrowserContextDependencyManager::GetInstance())
  68   //   {}
  69   BrowserContextKeyedServiceFactory(const char* name,
  70                                     BrowserContextDependencyManager* manager);
  71   ~BrowserContextKeyedServiceFactory() override;
  72
  73   // Common implementation that maps |context| to some service object. Deals
  74   // with incognito contexts per subclass instructions with
  75   // GetBrowserContextRedirectedInIncognito() and
  76   // GetBrowserContextOwnInstanceInIncognito() through the
  77   // GetBrowserContextToUse() method on the base.  If |create| is true, the
  78   // service will be created using BuildServiceInstanceFor() if it doesn't
  79   // already exist.
  80   KeyedService* GetServiceForBrowserContext(content::BrowserContext* context,
  81                                             bool create);
  82
  83   // Interface for people building a concrete FooServiceFactory: --------------
  84
  85   // Finds which browser context (if any) to use.
  86   virtual content::BrowserContext* GetBrowserContextToUse(
  87       content::BrowserContext* context) const;
  88
  89   // By default, we create instances of a service lazily and wait until
  90   // GetForBrowserContext() is called on our subclass. Some services need to be
  91   // created as soon as the BrowserContext has been brought up.
  92   virtual bool ServiceIsCreatedWithBrowserContext() const;
  93
  94   // By default, TestingBrowserContexts will be treated like normal contexts.
  95   // You can override this so that by default, the service associated with the
  96   // TestingBrowserContext is NULL. (This is just a shortcut around
  97   // SetTestingFactory() to make sure our contexts don't directly refer to the
  98   // services they use.)
  99   bool ServiceIsNULLWhileTesting() const override;
 100
 101   // Interface for people building a type of BrowserContextKeyedFactory: -------
 102
 103   // All subclasses of BrowserContextKeyedServiceFactory must return a
 104   // KeyedService instead of just a BrowserContextKeyedBase.
 105   virtual KeyedService* BuildServiceInstanceFor(
 106       content::BrowserContext* context) const = 0;
 107
 108   // A helper object actually listens for notifications about BrowserContext
 109   // destruction, calculates the order in which things are destroyed and then
 110   // does a two pass shutdown.
 111   //
 112   // First, BrowserContextShutdown() is called on every ServiceFactory and will
 113   // usually call KeyedService::Shutdown(), which gives each
 114   // KeyedService a chance to remove dependencies on other
 115   // services that it may be holding.
 116   //
 117   // Secondly, BrowserContextDestroyed() is called on every ServiceFactory
 118   // and the default implementation removes it from |mapping_| and deletes
 119   // the pointer.
 120   virtual void BrowserContextShutdown(content::BrowserContext* context);
 121   virtual void BrowserContextDestroyed(content::BrowserContext* context);
 122
 123  private:
 124   friend class BrowserContextDependencyManagerUnittests;
 125
 126   // Registers any user preferences on this service. This is called by
 127   // RegisterProfilePrefsIfNecessary() and should be overriden by any service
 128   // that wants to register profile-specific preferences.
 129   virtual void RegisterProfilePrefs(
 130       user_prefs::PrefRegistrySyncable* registry) {}
 131
 132   // KeyedServiceFactory:
 133   KeyedService* BuildServiceInstanceFor(
 134       base::SupportsUserData* context) const final;
 135   bool IsOffTheRecord(base::SupportsUserData* context) const final;
 136
 137   // KeyedServiceBaseFactory:
 138   user_prefs::PrefRegistrySyncable* GetAssociatedPrefRegistry(
 139       base::SupportsUserData* context) const final;
 140   base::SupportsUserData* GetContextToUse(
 141       base::SupportsUserData* context) const final;
 142   bool ServiceIsCreatedWithContext() const final;
 143   void ContextShutdown(base::SupportsUserData* context) final;
 144   void ContextDestroyed(base::SupportsUserData* context) final;
 145   void RegisterPrefs(user_prefs::PrefRegistrySyncable* registry) final;
 146
 147   DISALLOW_COPY_AND_ASSIGN(BrowserContextKeyedServiceFactory);
 148 };
 149
 150 #endif  // COMPONENTS_KEYED_SERVICE_CONTENT_BROWSER_CONTEXT_KEYED_SERVICE_FACTORY_H_