com.googlecode.janrain4j.api.engage
Interface EngageService

public interface EngageService

The EngageService provides access to the Janrain Engage API.

Note that methods might throw a ErrorResponeException in case your plan (Basic, Plus or Pro) is not sufficient for making the particular Janrain Engage API call.

Since:

1.0

Author:

Marcel Overdijk

See Also:

Janrain Engage Documentation

Method Summary

void	activity(String identifier, Activity activity) Post an activity update to the user's activity stream.
void	activity(String identifier, Activity activity, String location) Post an activity update to the user's activity stream.
void	activity(String identifier, String activity) Post an activity update to the user's activity stream.
void	activity(String identifier, String activity, String location) Post an activity update to the user's activity stream.
AllMappingsResponse	allMappings() Get all stored mappings for the application.
AnalyticsResponse	analytics(Date start, Date end) Get statistics for your application.
UserDataResponse	authInfo(String token) Get information about the user currently signing in to your web application.
UserDataResponse	authInfo(String token, boolean extended) Get information about the user currently signing in to your web application.
ContactsResponse	getContacts(String identifier) Retrieve a list of contacts for an identifier in the Portable Contacts format.
UserDataResponse	getUserData(String identifier) Obtain an up-to-date copy of a user's profile as previously returned by an authInfo(String) API call.
UserDataResponse	getUserData(String identifier, boolean extended) Obtain an up-to-date copy of a user's profile as previously returned by an authInfo(String) API call.
void	map(String identifier, String primaryKey) Map an OpenID identifier to a primary key.
void	map(String identifier, String primaryKey, boolean overwrite) Map an OpenID identifier to a primary key.
MappingsResponse	mappings(String primaryKey) Get all stored mappings for a particular primary key.
void	setAuthProviders(List<String> providers) Set the providers that will be displayed in the Sign-in Interface.
void	setStatus(String identifier, String status) Set the status message for the account corresponding to an identifier.
void	setStatus(String identifier, String status, String location) Set the status message for the account corresponding to an identifier.
boolean	supportsActivity(String providerName) Returns true if the provider name supports the activity(String, Activity) API call.
boolean	supportsSetStatus(String providerName) Returns true if the provider name supports the setStatus(String, String) API call.
void	unmap(String primaryKey) Remove (unmap) all OpenID identifiers from a primary key.
void	unmap(String primaryKey, boolean unlink) Remove (unmap) all OpenID identifiers from a primary key, and optionally unlink your application from the user's account with the provider.
void	unmap(String identifier, String primaryKey) Remove (unmap) an OpenID identifier from a primary key.
void	unmap(String identifier, String primaryKey, boolean unlink) Remove (unmap) an OpenID identifier from a primary key, and optionally unlink your application from the user's account with the provider.

Method Detail

authInfo

UserDataResponse authInfo(String token)
                          throws EngageFailureException,
                                 ErrorResponeException

Get information about the user currently signing in to your web application.

Parameters:

token - The token parameter received at your "token_url".

Returns:

The user data Janrain Engage knows about the user signing into your website.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: auth_info

authInfo

UserDataResponse authInfo(String token,
                          boolean extended)
                          throws EngageFailureException,
                                 ErrorResponeException

Get information about the user currently signing in to your web application.

Parameters:

token - The token parameter received at your "token_url".

extended - 'true' or 'false'(default). Return the extended Simple Registration and HCard data in addition to the normalized Portable Contacts format.

Returns:

The user data with Janrain Engage knows about the user signing into your website.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: auth_info

getContacts

ContactsResponse getContacts(String identifier)
                             throws EngageFailureException,
                                    ErrorResponeException

Retrieve a list of contacts for an identifier in the Portable Contacts format.

Parameters:

identifier - The identifier returned from a previous authInfo(String) API call.

Returns:

The Portable Contacts data representing the address book contents.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: get_contacts

getUserData

UserDataResponse getUserData(String identifier)
                             throws EngageFailureException,
                                    ErrorResponeException

Obtain an up-to-date copy of a user's profile as previously returned by an authInfo(String) API call.

Parameters:

identifier - The identifier returned from a previous authInfo(String) API call.

Returns:

The user data Janrain Engage knows about the user.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: get_user_data

getUserData

UserDataResponse getUserData(String identifier,
                             boolean extended)
                             throws EngageFailureException,
                                    ErrorResponeException

Obtain an up-to-date copy of a user's profile as previously returned by an authInfo(String) API call.

Parameters:

identifier - The identifier returned from a previous authInfo(String) API call.

extended - 'true' or 'false'(default). Return the extended Simple Registration and HCard data in addition to the normalized Portable Contacts format.

Returns:

The user data Janrain Engage knows about the user.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: get_user_data

setStatus

void setStatus(String identifier,
               String status)
               throws EngageFailureException,
                      ErrorResponeException

Set the status message for the account corresponding to an identifier.

Parameters:

identifier - The identifier returned from the authInfo(String) API call.

status - The status message to set. No length restriction on the status is imposed by Janrain Engage, but some providers may truncate it implicitly (e.g., Twitter).

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: set_status

setStatus

void setStatus(String identifier,
               String status,
               String location)
               throws EngageFailureException,
                      ErrorResponeException

Set the status message for the account corresponding to an identifier.

Parameters:

identifier - The identifier returned from the authInfo(String) API call.

status - The status message to set. No length restriction on the status is imposed by Janrain Engage, but some providers may truncate it implicitly (e.g., Twitter).

location - This is a string containing location data associated with the content being published. The string is latitude, followed by longitude, for example "37.4220 -122.0843". Valid values for latitude are -90.0 to +90.0, with North being positive. Valid values for longitude are -180.0 to +180.0 with East being positive.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: set_status

supportsSetStatus

