org.springframework.social.connect
Interface ConnectionRepository

public interface ConnectionRepository

Data access interface for saving and restoring Connection objects from a persistent store. The view is relative to a specific local user--it's not possible using this interface to access or update connections for multiple local users. If you need that capability, see UsersConnectionRepository.

Author:

Keith Donald

See Also:

UsersConnectionRepository

Method Summary

void	addConnection(Connection<?> connection) Add a new connection to this repository for the current user.
org.springframework.util.MultiValueMap<java.lang.String,Connection<?>>	findAllConnections() Find all connections the current user has across all providers.
<A> java.util.List<Connection<A>>	findConnections(java.lang.Class<A> apiType) Find the connections the current user has to the provider of the given API e.g.
java.util.List<Connection<?>>	findConnections(java.lang.String providerId) Find the connections the current user has to the provider registered by the given id e.g.
org.springframework.util.MultiValueMap<java.lang.String,Connection<?>>	findConnectionsToUsers(org.springframework.util.MultiValueMap<java.lang.String,java.lang.String> providerUserIds) Find the connections the current user has to the given provider users.
<A> Connection<A>	findPrimaryConnection(java.lang.Class<A> apiType) Find the "primary" connection the current user has to the provider of the given API e.g.
<A> Connection<A>	getConnection(java.lang.Class<A> apiType, java.lang.String providerUserId) Get a connection between the current user and the given provider user.
Connection<?>	getConnection(ConnectionKey connectionKey) Get a connection for the current user by its key, which consists of the providerId + providerUserId.
<A> Connection<A>	getPrimaryConnection(java.lang.Class<A> apiType) Get the "primary" connection the current user has to the provider of the given API e.g.
void	removeConnection(ConnectionKey connectionKey) Remove a single Connection for the current user from this repository.
void	removeConnections(java.lang.String providerId) Remove all Connections between the current user and the provider from this repository.
void	updateConnection(Connection<?> connection) Update a Connection already added to this repository.

Method Detail

findAllConnections

org.springframework.util.MultiValueMap<java.lang.String,Connection<?>> findAllConnections()

Find all connections the current user has across all providers. The returned map contains an entry for each provider the user is connected to. The key for each entry is the providerId, and the value is the list of Connections that exist between the user and that provider. For example, if the user is connected once to Facebook and twice to Twitter, the returned map would contain two entries with the following structure:

 { 
     "facebook" -> Connection("Keith Donald") ,
     "twitter"  -> Connection("kdonald"), Connection("springsource")
 }
 

The returned map is sorted by providerId and entry values are ordered by rank. Returns an empty map if the user has no connections.

findConnections

java.util.List<Connection<?>> findConnections(java.lang.String providerId)

Find the connections the current user has to the provider registered by the given id e.g. 'facebook'. The returned list is ordered by connection rank. Returns an empty list if the user has no connections to the provider.

Parameters:

providerId - the provider id e.g. "facebook"

Returns:

the connections the user has to the provider, or an empty list if none

findConnections

<A> java.util.List<Connection<A>> findConnections(java.lang.Class<A> apiType)

Find the connections the current user has to the provider of the given API e.g. Facebook.class. Semantically equivalent to findConnections(String), but uses the apiType as the provider key instead of the providerId. Useful for direct use by application code to obtain parameterized Connection instances e.g. List<Connection<Facebook>>.

Type Parameters:

A - the API parameterized type

Parameters:

apiType - the API type e.g. Facebook.class or Twitter.class

Returns:

the connections the user has to the provider of the API, or an empty list if none

findConnectionsToUsers

org.springframework.util.MultiValueMap<java.lang.String,Connection<?>> findConnectionsToUsers(org.springframework.util.MultiValueMap<java.lang.String,java.lang.String> providerUserIds)

Find the connections the current user has to the given provider users. The providerUsers parameter accepts a map containing an entry for each provider the caller is interested in. The key for each entry is the providerId e.g. "facebook", and the value is a list of provider user ids to fetch connections to e.g. ("126500", "34521", "127243"). The returned map has the same structure and order, except the provider userId values have been replaced by Connection instances. If no connection exists between the current user and a given provider user, a null value is returned for that position.

Parameters:

providerUserIds - the provider users map

Returns:

the provider user connection map

getConnection

Connection<?> getConnection(ConnectionKey connectionKey)

Get a connection for the current user by its key, which consists of the providerId + providerUserId.

Parameters:

connectionKey - the service provider connection key

Returns:

the connection

Throws:

NoSuchConnectionException - if no such connection exists for the current user

getConnection

<A> Connection<A> getConnection(java.lang.Class<A> apiType,
                                java.lang.String providerUserId)

Get a connection between the current user and the given provider user. Semantically equivalent to getConnection(ConnectionKey), but uses the apiType as the provider key instead of the providerId. Useful for direct use by application code to obtain a parameterized Connection instance.

Type Parameters:

A - the API parameterized type

Parameters:

apiType - the API type e.g. Facebook.class or Twitter.class

providerUserId - the provider user e.g. "126500".

Returns:

the connection

Throws:

NoSuchConnectionException - if no such connection exists for the current user

getPrimaryConnection

<A> Connection<A> getPrimaryConnection(java.lang.Class<A> apiType)

Get the "primary" connection the current user has to the provider of the given API e.g. Facebook.class. If the user has multiple connections to the provider associated with the given apiType, this method returns the one with the top rank (or priority). Useful for direct use by application code to obtain a parameterized Connection instance.

Type Parameters:

A - the API parameterized type

Parameters:

apiType - the API type e.g. Facebook.class or Twitter.class

Returns:

the primary connection

Throws:

NotConnectedException - if the user is not connected to the provider of the API

findPrimaryConnection

<A> Connection<A> findPrimaryConnection(java.lang.Class<A> apiType)

Find the "primary" connection the current user has to the provider of the given API e.g. Facebook.class. Semantically equivalent to getPrimaryConnection(Class) but returns null if no connection is found instead of throwing an exception.

Type Parameters:

A - the API parameterized type

Parameters:

apiType - the API type e.g. Facebook.class or Twitter.class

Returns:

the primary connection, or null if not found

addConnection

void addConnection(Connection<?> connection)

Add a new connection to this repository for the current user. After the connection is added, it can be retrieved later using one of the finders defined in this interface.

Parameters:

connection - the new connection to add to this repository

Throws:

DuplicateConnectionException - if the user already has this connection

updateConnection

void updateConnection(Connection<?> connection)

Update a Connection already added to this repository. Merges the field values of the given connection object with the values stored in the repository.

Parameters:

connection - the existing connection to update in this repository

removeConnections

void removeConnections(java.lang.String providerId)

Remove all Connections between the current user and the provider from this repository. Does nothing if no provider connections exist.

Parameters:

providerId - the provider id e.g. 'facebook'

removeConnection

void removeConnection(ConnectionKey connectionKey)

Remove a single Connection for the current user from this repository. Does nothing if no such connection exists.

Parameters:

connectionKey - the connection key