org.shredzone.flattr4j.oauth
Class FlattrAuthenticator

java.lang.Object
  org.shredzone.flattr4j.oauth.FlattrAuthenticator

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

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

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	getCallbackUrl() A callback URL.
EnumSet<Scope>	getScope() The access scope.
void	setCallbackUrl(String callbackUrl)
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

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)

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.