org.springframework.social.facebook.api
Interface MediaOperations

public interface MediaOperations

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

Author:

Craig Walls

Method Summary

java.lang.String	createAlbum(java.lang.String name, java.lang.String description) Creates a new photo album.
Album	getAlbum(java.lang.String albumId) Retrieves data for a specific album.
byte[]	getAlbumImage(java.lang.String albumId) Retrieves an album's image as an array of bytes.
byte[]	getAlbumImage(java.lang.String albumId, ImageType imageType) Retrieves an album's image as an array of bytes.
java.util.List<Album>	getAlbums() Retrieves a list of albums belonging to the authenticated user.
java.util.List<Album>	getAlbums(int offset, int limit) Retrieves a list of albums belonging to the authenticated user.
java.util.List<Album>	getAlbums(java.lang.String ownerId) Retrieves a list of albums belonging to a specific owner (user, page, etc).
java.util.List<Album>	getAlbums(java.lang.String ownerId, int offset, int limit) Retrieves a list of albums belonging to a specific owner (user, page, etc).
Photo	getPhoto(java.lang.String photoId) Retrieve data for a specified photo.
byte[]	getPhotoImage(java.lang.String photoId) Retrieves a photo's image as an array of bytes.
byte[]	getPhotoImage(java.lang.String photoId, ImageType imageType) Retrieves a photo's image as an array of bytes.
java.util.List<Photo>	getPhotos(java.lang.String objectId) Retrieves data for up to 25 photos from a specific album or that a user is tagged in.
java.util.List<Photo>	getPhotos(java.lang.String objectId, int offset, int limit) Retrieves photo data from a specific album or that a user is tagged in.
Video	getVideo(java.lang.String videoId) Retrieves data for a specific video.
byte[]	getVideoImage(java.lang.String videoId) Retrieves a video's image as an array of bytes.
byte[]	getVideoImage(java.lang.String videoId, ImageType imageType) Retrieves a video's image as an array of bytes.
java.util.List<Video>	getVideos() Retrieves a list of up to 25 videos that the authenticated user is tagged in.
java.util.List<Video>	getVideos(int offset, int limit) Retrieves a list of videos that the authenticated user is tagged in.
java.util.List<Video>	getVideos(java.lang.String userId) Retrieves a list of up to 25 videos that a specified user is tagged in.
java.util.List<Video>	getVideos(java.lang.String userId, int offset, int limit) Retrieves a list of videos that a specified user is tagged in.
java.lang.String	postPhoto(org.springframework.core.io.Resource photo) Uploads a photo to an album created specifically for the application.
java.lang.String	postPhoto(org.springframework.core.io.Resource photo, java.lang.String caption) Uploads a photo to an album created specifically for the application.
java.lang.String	postPhoto(java.lang.String albumId, org.springframework.core.io.Resource photo) Uploads a photo to a specific album.
java.lang.String	postPhoto(java.lang.String albumId, org.springframework.core.io.Resource photo, java.lang.String caption) Uploads a photo to a specific album.
java.lang.String	postVideo(org.springframework.core.io.Resource video) Uploads a video for the authenticated user.
java.lang.String	postVideo(org.springframework.core.io.Resource video, java.lang.String title, java.lang.String description) Uploads a video for the authenticated user.

Method Detail

getAlbums

java.util.List<Album> getAlbums()

Retrieves a list of albums belonging to the authenticated user. Requires "user_photos" or "friends_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" or "friends_photos" permission.

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

getAlbums

java.util.List<Album> getAlbums(int offset,
                                int limit)

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

Parameters:

offset - the offset into the list of albums

limit - the maximum number of albums 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" or "friends_photos" permission.

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

getAlbums

java.util.List<Album> getAlbums(java.lang.String ownerId)

Retrieves a list of albums belonging to a specific owner (user, page, etc). Requires "user_photos" or "friends_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" or "friends_photos" permission.

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

getAlbums

java.util.List<Album> getAlbums(java.lang.String ownerId,
                                int offset,
                                int limit)

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

Parameters:

ownerId - the album owner's ID

offset - the offset into the list of albums

limit - the maximum number of albums 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" or "friends_photos" permission.

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

getAlbum

Album getAlbum(java.lang.String albumId)