boolean supportsSetStatus(String providerName)

Returns true if the provider name supports the setStatus(String, String) API call.

Parameters:

providerName - The provider name

Returns:

True if supported.

Since:

1.1

map

void map(String identifier,
         String primaryKey)
         throws EngageFailureException,
                ErrorResponeException

Map an OpenID identifier to a primary key. Future logins by this owner of this OpenID will return the mapped primaryKey in the authInfo(String) API response, which you may use to sign the user in.

The map call is usually made right after a call to authInfo(String), when you already know who the user is because they are signed in to your website with their legacy (or existing) account.

Parameters:

identifier - The identifier returned from the authInfo(String) API call.

primaryKey - The primary key from your users table, as a string.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: map

map

void map(String identifier,
         String primaryKey,
         boolean overwrite)
         throws EngageFailureException,
                ErrorResponeException

Map an OpenID identifier to a primary key. Future logins by this owner of this OpenID will return the mapped primaryKey in the authInfo(String) API response, which you may use to sign the user in.

The map call is usually made right after a call to authInfo(String), when you already know who the user is because they are signed in to your website with their legacy (or existing) account.

Parameters:

identifier - The identifier returned from the authInfo(String) API call.

primaryKey - The primary key from your users table, as a string.

overwrite - 'true'(default) or 'false'. If 'false', only create the mapping if one does not already exist for the specified identifier.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: map

unmap

void unmap(String primaryKey)
           throws EngageFailureException,
                  ErrorResponeException

Remove (unmap) all OpenID identifiers from a primary key.

Parameters:

primaryKey - The primary key from your users table, as a string.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: unmap

unmap

void unmap(String primaryKey,
           boolean unlink)
           throws EngageFailureException,
                  ErrorResponeException

Remove (unmap) all OpenID identifiers from a primary key, and optionally unlink your application from the user's account with the provider.

Parameters:

primaryKey - The primary key from your users table, as a string.

unlink - 'true' or 'false'(default). If 'true', unlink your application from the user's account with the provider.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: unmap

unmap

void unmap(String identifier,
           String primaryKey)
           throws EngageFailureException,
                  ErrorResponeException

Remove (unmap) an OpenID identifier from a primary key.

Parameters:

identifier - The identifier returned from the auth_info API call.

primaryKey - The primary key from your users table, as a string.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: unmap

unmap

void unmap(String identifier,
           String primaryKey,
           boolean unlink)
           throws EngageFailureException,
                  ErrorResponeException

Remove (unmap) an OpenID identifier from a primary key, and optionally unlink your application from the user's account with the provider.

Parameters:

identifier - The identifier returned from the auth_info API call.

primaryKey - The primary key from your users table, as a string.

unlink - 'true' or 'false'(default). If 'true', unlink your application from the user's account with the provider.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: unmap

mappings

MappingsResponse mappings(String primaryKey)
                          throws EngageFailureException,
                                 ErrorResponeException

Get all stored mappings for a particular primary key.

Parameters:

primaryKey - The primary key from your users table, as a string.

Returns:

All stored mappings for a particular primary key.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: mappings

allMappings

AllMappingsResponse allMappings()
                                throws EngageFailureException,
                                       ErrorResponeException

Get all stored mappings for the application.

Returns:

All stored mappings for the application.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: all_mappings

activity

void activity(String identifier,
              Activity activity)
              throws EngageFailureException,
                     ErrorResponeException

Post an activity update to the user's activity stream.

Parameters:

identifier - The identifier returned from the authInfo(String) API call.

activity - The activity structure.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: activity

activity

void activity(String identifier,
              String activity)
              throws EngageFailureException,
                     ErrorResponeException

Post an activity update to the user's activity stream.

Parameters:

identifier - The identifier returned from the authInfo(String) API call.

activity - The activity structure as JSON String.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: activity

activity

void activity(String identifier,
              Activity activity,
              String location)
              throws EngageFailureException,
                     ErrorResponeException

Post an activity update to the user's activity stream.

Parameters:

identifier - The identifier returned from the authInfo(String) API call.

activity - The activity structure.

location - This is a string containing location data associated with the content being published. The string is latitude, followed by longitude, for example "37.4220 -122.0843". Valid values for latitude are -90.0 to +90.0, with North being positive. Valid values for longitude are -180.0 to +180.0 with East being positive.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: activity

activity

void activity(String identifier,
              String activity,
              String location)
              throws EngageFailureException,
                     ErrorResponeException

Post an activity update to the user's activity stream.

Parameters:

identifier - The identifier returned from the authInfo(String) API call.

activity - The activity structure as JSON String.

location - This is a string containing location data associated with the content being published. The string is latitude, followed by longitude, for example "37.4220 -122.0843". Valid values for latitude are -90.0 to +90.0, with North being positive. Valid values for longitude are -180.0 to +180.0 with East being positive.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: activity

supportsActivity

boolean supportsActivity(String providerName)

Returns true if the provider name supports the activity(String, Activity) API call.

Parameters:

providerName - The provider name

Returns:

True if supported.

Since:

1.1

analytics

AnalyticsResponse analytics(Date start,
                            Date end)
                            throws EngageFailureException,
                                   ErrorResponeException

Get statistics for your application.

Parameters:

start - The start date.

end - The end date.

Returns:

A URL to access the analytics file.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: analytics

setAuthProviders

void setAuthProviders(List<String> providers)
                      throws EngageFailureException,
                             ErrorResponeException

Set the providers that will be displayed in the Sign-in Interface.

Parameters:

providers - A list of provider names.

Throws:

EngageFailureException - If any unknown error occurs while communicating with the Janrain Engage API.

ErrorResponeException - If the Janrain Engage API returns an error response.

Since:

1.0

See Also:

Janrain Engage API Documentation: set_auth_providers