de.undercouch.citeproc.remote

Interface RemoteConnector

All Known Implementing Classes:

AbstractRemoteConnector, AuthenticatedRemoteConnector, MendeleyConnector, RemoteConnectorAdapter, ZoteroConnector

public interface RemoteConnector

Reads items from a remote service. Needs an OAuth API key and secret in order to authenticate.

Author:

Michel Kraemer

Method Summary

Modifier and Type	Method and Description
void	authorize(String verificationCode) Authorizes the app.
String	getAccessTokenSecret()
String	getAccessTokenValue()
String	getAuthorizationURL() Gets a new authorization URL from the remote server.
CSLItemData	getItem(String itemId) Requests an item from the service.
List<String>	getItemIDs() Requests a list of item IDs from the server.
Map<String,CSLItemData>	getItems(List<String> itemIds) Requests several items from the service.
int	getMaxBulkItems()
void	setAccessToken(String token, String secret) Authorizes the app.

Method Detail

getAuthorizationURL

String getAuthorizationURL()
                    throws IOException

Gets a new authorization URL from the remote server. This is the first step in the OAuth authorization process. The user has to visit the authorization URL and grant access to this app. Then they will get an verification code which has to be passed to authorize(String)

Returns:

the URL the authorization URL

Throws:

IOException - if the authorization URL could not be retrieved

authorize

void authorize(String verificationCode)
        throws IOException

Authorizes the app. This is the third step in the OAuth authorization process. After the user has visited the authorization URL that was generated by getAuthorizationURL(), this method has to be called to finish authorization

Parameters:

verificationCode - the verification code the user received from the authorization URL

Throws:

IOException - if authorization failed

setAccessToken

void setAccessToken(String token,
                    String secret)

Authorizes the app. If you already know a valid OAuth access token (for example if you cached it from previous sessions) you may call this method instead of getAuthorizationURL() and authorize(String).

This method just saves the provided access token. It does not act with the remote service in any way.

Parameters:

token - the access token value

secret - the access token's secret

See Also:

getAccessTokenValue(), getAccessTokenSecret()

getAccessTokenValue

String getAccessTokenValue()

Returns:

the access token's value used for authentication or null if the app is not yet authenticated

See Also:

setAccessToken(String, String)

getAccessTokenSecret

String getAccessTokenSecret()

Returns:

the access token's secret used for authentication or null if the app is not yet authenticated

See Also:

setAccessToken(String, String)

getItemIDs

List<String> getItemIDs()
                 throws IOException

Requests a list of item IDs from the server. The user has to be authenticated before this method can be called.

Returns:

the item IDs

Throws:

UnauthorizedException - if the user is not authenticated

RequestException - if the server returns an error code

IOException - if the items could not be read from the server

getItem

CSLItemData getItem(String itemId)
             throws IOException

Requests an item from the service. The user has to be authenticated before this method can be called.

Parameters:

itemId - the item's ID

Returns:

the item

Throws:

UnauthorizedException - if the user is not authenticated

RequestException - if the server returns an error code

IOException - if the item could not be read from the server

getItems

Map<String,CSLItemData> getItems(List<String> itemIds)
                          throws IOException

Requests several items from the service. The user has to be authenticated before this method can be called.

Some services support bulk loading. In this case, this method makes as few requests as possible. The getMaxBulkItems() method returns the maximum number of items that can be queried within one request.

Parameters:

itemIds - the IDs of the items to request

Returns:

a map mapping item IDs to retrieved items

Throws:

UnauthorizedException - if the user is not authenticated

RequestException - if the server returns an error code

IOException - if one of the items could not be read from the server

See Also:

getMaxBulkItems()

getMaxBulkItems

int getMaxBulkItems()

Returns:

the maximum number of items that can be queried within one request

See Also:

getItems(List)