/**
 * 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.facebook;

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;

/**
 * Facebook User Service method definitions.
 * 
 * This class defines the APIs for registering a new account with the system and authentication using Facebook credentials, or more precisely, using the Facebook OAuth 2.0 authentication. The methods also describe the means for granting the system authorization for accessing content of the Facebook account.
 * Creating an account or authenticating with Facebook credentials does not automatically grant the system persistent permissions for accessing the account contents.
 * 
 * Note that the Facebook 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_FACEBOOK) 
public class FacebookUserService {
  /**
   * This method is called by Facebook after user has either denied or granted the service permission to his/her Facebook account, and is not meant to be used directly by the end-users. The method implements the OAuth2 authorization process as defined by Facebook.
   * 
   * @param authorizationCode OAuth2 authorization code generated by Facebook.
   * @param errorCode Optional error message as reported by Facebook.
   * @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 FacebookUserCore.processOAuth2Callback(authorizationCode.getValue(), errorCode.getValue(), nonce.getValue());
  }
  
  /**
   * This method can be used to authenticate the user using Facebook credentials. The external account connection must be created either by registering the user as a new user using Facebook credentials or by authorizing the use of the Facebook 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>public_profile</i>, which should be present in each token by default. Additional Facebook OAuth2 scopes can be present, but are not required.
   * 
   * @param authenticatedUser
   * @param accessToken OAuth2 access token as provided by Facebook.
   * @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 FacebookUserCore.login(authenticatedUser.getSession(), accessToken.getValue());
  }
  
  /**
   * This method can be used to register a new user using a Facebook account. The passed access token is used to retrieve the required registration details from the account. The token scope should contain at least public_profile, which should be present in each token by default. Additional Facebook OAuth2 scopes can be present, but are not required.
   * 
   * The Facebook 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 Facebook
   * @return response
   */
  @HTTPServiceMethod(name=service.tut.pori.users.Definitions.METHOD_REGISTER)
  public Response register(@HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH2_ACCESS_TOKEN) StringParameter accessToken)
  {
    return FacebookUserCore.register(accessToken.getValue());
  }
  
  /**
   * This method can be used to grant the service access to the authenticated user's Facebook account. This method will redirect to Facebook's consent page asking user's permission to access the account. The default configuration will ask permissions for all Facebook 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 Facebook, 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 either show status message notifying the result of the authorization process or redirect to final target, if redirection URL was provided.
   * 
   * The method assumes that Facebook accounts are personal and an attempt to authorize the same Facebook account for multiple users will result in error.
   * 
   * @param authenticatedUser
   * @param redirectUri The final target, where the user should be redirected to after successful authorization. If not given, a default status message will be shown.
   * @return Error response, redirection or default OK response depending on the given parameters.
   */
  @HTTPServiceMethod(name=Definitions.METHOD_OAUTH2_AUTHORIZATION_REDIRECT)
  public Response authorize(
      @HTTPAuthenticationParameter AuthenticationParameter authenticatedUser,
      @HTTPMethodParameter(name=Definitions.PARAMETER_FACEBOOK_HACK_REDIRECT_URI, required=false) StringParameter redirectUri){
    return FacebookUserCore.createAuthorizationRedirection(authenticatedUser.getUserIdentity(), redirectUri.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 Facebook 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 FacebookUserCore.removeAuthorization(authenticatedUser.getUserIdentity());
  }
}