/**
 * Copyright 2014 Tampere University of Technology, Pori Department
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package service.tut.pori.users.google;

import core.tut.pori.http.Response;
import core.tut.pori.http.Response.Status;
import core.tut.pori.http.annotations.HTTPAuthenticationParameter;
import core.tut.pori.http.annotations.HTTPMethodParameter;
import core.tut.pori.http.annotations.HTTPService;
import core.tut.pori.http.annotations.HTTPServiceMethod;
import core.tut.pori.http.parameters.AuthenticationParameter;
import core.tut.pori.http.parameters.StringParameter;
import core.tut.pori.users.UserIdentity;

/**
 * Google User Service method definitions.
 * 
 * This class defines the APIs for registering a new account with the system and authentication using Google credentials, or more precisely, using the Google OAuth 2.0 authentication. The methods also describe the means for granting the system authorization for accessing content of the Google account.
 * 
 * Creating an account or authenticating with Google credentials does not automatically grant the system persistent permissions for accessing the account contents.
 * 
 * Note that the Google User Service does not contain a method for removing an existing user account. An existing account can be removed using the User Service 
 */
@HTTPService(name=Definitions.SERVICE_USERS_GOOGLE) 
public class GoogleUserService {
  
  /**
   * This method is called by Google after user has either denied or granted the service permission to his/her Google account, and is not meant to be used directly by the end-users. The method implements the OAuth2 authorization process as defined by Google.
   * 
   * @param authorizationCode OAuth2 authorization code generated by Google.
   * @param errorCode Optional error message as reported by Google.
   * @param nonce Short-lived nonce value randomly generated by the authorization process.
   * @return response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_OAUTH2_CALLBACK)
  public Response oAuth2Callback(
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH2_AUTHORIZATION_CODE, required=false) StringParameter authorizationCode,
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH2_ERROR_CODE, required=false) StringParameter errorCode,
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH2_STATE) StringParameter nonce
      )
  {
    return GoogleUserCore.processOAuth2Callback(authorizationCode.getValue(), errorCode.getValue(), nonce.getValue());
  }
  
  /**
   * This method allows a user to revoke the previously given authorization permissions. Note that calling this method does not prevent user from authenticating (logging in) using the credentials, nor will it remove the user account from the system, but calling this method will prevent the system from accessing the user's content stored in the Google account. 
   * 
   * In practice this means, that no synchronization can be performed for the account until authorization is restored. <i>All</i> previously synchronized content will be removed from the system.
   * 
   * @param authenticatedUser
   * @return response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_UNAUTHORIZE)
  public Response unauthorize(
      @HTTPAuthenticationParameter AuthenticationParameter authenticatedUser)
  {
    return GoogleUserCore.removeAuthorization(authenticatedUser.getUserIdentity());
  }
  
  /**
   * This method can be used to authenticate the user using Google credentials. The external account connection must be created either by registering the user as a new user using Google credentials or by authorizing the use of the Google account before the login functionality can be used.
   * 
   * The passed access token is used to validate the user identity. The token scope should contain at least <i>profile</i>. Additional Google OAuth2 scopes can be present, but are not required.
   * 
   * @param authenticatedUser
   * @param accessToken OAuth2 access token as provided by Google.
   * @return response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_LOGIN)
  public Response login(
      @HTTPAuthenticationParameter(required=false) AuthenticationParameter authenticatedUser,
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH2_ACCESS_TOKEN) StringParameter accessToken
      )
  {
    if(UserIdentity.isValid(authenticatedUser.getUserIdentity())){
      return new Response(Status.BAD_REQUEST, "Already logged in. Please logout first.");
    }
    return GoogleUserCore.login(authenticatedUser.getSession(), accessToken.getValue());
  }
  
  /**
   * This method can be used to register a new user using a Google account. The passed access token is used to retrieve the required registration details from the account. The token scope should contain at least profile, additional Google OAuth2 scopes can be present, but are not required.
   * 
   * The Google account is assumed to be personal, and an attempt to use the same account to create multiple accounts will result in an error.
   * 
   * @param accessToken OAuth2 access token as provided by Google.
   * @return response
   */
  @HTTPServiceMethod(name=service.tut.pori.users.Definitions.METHOD_REGISTER)
  public Response register(@HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH2_ACCESS_TOKEN) StringParameter accessToken)
  {
    return GoogleUserCore.register(accessToken.getValue());
  }
  
  /**
   * This method can be used to grant the service access to the authenticated user's Google account. This method will redirect to Google's consent page asking user's permission to access the account. The default configuration will ask permissions for <i>https://picasaweb.google.com/data/</i> and <i>profile</i> Google OAuth2 scopes, though the actual scopes required will depend on the services to be used.
   * 
   * The authorization process will use the default OAuth2 authentication flow as implemented by Google, firstly redirecting the user to the consent page, which in turn will redirect the user back to the OAuth2 callback method. The callback method will show status message notifying the result of the authorization.
   * 
   * The method assumes that Google accounts are personal and an attempt to authorize the same Google account for multiple users will result in error.
   * 
   * @param authenticatedUser
   * @return response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_OAUTH2_AUTHORIZATION_REDIRECT)
  public Response authorize(@HTTPAuthenticationParameter AuthenticationParameter authenticatedUser){
    return GoogleUserCore.createAuthorizationRedirection(authenticatedUser.getUserIdentity());
  }
}