org.springframework.social.facebook.api

Interface MediaOperations

public interface MediaOperations

Defines operations for working with albums, photos, and videos.

Method Summary

Methods

Modifier and Type	Method and Description
String	createAlbum(String name, String description) Creates a new photo album.
String	createAlbum(String ownerId, String name, String description) Creates a new photo album.
Album	getAlbum(String albumId) Retrieves data for a specific album.
byte[]	getAlbumImage(String albumId) Retrieves an album's image as an array of bytes.
byte[]	getAlbumImage(String albumId, ImageType imageType) Retrieves an album's image as an array of bytes.
PagedList<Album>	getAlbums() Retrieves a list of albums belonging to the authenticated user.
PagedList<Album>	getAlbums(PagingParameters pagedListParameters) Retrieves a list of albums belonging to the authenticated user.
PagedList<Album>	getAlbums(String ownerId) Retrieves a list of albums belonging to a specific owner (user, page, etc).
PagedList<Album>	getAlbums(String ownerId, PagingParameters pagedListParameters) Retrieves a list of albums belonging to a specific owner (user, page, etc).
Photo	getPhoto(String photoId) Retrieve data for a specified photo.
byte[]	getPhotoImage(String photoId) Retrieves a photo's image as an array of bytes.
byte[]	getPhotoImage(String photoId, ImageType imageType) Retrieves a photo's image as an array of bytes.
PagedList<Photo>	getPhotos(String objectId) Retrieves data for up to 25 photos from a specific album or that a user is tagged in.
PagedList<Photo>	getPhotos(String objectId, PagingParameters pagedListParameters) Retrieves photo data from a specific album or that a user is tagged in.
Video	getVideo(String videoId) Retrieves data for a specific video.
byte[]	getVideoImage(String videoId) Retrieves a video's image as an array of bytes.
PagedList<Video>	getVideos() Retrieves a list of up to 25 videos that the authenticated user is tagged in.
PagedList<Video>	getVideos(PagingParameters pagedListParameters) Retrieves a list of videos that the authenticated user is tagged in.
PagedList<Video>	getVideos(String userId) Retrieves a list of up to 25 videos that a specified user is tagged in.
PagedList<Video>	getVideos(String userId, PagingParameters pagedListParameters) Retrieves a list of videos that a specified user is tagged in.
String	postPhoto(Resource photo) Uploads a photo to an album created specifically for the application.
String	postPhoto(Resource photo, String caption) Uploads a photo to an album created specifically for the application.
String	postPhoto(String albumId, Resource photo) Uploads a photo to a specific album.
String	postPhoto(String albumId, Resource photo, String caption) Uploads a photo to a specific album.
String	postVideo(Resource video) Uploads a video for the authenticated user.
String	postVideo(Resource video, String title, String description) Uploads a video for the authenticated user.
void	tagVideo(String videoId, String userId) Tags a video with the given user ID.

Method Detail

getAlbums

PagedList<Album> getAlbums()

Retrieves a list of albums belonging to the authenticated user. Requires "user_photos" permission.

Returns:

a list Albums 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_photos" permission.

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

getAlbums

PagedList<Album> getAlbums(PagingParameters pagedListParameters)

Retrieves a list of albums belonging to the authenticated user. Requires "user_photos" permission.

Parameters:

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

Returns:

a list Albums 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_photos" permission.

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

getAlbums

PagedList<Album> getAlbums(String ownerId)

Retrieves a list of albums belonging to a specific owner (user, page, etc). Requires "user_photos" permission.

Parameters:

ownerId - the album owner's ID

Returns:

a list Albums 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_photos" permission.

getAlbums

PagedList<Album> getAlbums(String ownerId,
                         PagingParameters pagedListParameters)

Retrieves a list of albums belonging to a specific owner (user, page, etc). Requires "user_photos" permission.

Parameters:

ownerId - the album owner's ID

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

Returns:

a list Albums 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_photos" permission.

getAlbum

Album getAlbum(String albumId)

Retrieves data for a specific album. Requires "user_photos" permission if the album is not public.

Parameters:

albumId - the album ID

Returns:

