org.shredzone.flattr4j.oauth

Class FlattrAuthenticator

java.lang.Object

org.shredzone.flattr4j.oauth.FlattrAuthenticator

Direct Known Subclasses:

AndroidAuthenticator

public class FlattrAuthenticator
extends Object

Helps through the OAuth2 authentication process at Flattr.

Author:

Richard "Shred" Körber

See Also:

IETF OAuth V2

Constructor Summary

Constructors

Constructor and Description
FlattrAuthenticator(ConsumerKey consumerKey) Constructs a new instance with the given ConsumerKey.
FlattrAuthenticator(String key, String secret) Constructs a new instance with the given consumer key and secret.

Method Summary

Methods

Modifier and Type	Method and Description
String	authenticate() Authenticates this application against Flattr.
String	authenticate(String state) Authenticates this application against Flattr.
protected String	buildScopeString() Builds a scope string for the scope flags set.
protected Connector	createConnector() Creates a Connector for sending requests.
AccessToken	fetchAccessToken(String code) Fetches an AccessToken that gives access to the Flattr API.
String	getAccessTokenUrl() The access token url required to retrieve the access token for flattr.com.
String	getCallbackUrl() A callback URL.
String	getRequestTokenUrl() The request token url.
String	getResponseType()
EnumSet<Scope>	getScope() The access scope.
void	setAccessTokenUrl(String accessTokenUrl)
void	setCallbackUrl(String callbackUrl)
void	setRequestTokenUrl(String requestTokenUrl)
void	setResponseType(String responseType) The OAuth response type.
void	setScope(EnumSet<Scope> scope)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FlattrAuthenticator

public FlattrAuthenticator(ConsumerKey consumerKey)

Constructs a new instance with the given ConsumerKey.

Parameters:

consumerKey - ConsumerKey

FlattrAuthenticator

public FlattrAuthenticator(String key,
                   String secret)

Constructs a new instance with the given consumer key and secret.

Parameters:

key - Consumer key

secret - Consumer secret

Method Detail

getRequestTokenUrl

public String getRequestTokenUrl()

The request token url.

NOTE: This request token url must match the url defined at http://developers.flattr.net/api/#authorization

Returns:

the defined request token url

setRequestTokenUrl

public void setRequestTokenUrl(String requestTokenUrl)

getAccessTokenUrl

public String getAccessTokenUrl()

The access token url required to retrieve the access token for flattr.com.

NOTE: This access token url must match the url defined at http://developers.flattr.net/api/#authorization

Returns:

the defined access token url

setAccessTokenUrl

public void setAccessTokenUrl(String accessTokenUrl)

getCallbackUrl

public String getCallbackUrl()

A callback URL. If set, the user is forwarded to this URL in order to pass the valication code. null means that the user is required to retrieve the code from Flattr and enter it manually. Use null if you cannot provide a callback URL, for example on a desktop or handheld device application.

NOTE: This callback URL must exactly match the URL that was used on registration. Otherwise the authentication process will fail. NOTE: If you registered your application as "client" type, callback url must be null.

Defaults to null.

setCallbackUrl

public void setCallbackUrl(String callbackUrl)

getScope

public EnumSet<Scope> getScope()

The access scope. This is a set of rights the consumer needs. The set of rights is shown to the user on authentication. Defaults to an empty set.

setScope

public void setScope(EnumSet<Scope> scope)

setResponseType

public void setResponseType(String responseType)

The OAuth response type. This is code or token, with the former being the default.

Since:

2.3

getResponseType

public String getResponseType()

authenticate

public String authenticate()
                    throws FlattrException

Authenticates this application against Flattr. The user is required to visit the returned url and retrieve a code. The code needs to be passed to fetchAccessToken(String) in order to complete the authorization.

When a callback url was set, Flattr will forward the user to this url with the following GET parameter:

• code: the code

This way the user only needs to log in at Flattr, but does not need to copy a code to complete the authorization.

Scope flags need to be set properly before invocation.

Returns:

The authentication URL that the user must visit

Throws:

FlattrException

Since:

2.0

authenticate

public String authenticate(String state)
                    throws FlattrException

Authenticates this application against Flattr. The user is required to visit the returned url and retrieve a code. The code needs to be passed to fetchAccessToken(String) in order to complete the authorization.

When a callback url was set, Flattr will forward the user to this url with the following GET parameters:

• code: the code
• state: the value of the state parameter that was given

This way the user only needs to log in at Flattr, but does not need to copy a code to complete the authorization.

Scope flags need to be set properly before invocation.

Parameters:

state - A value that is passed to the callback URL, to maintain state and reidentify the user between request and callback. Optional, may be null.

Returns:

The authentication URL the user must visit

Throws:

FlattrException

Since:

2.0

fetchAccessToken

public AccessToken fetchAccessToken(String code)
                             throws FlattrException

Fetches an AccessToken that gives access to the Flattr API. After the user entered the code (or when the callback url was invoked), this method is invoked to complete the authorization process.

The returned access token can be serialized or the AccessToken.getToken() persisted in a database. It is needed to access the Flattr API with a valid authentication. The token is valid until revoked by the user.

Parameters:

code - The code that was returned from Flattr

Returns:

AccessToken giving access to the Flattr API for the authenticated user

Throws:

FlattrException

createConnector

protected Connector createConnector()

Creates a Connector for sending requests.

Returns:

Connector

buildScopeString

protected String buildScopeString()

Builds a scope string for the scope flags set.

Returns:

Scope string: scope texts, separated by spaces.