org.springframework.social.facebook.api
Interface FriendOperations

public interface FriendOperations

Defines operations for interacting with a user's friends and friend lists.

Method Summary

void	addToFriendList(String friendListId, String friendId) Adds a friend to a friend list.
String	createFriendList(String name) Creates a new friend list for the authenticated user.
String	createFriendList(String userId, String name) Creates a new friend list.
void	deleteFriendList(String friendListId) Deletes a friend list.
PagedList<FamilyMember>	getFamily() Retrieves a list of FamilyMember references for the authenticated user.
PagedList<FamilyMember>	getFamily(String userId) Retrieves a list of FamilyMember references for the specified user.
PagedList<String>	getFriendIds() Retrieves a list of the authenticating user's friends' IDs.
PagedList<String>	getFriendIds(String userId) Retrieves a list of the authenticating user's friends' IDs.
Reference	getFriendList(String friendListId) Retrieves a reference to the specified friend list.
PagedList<Reference>	getFriendListMembers(String friendListId) Retrieves references for all users who are members of the specified friend list.
PagedList<Reference>	getFriendLists() Retrieves a list of custom friend lists belonging to the authenticated user.
PagedList<Reference>	getFriendLists(String userId) Retrieves a list of custom friend lists belonging to the specified user.
PagedList<FacebookProfile>	getFriendProfiles() Retrieves the profile data for all of an authenticated user's friends.
PagedList<FacebookProfile>	getFriendProfiles(int offset, int limit) Deprecated. Use getFriendProfiles(PagingParameters) instead.
PagedList<FacebookProfile>	getFriendProfiles(PagingParameters pagedListParameters) Retrieves profile data for the authenticated user's friends.
PagedList<FacebookProfile>	getFriendProfiles(String userId) Retrieves profile data for all of an authenticated user's friends.
PagedList<FacebookProfile>	getFriendProfiles(String userId, int offset, int limit) Deprecated. Use getFriendProfiles(String, PagingParameters) instead.
PagedList<FacebookProfile>	getFriendProfiles(String userId, PagingParameters pagedListParameters) Retrieves profile data for the specified user's friends.
PagedList<Reference>	getFriends() Retrieves a list of user references for the authenticated user's friends.
PagedList<Reference>	getFriends(String userId) Retrieves a list of user references for the specified user's friends.
PagedList<Reference>	getMutualFriends(String userId) Retrieves a list of user references that the authenticated user and the specified user have in common as friends.
PagedList<Reference>	getSubscribedTo() Retrieves a list of user reference for the users that the authenticated user is subscribed to.
PagedList<Reference>	getSubscribedTo(String userId) Retrieves a list of user reference for the users that the specified user is subscribed to.
PagedList<Reference>	getSubscribers() Retrieves a list of user reference for the users that are subscribed to the authenticated user.
PagedList<Reference>	getSubscribers(String userId) Retrieves a list of user reference for the users that are subscribed to the specified user.
void	removeFromFriendList(String friendListId, String friendId) Removes a friend from a friend list.

Method Detail

getFriendLists

PagedList<Reference> getFriendLists()

Retrieves a list of custom friend lists belonging to the authenticated user. Requires "read_friendlists" permission.

Returns:

a list References, each representing a friends list for the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.InsufficientPermissionException - if the user has not granted "read_friendlists" permission.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendLists

PagedList<Reference> getFriendLists(String userId)

Retrieves a list of custom friend lists belonging to the specified user. Requires "read_friendlists" permission.

Parameters:

userId - the user's ID

Returns:

a list References, each representing a friends list for the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.InsufficientPermissionException - if the user has not granted "read_friendlists" permission.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendList

Reference getFriendList(String friendListId)

Retrieves a reference to the specified friend list.

Parameters:

friendListId - the friend list ID.

Returns:

a Reference to the requested friend list.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendListMembers

PagedList<Reference> getFriendListMembers(String friendListId)

Retrieves references for all users who are members of the specified friend list.

Parameters:

friendListId - the friend list ID.

Returns:

a list of Reference, each representing a member of the friend list.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

createFriendList

String createFriendList(String name)

Creates a new friend list for the authenticated user. Requires "manage_friendlists" permission.

Parameters:

name - the name of the friend list.

Returns:

the ID of the newly created friend list.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.InsufficientPermissionException - if the user has not granted "manage_friendlists" permission.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

createFriendList

String createFriendList(String userId,
                        String name)

Creates a new friend list. Requires "manage_friendlists" permission.

Parameters:

userId - the user ID to create the friend list for.

name - the name of the friend list.

Returns:

the ID of the newly created friend list.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.InsufficientPermissionException - if the user has not granted "manage_friendlists" permission.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

deleteFriendList

void deleteFriendList(String friendListId)

Deletes a friend list. Requires "manage_friendlists" permission.

Parameters:

friendListId - the ID of the friend list to remove.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.InsufficientPermissionException - if the user has not granted "manage_friendlists" permission.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

addToFriendList

void addToFriendList(String friendListId,
                     String friendId)

Adds a friend to a friend list. Requires "manage_friendlists" permission.

Parameters:

friendListId - the friend list ID

friendId - The ID of the user to add to the list. The user must be a friend of the list's owner.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.InsufficientPermissionException - if the user has not granted "manage_friendlists" permission.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

removeFromFriendList

void removeFromFriendList(String friendListId,
                          String friendId)

Removes a friend from a friend list. Requires "manage_friendlists" permission.

Parameters:

friendListId - the friend list ID