the requested Album object.

Throws:

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

org.springframework.social.InsufficientPermissionException - if the album is not public and if the user has not granted "user_photos" permission.

createAlbum

String createAlbum(String name,
                 String description)

Creates a new photo album. Requires "user_photos" permission.

Parameters:

name - the name of the album.

description - the album's description.

Returns:

the ID of the newly created album.

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_photos" permission.

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

createAlbum

String createAlbum(String ownerId,
                 String name,
                 String description)

Creates a new photo album. Requires "user_photos" permission.

Parameters:

ownerId - the owner of the album, possibly a page ID.

name - the name of the album.

description - the album's description.

Returns:

the ID of the newly created album.

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_photos" permission.

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

getAlbumImage

byte[] getAlbumImage(String albumId)

Retrieves an album's image as an array of bytes. Returns the image in Facebook's "normal" type. Requires "user_photos" permission if the album is not public.

Parameters:

albumId - the album ID

Returns:

an array of bytes containing the album's image.

Throws:

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

org.springframework.social.InsufficientPermissionException - if the album is not public and if the user has not granted "user_photos" permission.

getAlbumImage

byte[] getAlbumImage(String albumId,
                   ImageType imageType)

Retrieves an album's image as an array of bytes. Requires "user_photos" permission if the album is not public.

Parameters:

albumId - the album ID

imageType - the image type (eg., small, normal, large. square)

Returns:

an array of bytes containing the album's image.

Throws:

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

org.springframework.social.InsufficientPermissionException - if the album is not public and if the user has not granted "user_photos" permission.

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

getPhotos

PagedList<Photo> getPhotos(String objectId)

Retrieves data for up to 25 photos from a specific album or that a user is tagged in. If the objectId parameter is the ID of an album, the photos returned are the photos from that album. If the objectId parameter is the ID of a user, the photos returned are the photos that the user is tagged in. Requires "user_photos" permission if the album is not public.

Parameters:

objectId - either an album ID or a user ID

Returns:

a list of Photos in the specified album.

Throws:

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

org.springframework.social.InsufficientPermissionException - if the album is not public and if the user has not granted "user_photos" permission.

getPhotos

PagedList<Photo> getPhotos(String objectId,
                         PagingParameters pagedListParameters)

Retrieves photo data from a specific album or that a user is tagged in. If the objectId parameter is the ID of an album, the photos returned are the photos from that album. If the objectId parameter is the ID of a user, the photos returned are the photos that the user is tagged in. Requires "user_photos" permission if the album is not public.

Parameters:

objectId - either an album ID or a user ID

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

Returns:

a list of Photos in the specified album.

Throws:

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

org.springframework.social.InsufficientPermissionException - if the album is not public and if the user has not granted "user_photos" permission.

getPhoto

Photo getPhoto(String photoId)

Retrieve data for a specified photo. Requires "user_photos" permission if the photo is not public.

Parameters:

photoId - the photo's ID

Returns:

the requested Photo

Throws:

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

org.springframework.social.InsufficientPermissionException - if the photo is not public and if the user has not granted "user_photos" permission.

getPhotoImage

byte[] getPhotoImage(String photoId)

Retrieves a photo's image as an array of bytes. Returns the image in Facebook's "normal" type. Requires "user_photos" permission if the photo is not public.

Parameters:

photoId - the photo ID

Returns:

an array of bytes containing the photo's image.

Throws:

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

org.springframework.social.InsufficientPermissionException - if the photo is not public and if the user has not granted "user_photos" permission.

getPhotoImage

byte[] getPhotoImage(String photoId,
                   ImageType imageType)

Retrieves a photo's image as an array of bytes. Requires "user_photos" permission if the photo is not public.

Parameters:

photoId - the photo ID

imageType - the image type (eg., small, normal, large. square)

Returns:

an array of bytes containing the photo's image.

Throws:

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

org.springframework.social.InsufficientPermissionException - if the photo is not public and if the user has not granted "user_photos" permission.

postPhoto

String postPhoto(Resource photo)

Uploads a photo to an album created specifically for the application. Requires "publish_actions" permission. If no album exists for the application, it will be created.

