Create an abstract flow class that abstracts the following logical steps of calling an OAuth2 enabl…

chrome/common/net/gaia/oauth2_api_call_flow.h

+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CHROME_COMMON_NET_GAIA_OAUTH2_API_CALL_FLOW_H_
+#define CHROME_COMMON_NET_GAIA_OAUTH2_API_CALL_FLOW_H_
+
+#include <string>
+
+#include "base/memory/scoped_ptr.h"
+#include "chrome/common/net/gaia/oauth2_access_token_consumer.h"
+#include "chrome/common/net/gaia/oauth2_access_token_fetcher.h"
+#include "chrome/common/net/gaia/oauth2_mint_token_consumer.h"
+#include "chrome/common/net/gaia/oauth2_mint_token_fetcher.h"
+#include "content/public/common/url_fetcher.h"
+#include "content/public/common/url_fetcher_delegate.h"
+
+class GoogleServiceAuthError;
+class OAuth2MintTokenFlowTest;
+
+namespace net {
+class URLRequestContextGetter;
+}
+
+// Base calss for all classes that implement a flow to call OAuth2

[msw, 2012/03/30 23:56:32]

nit spelling: "class".

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+// enabled APIs.
+//
+// Given a refresh token, an access token, and a list of scopes an OAuth2
+// enabled API is called in the following way:
+// 1. Try the given access token to call the API.
+// 2. If that does not work, use the refresh token and scopes to generate
+//    a new access token.
+// 3. Try the new access token to call the API.
+//
+// This class abstracts the basic steps and exposes template methods
+// for sub-classes to implement for API specific details.
+class OAuth2ApiCallFlow
+    : public content::URLFetcherDelegate,
+      public OAuth2AccessTokenConsumer {
+ public:
+  // Creates an instance that works with the given data.
+  // Note that access_token can be empty. In that case, the flow will skip

[msw, 2012/03/30 23:56:32]

optional nit: vertical bars around |access_token|.

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+  // the first step (of trying an existing acces token).
+  OAuth2ApiCallFlow(
+      net::URLRequestContextGetter* context,
+      const std::string& refresh_token,
+      const std::string& access_token,
+      const std::vector<std::string>& scopes);
+
+  virtual ~OAuth2ApiCallFlow();
+
+  // Start the flow.
+  void Start();
+
+  // OAuth2AccessTokenFetcher implementation.
+  virtual void OnGetTokenSuccess(const std::string& access_token) OVERRIDE;
+  virtual void OnGetTokenFailure(const GoogleServiceAuthError& error) OVERRIDE;
+
+  // content::URLFetcherDelegate implementation.
+  virtual void OnURLFetchComplete(const content::URLFetcher* source) OVERRIDE;
+
+ protected:
+  // Template methods for sub-classes.
+
+  // Methods to help create HTTP request.
+  virtual GURL CreateApiCallUrl() = 0;
+  virtual std::string CreateApiCallBody() = 0;
+
+  // Sub-classes can expose appropriate observer interface by implementing

[msw, 2012/03/30 23:56:32]

nit grammar: "can expose *an* appropriate".

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+  // these template methods.
+  // Called when the API call finished successfully.
+  virtual void ProcessApiCallSuccess(const content::URLFetcher* source) = 0;
+  // Called when the API call failed.
+  virtual void ProcessApiCallFailure(const content::URLFetcher* source) = 0;
+  // Called when a new access token is generated.
+  virtual void ProcessNewAccessToken(const std::string& access_token) = 0;
+  virtual void ProcessMintAccessTokenFailure(
+      const GoogleServiceAuthError& error) = 0;
+
+ private:
+  // The steps this class performs are:

[msw, 2012/03/30 23:56:32]

This is a duplicated but less informative version of the comments at lines
28-33. Please remove or relate these steps to the State enum type/values.

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+  // 1. Try existing access token.
+  // 2. If that works, flow is done. If not, generate a new access token.
+  // 3. Try using new access token.
+  enum State {
+    INITIAL,
+    API_CALL_STARTED,
+    API_CALL_DONE,
+    MINT_ACCESS_TOKEN_STARTED,
+    MINT_ACCESS_TOKEN_DONE,
+    ERROR_STATE
+  };
+
+  friend class OAuth2ApiCallFlowTest;
+
+  // Helper to create an instnace of access token fetcher.

[Ryan Sleevi, 2012/03/30 22:54:17]

nit typo: instnace -> instance

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+  // Caller owns the returned instance.
+  virtual OAuth2AccessTokenFetcher* CreateAccessTokenFetcher();

[msw, 2012/03/30 23:56:32]

nit: Mention that this is virtual just for unit test mocking.

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+
+  // Creates an instance of URLFetcher that does not send or save cookies.
+  // The URLFether's method will be GET if body is empty, POST otherwise.

[msw, 2012/03/30 23:56:32]

nit: perhaps rephrase or mention that "body" indicates the value returned by the
pure virtual CreateApiCallBody.

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+  // Caller owns the returned instance.
+  virtual content::URLFetcher* CreateURLFetcher();

[msw, 2012/03/30 23:56:32]

nit: Mention that this is virtual just for unit test mocking.

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+
+  // Helper methods to implement the state machien for the flow.

[Ryan Sleevi, 2012/03/30 22:54:17]

nit typo: machien -> machine

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+  void BeginApiCall();
+  void EndApiCall(const content::URLFetcher* source);
+  void BeginMintAccessToken();
+  void EndMintAccessToken(const GoogleServiceAuthError* error);
+
+  net::URLRequestContextGetter* context_;
+  std::string refresh_token_;
+  std::string access_token_;
+  std::vector<std::string> scopes_;
+
+  State state_;
+  // Whether we have already tried minting access token once.

[Ryan Sleevi, 2012/03/30 22:54:17]

nit grammar: minting access token once. -> minting an access token.

[Munjal (Google), 2012/04/04 19:24:38]

Done.

+  bool tried_mint_access_token_;
+
+  scoped_ptr<content::URLFetcher> url_fetcher_;
+  scoped_ptr<OAuth2AccessTokenFetcher> oauth2_access_token_fetcher_;
+
+  DISALLOW_COPY_AND_ASSIGN(OAuth2ApiCallFlow);
+};
+
+#endif  // CHROME_COMMON_NET_GAIA_OAUTH2_API_CALL_FLOW_H_