/*
 * Copyright 2015 the original author or authors.
 *
 * 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 org.springframework.social.oauth1;

import org.springframework.util.MultiValueMap;

/**
 * A service interface for the OAuth 1 flow.
 * This interface allows you to conduct the "OAuth dance" with a service provider on behalf of a user.
 * @author Keith Donald
 */
public interface OAuth1Operations {

	/**
	 * The version of OAuth1 implemented by this operations instance.
	 * @see OAuth1Version#CORE_10
	 * @see OAuth1Version#CORE_10_REVISION_A
	 * @return The version of OAuth1 implemented by this operations instance.
	 */
	OAuth1Version getVersion();
	
	/**
	 * Begin a new authorization flow by fetching a new request token from this service provider.
	 * The request token should be stored in the user's session up until the authorization callback is made
	 * and it's time to exchange it for an {@link #exchangeForAccessToken(AuthorizedRequestToken, MultiValueMap) access token}.
	 * @param callbackUrl the URL the provider should redirect to after the member authorizes the connection. Ignored for OAuth 1.0 providers.
	 * @param additionalParameters any additional query parameters to be sent when fetching the request token. Should not be encoded.
	 * @return a temporary request token use for authorization and exchanged for an access token 
	 */
	OAuthToken fetchRequestToken(String callbackUrl, MultiValueMap<String, String> additionalParameters);

	/**
	 * Construct the URL to redirect the user to for authorization.
	 * @param requestToken the request token value, to be encoded in the authorize URL.
	 * @param parameters parameters to pass to the provider in the authorize URL. Should never be null; if there are no parameters to pass, set this argument value to {@link OAuth1Parameters#NONE}.
	 * @return the absolute authorize URL to redirect the user to for authorization
	 */
	String buildAuthorizeUrl(String requestToken, OAuth1Parameters parameters);
	
	/**
	 * Construct the URL to redirect the user to for authentication.
	 * For some provider, the authenticate URL differs from the authorizationUrl slightly in that it does not require the user to authorize the app multiple times.
	 * This provides a better user experience for "Sign in with Provider" scenarios.
	 * @param requestToken the request token value, to be encoded in the authorize URL.
	 * @param parameters parameters to pass to the provider in the authenticate URL. Should never be null; if there are no parameters to pass, set this argument value to {@link OAuth1Parameters#NONE}.
	 * @return the absolute authenticate URL to redirect the user to for authentication
	 */
	String buildAuthenticateUrl(String requestToken, OAuth1Parameters parameters);

	/**
	 * Exchange the authorized request token for an access token.
	 * @param requestToken an authorized request token and verifier. The verifier will be ignored for OAuth 1.0 providers.
	 * @param additionalParameters any additional query parameters to be sent when fetching the access token. Should not be encoded. 
	 * @return an access token granted by the provider
	 */
	OAuthToken exchangeForAccessToken(AuthorizedRequestToken requestToken, MultiValueMap<String, String> additionalParameters);

}