org.springframework.social.facebook.api
Interface PlacesOperations

public interface PlacesOperations

Defines the operations for interacting with a user's Facebook checkins.

Method Summary

String	checkin(String placeId, double latitude, double longitude) Checks the authenticated user into the specified location.
String	checkin(String placeId, double latitude, double longitude, String message, String... tags) Checks the authenticated user into the specified location.
Checkin	getCheckin(String checkinId) Retrieves details for a single checkin.
PagedList<Checkin>	getCheckins() Retrieves a list of up to 25 recent checkins for the authenticated user.
PagedList<Checkin>	getCheckins(int offset, int limit) Deprecated. Use getCheckins(PagingParameters) instead.
PagedList<Checkin>	getCheckins(PagingParameters pagedListParameters) Retrieves a list of checkins for the authenticated user.
PagedList<Checkin>	getCheckins(String objectId) Retrieves a list of up to 25 recent checkins for the specified object.
PagedList<Checkin>	getCheckins(String objectId, int offset, int limit) Deprecated. Use getCheckins(String, PagingParameters) instead.
PagedList<Checkin>	getCheckins(String objectId, PagingParameters pagedListParameters) Retrieves a list of checkins for the specified object.
PagedList<Page>	search(String query, double latitude, double longitude, long distance) Searches for places near a given coordinate.

Method Detail

getCheckins

PagedList<Checkin> getCheckins()

Retrieves a list of up to 25 recent checkins for the authenticated user. Requires "user_checkins" or "friends_checkins" permission.

Returns:

a list Checkins 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 "user_checkins" or "friends_checkins" permission.

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

getCheckins

@Deprecated
PagedList<Checkin> getCheckins(int offset,
                                          int limit)

Deprecated. Use getCheckins(PagingParameters) instead.

Retrieves a list of checkins for the authenticated user. Requires "user_checkins" or "friends_checkins" permission.

Parameters:

offset - the offset into the list of checkins

limit - the maximum number of checkins to return

Returns:

a list Checkins 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 "user_checkins" or "friends_checkins" permission.

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

getCheckins

PagedList<Checkin> getCheckins(PagingParameters pagedListParameters)

Retrieves a list of checkins for the authenticated user. Requires "user_checkins" or "friends_checkins" permission.

Parameters:

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

Returns:

a list Checkins 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 "user_checkins" or "friends_checkins" permission.

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

getCheckins

PagedList<Checkin> getCheckins(String objectId)

Retrieves a list of up to 25 recent checkins for the specified object. If the object is a user, this returns checkins for places the user has checked into. If the object is a page, then this returns checkins that the user's friends has made to the location that the page represents. Requires "user_checkins" or "friends_checkins" permission.

Parameters:

objectId - either a Facebook user ID or page ID

Returns:

a list Checkins, 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 "user_checkins" or "friends_checkins" permission.

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

getCheckins

@Deprecated
PagedList<Checkin> getCheckins(String objectId,
                                          int offset,
                                          int limit)

Deprecated. Use getCheckins(String, PagingParameters) instead.

Retrieves a list of checkins for the specified object. If the object is a user, this returns checkins for places the user has checked into. If the object is a page, then this returns checkins that the user's friends has made to the location that the page represents. Requires "user_checkins" or "friends_checkins" permission.

Parameters:

objectId - either a Facebook user ID or page ID

offset - the offset into the list of checkins

limit - the maximum number of checkins to return

Returns:

a list Checkins, 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 "user_checkins" or "friends_checkins" permission.

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

getCheckins

PagedList<Checkin> getCheckins(String objectId,
                               PagingParameters pagedListParameters)

Retrieves a list of checkins for the specified object. If the object is a user, this returns checkins for places the user has checked into. If the object is a page, then this returns checkins that the user's friends has made to the location that the page represents. Requires "user_checkins" or "friends_checkins" permission.

Parameters:

objectId - either a Facebook user ID or page ID

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

Returns:

a list Checkins, 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 "user_checkins" or "friends_checkins" permission.

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

getCheckin

Checkin getCheckin(String checkinId)

Retrieves details for a single checkin.

Parameters:

checkinId - the checkin ID

Returns:

a Checkin

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.

checkin

String checkin(String placeId,
               double latitude,
               double longitude)

Checks the authenticated user into the specified location. Requires "publish_checkins" permission.

Parameters:

placeId - the ID of the place to check into.

latitude - the latitude of the place.

longitude - the longitude of the place.

Returns:

the ID of the checkin.

Throws:

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

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

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

checkin

String checkin(String placeId,
               double latitude,
               double longitude,
               String message,
               String... tags)

Checks the authenticated user into the specified location. Requires "publish_checkins" permission.

Parameters:

placeId - the ID of the place to check into.

latitude - the latitude of the place.

longitude - the longitude of the place.

message - a message to post along with the checkin.

tags - a varargs list of user IDs to tag on the checkin.

Returns:

the ID of the checkin.

Throws:

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

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

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

search

PagedList<Page> search(String query,
                       double latitude,
                       double longitude,
                       long distance)

Searches for places near a given coordinate.

Parameters:

query - the search query (e.g., "Burritos")

latitude - the latitude of the point to search near

longitude - the longitude of the point to search near

distance - the radius to search within (in feet)

Returns:

a list of Pages matching the search

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.