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

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;

/**
 * Twitter User Service method definitions.
 * 
 * This class defines the APIs for registering a new account with the system and authentication using Twitter credentials, or more precisely, using the Twitter OAuth authentication. The methods also describe the means for granting the system authorization for accessing content of the Twitter account.
 * 
 * Creating an account or authenticating with Twitter credentials does not automatically grant the system persistent permissions for accessing the account contents.
 * 
 * Note that the Twitter 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_TWITTER) 
public class TwitterUserService {
  /**
   * This method is called by Twitter after user has either denied or granted the service permission to his/her Twitter account, and is not meant to be used directly by the end-users.
   * 
   * @param authenticatedUser 
   * @param token OAuth token as provided by Twitter.
   * @param verifier OAuth verifier generated by Twitter.
   * @return response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_OAUTH_LOGIN_CALLBACK)
  public Response oAuthLoginCallback(
      @HTTPAuthenticationParameter(required=false) AuthenticationParameter authenticatedUser,
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH_TOKEN) StringParameter token,
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH_VERIFIER) StringParameter verifier
      )
  {
    return TwitterUserCore.processOAuthLoginCallback(authenticatedUser.getSession(), token.getValue(), verifier.getValue());
  }
  
  /**
   * This method is called by Twitter after user has either denied or granted the service permission to his/her Twitter account, and is not meant to be used directly by the end-users.
   * 
   * @param token OAuth token as provided by Twitter.
   * @param verifier OAuth verifier generated by Twitter.
   * @return response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_OAUTH_AUTHORIZE_CALLBACK)
  public Response oAuthAuthorizeCallback(
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH_TOKEN) StringParameter token,
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH_VERIFIER) StringParameter verifier
      )
  {
    return TwitterUserCore.processOAuthAuthorizeCallback(token.getValue(), verifier.getValue());
  }
  
  /**
   * This method is called by Twitter after user has either denied or granted the service permission to his/her Twitter account, and is not meant to be used directly by the end-users.
   * 
   * @param token OAuth token as provided by Twitter.
   * @param verifier OAuth verifier generated by Twitter.
   * @return response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_OAUTH_REGISTER_CALLBACK)
  public Response oAuthRegisterCallback(
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH_TOKEN) StringParameter token,
      @HTTPMethodParameter(name=Definitions.PARAMETER_OAUTH_VERIFIER) StringParameter verifier
      )
  {
    return TwitterUserCore.processOAuthRegisterCallback(token.getValue(), verifier.getValue());
  }
  
  /**
   * This method can be used to authenticate the user using Twitter credentials. The method redirects the user to Twitter's consent page, which will forward the user to the service's login OAuth callback method.
   * 
   * This method implements the Sign in with Twitter OAuth flow as defined by Twitter.
   * 
   * @param authenticatedUser
   * @return response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_LOGIN)
  public Response login(@HTTPAuthenticationParameter(required=false) AuthenticationParameter authenticatedUser) {
    if(UserIdentity.isValid(authenticatedUser.getUserIdentity())){
      return new Response(Status.BAD_REQUEST, "Already logged in. Please logout first.");
    }
    return TwitterUserCore.createLoginRedirection();
  }
  
  /**
   * This method can be used to register a new user using a Twitter account. The method redirects the user to Twitter's consent page, which will forward the user to the service's register OAuth callback method. The twitter profile details will be used for the new user registration.
   * 
   * This method implements the Sign in with Twitter OAuth flow as defined by Twitter.
   * 
   * The Twitter account is assumed to be personal, and an attempt to use the same account to create multiple accounts will result in an error.
   * 
   * @return response
   */
  @HTTPServiceMethod(name=service.tut.pori.users.Definitions.METHOD_REGISTER)
  public Response register() {
    return TwitterUserCore.createRegisterRedirection();
  }
  
  /**
   * This method can be used to grant the service access to the authenticated user's Twitter account. The method redirects the user to Twitter's consent page, which will forward the user to the service's authorization OAuth callback method.
   * 
   * This method implements the Sign in with Twitter OAuth flow as defined by Twitter.
   * 
   * The Twitter account is assumed to be personal, and an attempt to authorize the same Twitter account to multiple users will result in an 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 response
   */
  @HTTPServiceMethod(name=Definitions.METHOD_OAUTH_AUTHORIZATION_REDIRECT)
  public Response authorize(
      @HTTPAuthenticationParameter AuthenticationParameter authenticatedUser,
      @HTTPMethodParameter(name=Definitions.PARAMETER_TWITTER_REDIRECT_URI, required=false) StringParameter redirectUri
      )
  {
    return TwitterUserCore.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 Twitter 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 TwitterUserCore.removeAuthorization(authenticatedUser.getUserIdentity());
  }
}