Retrieves data for a specific album. Requires "user_photos" or "friends_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" or "friends_photos" permission.

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

createAlbum

java.lang.String createAlbum(java.lang.String name,
                             java.lang.String description)

Creates a new photo album. Requires "publish_stream" 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 "publish_stream" permission.

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

getAlbumImage

byte[] getAlbumImage(java.lang.String albumId)

Retrieves an album's image as an array of bytes. Returns the image in Facebook's "normal" type. Requires "user_photos" or "friends_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" or "friends_photos" permission.

getAlbumImage

byte[] getAlbumImage(java.lang.String albumId,
                     ImageType imageType)

Retrieves an album's image as an array of bytes. Requires "user_photos" or "friends_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" or "friends_photos" permission.

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

getPhotos

java.util.List<Photo> getPhotos(java.lang.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" or "friends_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" or "friends_photos" permission.

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

getPhotos

java.util.List<Photo> getPhotos(java.lang.String objectId,
                                int offset,
                                int limit)

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" or "friends_photos" permission if the album is not public.

Parameters:

objectId - either an album ID or a user ID

offset - the offset into the list of photos

limit - the maximum number of photos 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" or "friends_photos" permission.

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

getPhoto

Photo getPhoto(java.lang.String photoId)

Retrieve data for a specified photo. Requires "user_photos" or "friends_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" or "friends_photos" permission.

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

getPhotoImage

byte[] getPhotoImage(java.lang.String photoId)

Retrieves a photo's image as an array of bytes. Returns the image in Facebook's "normal" type. Requires "user_photos" or "friends_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" or "friends_photos" permission.

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

getPhotoImage

byte[] getPhotoImage(java.lang.String photoId,
                     ImageType imageType)

Retrieves a photo's image as an array of bytes. Requires "user_photos" or "friends_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" or "friends_photos" permission.

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

postPhoto

java.lang.String postPhoto(org.springframework.core.io.Resource photo)

Uploads a photo to an album created specifically for the application. Requires "publish_stream" 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_stream" permission.

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

postPhoto

java.lang.String postPhoto(org.springframework.core.io.Resource photo,
                           java.lang.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_stream" 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_stream" permission.

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

postPhoto

java.lang.String postPhoto(java.lang.String albumId,
                           org.springframework.core.io.Resource photo)

Uploads a photo to a specific album. Requires "publish_stream" 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_stream" permission.

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

postPhoto

java.lang.String postPhoto(java.lang.String albumId,
                           org.springframework.core.io.Resource photo,
                           java.lang.String caption)

Uploads a photo to a specific album. Requires "publish_stream" 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_stream" permission.

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

getVideos

java.util.List<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

java.util.List<Video> getVideos(int offset,
                                int limit)

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

Parameters:

offset - the offset into the list of videos

limit - the maximum number of videos 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

java.util.List<Video> getVideos(java.lang.String userId)

Retrieves a list of up to 25 videos that a specified user is tagged in. Requires "user_videos" or "friends_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" or "friends_videos" permission.

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

getVideos

java.util.List<Video> getVideos(java.lang.String userId,
                                int offset,
                                int limit)

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

Parameters:

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

offset - the offset into the list of videos

limit - the maximum number of videos 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" or "friends_videos" permission.

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

getVideo

Video getVideo(java.lang.String videoId)

Retrieves data for a specific video. Requires "user_videos" or "friends_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" or "friends_videos" permission.

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

getVideoImage

byte[] getVideoImage(java.lang.String videoId)

Retrieves a video's image as an array of bytes. Returns the image in Facebook's "normal" type. Requires "user_videos" or "friends_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" or "friends_videos" permission.

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

getVideoImage

byte[] getVideoImage(java.lang.String videoId,
                     ImageType imageType)

Retrieves a video's image as an array of bytes. Requires "user_videos" or "friends_videos" permission.

Parameters:

videoId - the video ID

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

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" or "friends_videos" permission.

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

postVideo

java.lang.String postVideo(org.springframework.core.io.Resource video)

Uploads a video for the authenticated user. Requires "publish_stream" 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_stream" permission.

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

postVideo

java.lang.String postVideo(org.springframework.core.io.Resource video,
                           java.lang.String title,
                           java.lang.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_stream" permission.

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

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