Parameters:

photo - A Resource for the photo data. The given Resource must implement the getFilename() method (such as FileSystemResource or ClassPathResource).

Returns:

the ID of the photo.

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_actions" permission.

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

postPhoto

String postPhoto(Resource photo,
               String caption)

Uploads a photo to an album created specifically for the application. If no album exists for the application, it will be created. Requires "publish_actions" permission.

Parameters:

photo - A Resource for the photo data. The given Resource must implement the getFilename() method (such as FileSystemResource or ClassPathResource).

caption - A caption describing the photo.

Returns:

the ID of the photo.

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_actions" permission.

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

postPhoto

String postPhoto(String albumId,
               Resource photo)

Uploads a photo to a specific album. Requires "publish_actions" permission.

Parameters:

albumId - the ID of the album to upload the photo to.

photo - A Resource for the photo data. The given Resource must implement the getFilename() method (such as FileSystemResource or ClassPathResource).

Returns:

the ID of the photo.

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_actions" permission.

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

postPhoto

String postPhoto(String albumId,
               Resource photo,
               String caption)

Uploads a photo to a specific album. Requires "publish_actions" permission.

Parameters:

albumId - the ID of the album to upload the photo to.

photo - A Resource for the photo data. The given Resource must implement the getFilename() method (such as FileSystemResource or ClassPathResource).

caption - A caption describing the photo.

Returns:

the ID of the photo.

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_actions" permission.

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

getVideos

PagedList<Video> getVideos()

Retrieves a list of up to 25 videos that the authenticated user is tagged in. Requires "user_videos" permission.

Returns:

a list of Video belonging to the authenticated user.

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_videos" permission.

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

getVideos

PagedList<Video> getVideos(PagingParameters pagedListParameters)

Retrieves a list of videos that the authenticated user is tagged in. Requires "user_videos" permission.

Parameters:

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

Returns:

a list of Video belonging to the authenticated user.

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_videos" permission.

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

getVideos

PagedList<Video> getVideos(String userId)

Retrieves a list of up to 25 videos that a specified user is tagged in. Requires "user_videos" permission.

Parameters:

userId - the ID of the user who is tagged in the videos

Returns:

a list of Video which the specified user is tagged in.

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_videos" permission.

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

getVideos

PagedList<Video> getVideos(String userId,
                         PagingParameters pagedListParameters)

Retrieves a list of videos that a specified user is tagged in. Requires "user_videos" permission.

Parameters:

userId - the ID of the user who is tagged in the videos

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

Returns:

a list of Video which the specified user is tagged in.

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_videos" permission.

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

getVideo

Video getVideo(String videoId)

Retrieves data for a specific video. Requires "user_videos" permission.

Parameters:

videoId - the ID of the video.

Returns:

the requested Video data.

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_videos" permission.

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

getVideoImage

byte[] getVideoImage(String videoId)

Retrieves a video's image as an array of bytes. Returns the image in Facebook's "normal" type. Requires "user_videos" permission.

Parameters:

videoId - the video ID

Returns:

an array of bytes containing the video's image.

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_videos" permission.

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

postVideo

String postVideo(Resource video)

Uploads a video for the authenticated user. Requires "publish_actions" permission. Note that the video will not be immediately available after uploading, as Facebook performs some post-upload processing on the video.

Parameters:

video - A Resource for the video data. The given Resource must implement the getFilename() method (such as FileSystemResource or ClassPathResource).

Returns:

the ID of the video.

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_actions" permission.

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

postVideo

String postVideo(Resource video,
               String title,
               String description)

Uploads a video for the authenticated user. Note that the video will not be immediately available after uploading, as Facebook performs some post-upload processing on the video. Requires "publish_actions" permission.

Parameters:

video - A Resource for the video data. The given Resource must implement the getFilename() method (such as FileSystemResource or ClassPathResource).

title - the video title

description - the video description

Returns:

the ID of the video.

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_actions" permission.

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

tagVideo

void tagVideo(String videoId,
            String userId)

Tags a video with the given user ID.

Parameters:

videoId - the video ID

userId - the user ID