org.springframework.social.connect
Interface Connection<A>

Type Parameters:

A - a strongly-typed binding to the service provider's API

All Known Implementing Classes:

AbstractConnection, OAuth1Connection, OAuth2Connection

public interface Connection<A>

A link to a service provider user. Allows the client application to access or update user information using the provider's API. Exposes a set of operations that are common across all service providers, including the ability to access user profile information and update user status.

Author:

Keith Donald

Method Summary

ConnectionData	createData() Creates a data transfer object that can be used to persist the state of this connection.
UserProfile	fetchUserProfile() Fetch a normalized model of the user's profile on the provider system.
A	getApi() A Java binding to the service provider's native API.
java.lang.String	getDisplayName() A display name or label for this connection.
java.lang.String	getImageUrl() A link to a image that visualizes this connection.
ConnectionKey	getKey() The key identifying this connection.
java.lang.String	getProfileUrl() The public URL of the connected user's profile at the provider's site.
boolean	hasExpired() Returns true if this connection has expired.
void	refresh() Refresh this connection.
void	sync() Sync's this connection object with the current state of the external user's profile.
boolean	test() Test this connection.
void	updateStatus(java.lang.String message) Update the user's status on the provider's system.

Method Detail

getKey

ConnectionKey getKey()

The key identifying this connection. A composite key that consists of the "providerId" plus "providerUserId"; for example, "facebook" and "125660".

getDisplayName

java.lang.String getDisplayName()

A display name or label for this connection. Should be suitable for display on a UI and distinguish this connection from others with the same provider. Generally the full name or screen name of the connected provider user e.g. "Keith Donald" or "@kdonald". May be null if this information is not public or not provided. The value of this property may change if the user updates his or her profile.

See Also:

sync()

getProfileUrl

java.lang.String getProfileUrl()

The public URL of the connected user's profile at the provider's site. A client application may use this value along with the displayName to generate a link to the user's profile on the provider's system. May be null if this information is not public or not provided. The value of this property may change if the user updates his or her profile.

See Also:

sync()

getImageUrl

java.lang.String getImageUrl()

A link to a image that visualizes this connection. Should visually distinguish this connection from others with the same provider. Generally the small/thumbnail version of the connected provider user's profile picture. May be null if this information is not public or not provided. The value of this property may change if the user updates his or her profile.

See Also:

sync()

sync

void sync()

Sync's this connection object with the current state of the external user's profile. Triggers locally cached profile fields to update if they have changed on the provider's system.

test

boolean test()

Test this connection. If false, indicates calls to the api will fail. Used to proactively test authorization credentials such as an API access token before invoking the service API.

hasExpired

boolean hasExpired()

Returns true if this connection has expired. An expired connection cannot be used; calls to test() return false, and any service API invocations fail. If expired, you may call refresh() to renew the connection. Not supported by all Connection implementations; always returns false if not supported.

refresh

void refresh()

Refresh this connection. Used to renew an expired connection. If the refresh operation is successful, hasExpired() returns false. Not supported by all connection implementations; if not supported, this method is a no-op.

fetchUserProfile

UserProfile fetchUserProfile()

Fetch a normalized model of the user's profile on the provider system. Capable of exposing the user's name, email, and username. What is actually exposed depends on the provider and scope of this connection.

updateStatus

void updateStatus(java.lang.String message)

Update the user's status on the provider's system. This method is a no-op if a status concept is not supported by the service provider.

Parameters:

message - the status message

getApi

A getApi()

A Java binding to the service provider's native API.

createData

ConnectionData createData()

Creates a data transfer object that can be used to persist the state of this connection. Used to support the transfer of connection state between layers of the application, such as to the database layer.