friendId - The ID of the user to add to the list.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.InsufficientPermissionException - if the user has not granted "manage_friendlists" permission.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriends

PagedList<Reference> getFriends()

Retrieves a list of user references for the authenticated user's friends.

Returns:

a list References, each representing a friend of the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendIds

PagedList<String> getFriendIds()

Retrieves a list of the authenticating user's friends' IDs.

Returns:

a list of Strings, where each entry is the ID of one of the user's friends.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendProfiles

PagedList<FacebookProfile> getFriendProfiles()

Retrieves the profile data for all of an authenticated user's friends. The list of profiles is ordered by each user's Facebook ID.

Returns:

a list FacebookProfiles, each representing a friend of the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendProfiles

@Deprecated
PagedList<FacebookProfile> getFriendProfiles(int offset,
                                                        int limit)

Deprecated. Use getFriendProfiles(PagingParameters) instead.

Retrieves profile data for the authenticated user's friends. The list of profiles is ordered by each user's Facebook ID.

Parameters:

offset - the offset into the friends list to start retrieving profiles.

limit - the maximum number of profiles to return.

Returns:

a list FacebookProfiles, each representing a friend of the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendProfiles

PagedList<FacebookProfile> getFriendProfiles(PagingParameters pagedListParameters)

Retrieves profile data for the authenticated user's friends. The list of profiles is ordered by each user's Facebook ID.

Parameters:

pagedListParameters - the parameters defining the bounds of the list to return.

Returns:

a list FacebookProfiles, each representing a friend of the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriends

PagedList<Reference> getFriends(String userId)

Retrieves a list of user references for the specified user's friends. The list of profiles is ordered by each user's Facebook ID.

Parameters:

userId - the user's ID

Returns:

a list References, each representing a friend of the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendIds

PagedList<String> getFriendIds(String userId)

Retrieves a list of the authenticating user's friends' IDs. The list of profiles is ordered by each user's Facebook ID.

Parameters:

userId - the user's ID

Returns:

a list of Strings, where each entry is the ID of one of the user's friends.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendProfiles

PagedList<FacebookProfile> getFriendProfiles(String userId)

Retrieves profile data for all of an authenticated user's friends. The list of profiles is ordered by each user's Facebook ID.

Parameters:

userId - the user's ID

Returns:

a list FacebookProfiles, each representing a friend of the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendProfiles

@Deprecated
PagedList<FacebookProfile> getFriendProfiles(String userId,
                                                        int offset,
                                                        int limit)

Deprecated. Use getFriendProfiles(String, PagingParameters) instead.

Retrieves profile data for the specified user's friends. The list of profiles is ordered by each user's Facebook ID.

Parameters:

userId - the user's ID

offset - the offset into the friends list to start retrieving profiles.

limit - the maximum number of profiles to return.

Returns:

a list FacebookProfiles, each representing a friend of the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFriendProfiles

PagedList<FacebookProfile> getFriendProfiles(String userId,
                                             PagingParameters pagedListParameters)

Retrieves profile data for the specified user's friends. The list of profiles is ordered by each user's Facebook ID.

Parameters:

userId - the user's ID

pagedListParameters - the parameters defining the bounds of the list to return.

Returns:

a list FacebookProfiles, each representing a friend of the user, or an empty list if not available.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFamily

PagedList<FamilyMember> getFamily()

Retrieves a list of FamilyMember references for the authenticated user.

Returns:

a list of FamilyMembers, each representing a Facebook user that the user is related to.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getFamily

PagedList<FamilyMember> getFamily(String userId)

Retrieves a list of FamilyMember references for the specified user.

Parameters:

userId - the ID of the user to retrieve family members for.

Returns:

a list of FamilyMembers, each representing a Facebook user that the user is related to.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getMutualFriends

PagedList<Reference> getMutualFriends(String userId)

Retrieves a list of user references that the authenticated user and the specified user have in common as friends.

Parameters:

userId - the ID of the user to check for common friendships with.

Returns:

a list of References, each representing a friend that the two users have in common.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getSubscribedTo

PagedList<Reference> getSubscribedTo()

Retrieves a list of user reference for the users that the authenticated user is subscribed to. Requires "user_subscriptions" permission.

Returns:

a list of References, each representing a Facebook user that the user is subscribed to.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getSubscribedTo

PagedList<Reference> getSubscribedTo(String userId)

Retrieves a list of user reference for the users that the specified user is subscribed to. Requires "user_subscriptions" permission for the authenticated user or "friends_subscriptions" permission for accessing the authenticated user's friends subscriptions.

Parameters:

userId - the ID of the user to fetch subscriptions for.

Returns:

a list of References, each representing a Facebook user that the user is subscribed to.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getSubscribers

PagedList<Reference> getSubscribers()

Retrieves a list of user reference for the users that are subscribed to the authenticated user. Requires "user_subscriptions" permission.

Returns:

a list of References, each representing a Facebook user that the user is subscribed to.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.

getSubscribers

PagedList<Reference> getSubscribers(String userId)

Retrieves a list of user reference for the users that are subscribed to the specified user. Requires "user_subscriptions" permission for the authenticated user or "friends_subscriptions" permission for accessing the authenticated user's friends subscriptions.

Parameters:

userId - the ID of the user to fetch subscriptions for.

Returns:

a list of References, each representing a Facebook user that the user is subscribed to.

Throws:

org.springframework.social.ApiException - if there is an error while communicating with Facebook.

org.springframework.social.MissingAuthorizationException - if FacebookTemplate was not created with an access token.