From a1199f17af55df60e7f0dcddc096c5ad4ea2ffa7 Mon Sep 17 00:00:00 2001 From: Jose Alberto Hdez Date: Sun, 12 Feb 2012 11:43:21 +0100 Subject: [PATCH] SOCIALFB-45: Support paging with since and until in API binding Signed-off-by: Jose Alberto Hdez --- .../facebook/api/CommentOperations.java | 184 +- .../social/facebook/api/EventOperations.java | 483 ++--- .../social/facebook/api/FeedOperations.java | 1065 ++++++----- .../social/facebook/api/MediaOperations.java | 747 ++++---- .../social/facebook/api/PlacesOperations.java | 285 +-- .../facebook/api/impl/CommentTemplate.java | 141 +- .../facebook/api/impl/EventTemplate.java | 285 +-- .../facebook/api/impl/FeedTemplate.java | 687 ++++---- .../facebook/api/impl/MediaTemplate.java | 432 ++--- .../facebook/api/impl/PlacesTemplate.java | 200 ++- .../facebook/api/CommentTemplateTest.java | 287 +-- .../facebook/api/EventTemplateTest.java | 661 +++---- .../social/facebook/api/FeedTemplateTest.java | 1556 +++++++++-------- .../facebook/api/MediaTemplateTest.java | 989 ++++++----- .../facebook/api/PlacesTemplateTest.java | 474 ++--- 15 files changed, 4629 insertions(+), 3847 deletions(-) diff --git a/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/CommentOperations.java b/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/CommentOperations.java index 084bd4e52..42ac2f1ac 100644 --- a/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/CommentOperations.java +++ b/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/CommentOperations.java @@ -1,87 +1,97 @@ -/* - * Copyright 2011 the original author or authors. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package org.springframework.social.facebook.api; - -import java.util.List; - -import org.springframework.social.ApiException; -import org.springframework.social.InsufficientPermissionException; -import org.springframework.social.MissingAuthorizationException; - - -/** - * Defines operations for reading and posting comments to Facebook. - * @author Craig Walls - */ -public interface CommentOperations { - - /** - * Retrieves the first 25 comments for a given object. - * @param objectId the ID of the object - * @return a list of {@link Comment}s for the specified object - * @throws ApiException if there is an error while communicating with Facebook. - */ - List getComments(String objectId); - - /** - * Retrieves comments for a given object. - * @param objectId the ID of the object - * @param offset the offset into the list of comments to start retrieving comments - * @param limit the maximum number of comments to retrieve - * @return a list of {@link Comment}s for the specified object - * @throws ApiException if there is an error while communicating with Facebook. - */ - List getComments(String objectId, int offset, int limit); - - /** - * Retrieves a single comment - * @param commentId the comment ID - * @return the requested {@link Comment} - * @throws ApiException if there is an error while communicating with Facebook. - */ - Comment getComment(String commentId); - - /** - * Posts a comment on an object on behalf of the authenticated user. - * Requires "publish_stream" permission. - * @param objectId the object ID - * @param message the comment message - * @return the new comment's ID - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String addComment(String objectId, String message); - - /** - * Deletes a comment. - * Requires "publish_stream" permission. - * @param commentId the comment ID - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - void deleteComment(String commentId); - - /** - * Retrieve a list of references to users who have liked a given object. - * @param objectId - * @return a list of {@link Reference}s - * @throws ApiException if there is an error while communicating with Facebook. - */ - List getLikes(String objectId); - -} +/* + * Copyright 2011 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.social.facebook.api; + +import java.util.List; + +import org.springframework.social.ApiException; +import org.springframework.social.InsufficientPermissionException; +import org.springframework.social.MissingAuthorizationException; + + +/** + * Defines operations for reading and posting comments to Facebook. + * @author Craig Walls + */ +public interface CommentOperations { + + /** + * Retrieves the first 25 comments for a given object. + * @param objectId the ID of the object + * @return a list of {@link Comment}s for the specified object + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getComments(String objectId); + + /** + * Retrieves comments for a given object. + * @param objectId the ID of the object + * @param offset the offset into the list of comments to start retrieving comments + * @param limit the maximum number of comments to retrieve + * @return a list of {@link Comment}s for the specified object + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getComments(String objectId, int offset, int limit); + + /** + * Retrieves comments for a given object using time-based paging.. + * @param objectId the ID of the object + * @param since the date into the list of comments to start retrieving posts. + * @param until the date up to comments to be returned. + * @return a list of {@link Comment}s for the specified object + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getComments(String objectId, String since, String until); + + /** + * Retrieves a single comment + * @param commentId the comment ID + * @return the requested {@link Comment} + * @throws ApiException if there is an error while communicating with Facebook. + */ + Comment getComment(String commentId); + + /** + * Posts a comment on an object on behalf of the authenticated user. + * Requires "publish_stream" permission. + * @param objectId the object ID + * @param message the comment message + * @return the new comment's ID + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + String addComment(String objectId, String message); + + /** + * Deletes a comment. + * Requires "publish_stream" permission. + * @param commentId the comment ID + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + void deleteComment(String commentId); + + /** + * Retrieve a list of references to users who have liked a given object. + * @param objectId + * @return a list of {@link Reference}s + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getLikes(String objectId); + +} diff --git a/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/EventOperations.java b/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/EventOperations.java index 98f0638ad..a61e527e4 100644 --- a/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/EventOperations.java +++ b/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/EventOperations.java @@ -1,224 +1,259 @@ -/* - * Copyright 2011 the original author or authors. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package org.springframework.social.facebook.api; - -import java.util.List; - -import org.springframework.social.ApiException; -import org.springframework.social.InsufficientPermissionException; -import org.springframework.social.MissingAuthorizationException; - - -/** - * Defines operations for creating and reading event data as well as RSVP'ing to events on behalf of a user. - * @author Craig Walls - */ -public interface EventOperations { - - /** - * Retrieves a list of up to 25 events that the authenticated user has been invited to. - * Requires "user_events" or "friends_events" permission. - * @return a list {@link Invitation}s for the user, or an empty list if not available. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getInvitations(); - - /** - * Retrieves a list of events that the authenticated user has been invited to. - * Requires "user_events" or "friends_events" permission. - * @param offset the offset into the list of events - * @param limit the maximum number of events to return - * @return a list {@link Invitation}s for the user, or an empty list if not available. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getInvitations(int offset, int limit); - - /** - * Retrieves a list of events that the specified user has been invited to. - * Requires "user_events" or "friends_events" permission. - * @param userId the user's ID - * @return a list {@link Invitation}s for the user, or an empty list if not available. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getInvitations(String userId); - - /** - * Retrieves a list of events that the specified user has been invited to. - * Requires "user_events" or "friends_events" permission. - * @param userId the user's ID - * @param offset the offset into the list of events - * @param limit the maximum number of events to return - * @return a list {@link Invitation}s for the user, or an empty list if not available. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getInvitations(String userId, int offset, int limit); - - /** - * Retrieves event data for a specified event. - * @param eventId the event ID - * @return an {@link Event} object - * @throws ApiException if there is an error while communicating with Facebook. - */ - Event getEvent(String eventId); - - /** - * Retrieves an event's image as an array of bytes. Returns the image in Facebook's "normal" type. - * @param eventId the event ID - * @return an array of bytes containing the event's image. - * @throws ApiException if there is an error while communicating with Facebook. - */ - byte[] getEventImage(String eventId); - - /** - * Retrieves an event's image as an array of bytes. - * @param eventId the event ID - * @param imageType the image type (eg., small, normal, large. square) - * @return an array of bytes containing the event's image. - * @throws ApiException if there is an error while communicating with Facebook. - */ - byte[] getEventImage(String eventId, ImageType imageType); - - /** - * Creates an event. - * Requires "create_event" permission. - * The String passed in for start time and end time is flexible in regard to format. Some valid examples are: - *
    - *
  • 2011-04-01T15:30:00 (3:30PM on April 1, 2011)
    • - *
  • 2011-04-01 (midnight on April 1, 2011)
    • - *
  • April 1, 2011 (midnight on April 1, 2011)
    • - *
  • 17:00:00 (5:00PM today)
    • - *
  • 10-11-2011 (November 10, 2012)
    • - *
  • 10/11/2012 (October 11, 2012)
    • - *
  • 10.11.2012 (November 10, 2012)
    • - *
  • Tomorrow 2PM
    • - *
- * @param name the name of the event - * @param startTime the start time of the event. - * @param endTime the end time of the event. - * @return the newly created event's ID - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "create_event" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String createEvent(String name, String startTime, String endTime); - - /** - * Deletes an event. - * Requires "create_event" permission. - * @param eventId the ID of the event - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "create_event" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - void deleteEvent(String eventId); - - /** - * Retrieves the list of an event's invitees. - * @param eventId the event ID. - * @return a list of {@link EventInvitee}s for the event. - * @throws ApiException if there is an error while communicating with Facebook. - */ - List getInvited(String eventId); - - /** - * Retrieves the list of an event's invitees who have accepted the invitation. - * @param eventId the event ID. - * @return a list of {@link EventInvitee}s for the event. - * @throws ApiException if there is an error while communicating with Facebook. - */ - List getAttending(String eventId); - - /** - * Retrieves the list of an event's invitees who have indicated that they may attend the event. - * @param eventId the event ID. - * @return a list of {@link EventInvitee}s for the event. - * @throws ApiException if there is an error while communicating with Facebook. - */ - List getMaybeAttending(String eventId); - - /** - * Retrieves the list of an event's invitees who have not yet RSVP'd. - * @param eventId the event ID. - * @return a list of {@link EventInvitee}s for the event. - * @throws ApiException if there is an error while communicating with Facebook. - */ - List getNoReplies(String eventId); - - /** - * Retrieves the list of an event's invitees who have declined the invitation. - * @param eventId the event ID. - * @return a list of {@link EventInvitee}s for the event. - * @throws ApiException if there is an error while communicating with Facebook. - */ - List getDeclined(String eventId); - - /** - * Accepts an invitation to an event. - * Requires "rsvp_event" permission. - * @param eventId the event ID - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "rsvp_event" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - void acceptInvitation(String eventId); - - /** - * RSVPs to an event with a maybe. - * Requires "rsvp_event" permission. - * @param eventId the event ID - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "rsvp_event" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - void maybeInvitation(String eventId); - - /** - * Declines an invitation to an event. - * Requires "rsvp_event" permission. - * @param eventId the event ID - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "rsvp_event" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - void declineInvitation(String eventId); - - /** - * Search for events. - * @param query the search query (e.g., "Spring User Group") - * @return a list of {@link Event}s matching the search query - * @throws ApiException if there is an error while communicating with Facebook. - */ - List search(String query); - - /** - * Search for events. - * @param query the search query (e.g., "Spring User Group") - * @param offset the offset into the list of events - * @param limit the maximum number of events to return - * @return a list of {@link Event}s matching the search query - * @throws ApiException if there is an error while communicating with Facebook. - */ - List search(String query, int offset, int limit); - -} +/* + * Copyright 2011 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.social.facebook.api; + +import java.util.List; + +import org.springframework.social.ApiException; +import org.springframework.social.InsufficientPermissionException; +import org.springframework.social.MissingAuthorizationException; + + +/** + * Defines operations for creating and reading event data as well as RSVP'ing to events on behalf of a user. + * @author Craig Walls + */ +public interface EventOperations { + + /** + * Retrieves a list of up to 25 events that the authenticated user has been invited to. + * Requires "user_events" or "friends_events" permission. + * @return a list {@link Invitation}s for the user, or an empty list if not available. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getInvitations(); + + /** + * Retrieves a list of events that the authenticated user has been invited to. + * Requires "user_events" or "friends_events" permission. + * @param offset the offset into the list of events + * @param limit the maximum number of events to return + * @return a list {@link Invitation}s for the user, or an empty list if not available. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getInvitations(int offset, int limit); + + /** + * Retrieves a list of events that the authenticated user has been invited to using time-based paging. + * Requires "user_events" or "friends_events" permission. + * @param since the date into the list of events. + * @param until the date up to events to be returned. + * @return a list {@link Invitation}s for the user, or an empty list if not available. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getInvitations(String since, String until); + + /** + * Retrieves a list of events that the specified user has been invited to. + * Requires "user_events" or "friends_events" permission. + * @param userId the user's ID + * @return a list {@link Invitation}s for the user, or an empty list if not available. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getInvitations(String userId); + + /** + * Retrieves a list of events that the specified user has been invited to. + * Requires "user_events" or "friends_events" permission. + * @param userId the user's ID + * @param offset the offset into the list of events + * @param limit the maximum number of events to return + * @return a list {@link Invitation}s for the user, or an empty list if not available. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getInvitations(String userId, int offset, int limit); + + /** + * Retrieves a list of events that the specified user has been invited to using time-based paging. + * Requires "user_events" or "friends_events" permission. + * @param userId the user's ID + * @param since the date into the list of events. + * @param until the date up to events to be returned. + * @return a list {@link Invitation}s for the user, or an empty list if not available. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "user_events" or "friends_events" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getInvitations(String userId, String since, String until); + + /** + * Retrieves event data for a specified event. + * @param eventId the event ID + * @return an {@link Event} object + * @throws ApiException if there is an error while communicating with Facebook. + */ + Event getEvent(String eventId); + + /** + * Retrieves an event's image as an array of bytes. Returns the image in Facebook's "normal" type. + * @param eventId the event ID + * @return an array of bytes containing the event's image. + * @throws ApiException if there is an error while communicating with Facebook. + */ + byte[] getEventImage(String eventId); + + /** + * Retrieves an event's image as an array of bytes. + * @param eventId the event ID + * @param imageType the image type (eg., small, normal, large. square) + * @return an array of bytes containing the event's image. + * @throws ApiException if there is an error while communicating with Facebook. + */ + byte[] getEventImage(String eventId, ImageType imageType); + + /** + * Creates an event. + * Requires "create_event" permission. + * The String passed in for start time and end time is flexible in regard to format. Some valid examples are: + *
    + *
  • 2011-04-01T15:30:00 (3:30PM on April 1, 2011)
    • + *
  • 2011-04-01 (midnight on April 1, 2011)
    • + *
  • April 1, 2011 (midnight on April 1, 2011)
    • + *
  • 17:00:00 (5:00PM today)
    • + *
  • 10-11-2011 (November 10, 2012)
    • + *
  • 10/11/2012 (October 11, 2012)
    • + *
  • 10.11.2012 (November 10, 2012)
    • + *
  • Tomorrow 2PM
    • + *
+ * @param name the name of the event + * @param startTime the start time of the event. + * @param endTime the end time of the event. + * @return the newly created event's ID + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "create_event" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + String createEvent(String name, String startTime, String endTime); + + /** + * Deletes an event. + * Requires "create_event" permission. + * @param eventId the ID of the event + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "create_event" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + void deleteEvent(String eventId); + + /** + * Retrieves the list of an event's invitees. + * @param eventId the event ID. + * @return a list of {@link EventInvitee}s for the event. + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getInvited(String eventId); + + /** + * Retrieves the list of an event's invitees who have accepted the invitation. + * @param eventId the event ID. + * @return a list of {@link EventInvitee}s for the event. + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getAttending(String eventId); + + /** + * Retrieves the list of an event's invitees who have indicated that they may attend the event. + * @param eventId the event ID. + * @return a list of {@link EventInvitee}s for the event. + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getMaybeAttending(String eventId); + + /** + * Retrieves the list of an event's invitees who have not yet RSVP'd. + * @param eventId the event ID. + * @return a list of {@link EventInvitee}s for the event. + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getNoReplies(String eventId); + + /** + * Retrieves the list of an event's invitees who have declined the invitation. + * @param eventId the event ID. + * @return a list of {@link EventInvitee}s for the event. + * @throws ApiException if there is an error while communicating with Facebook. + */ + List getDeclined(String eventId); + + /** + * Accepts an invitation to an event. + * Requires "rsvp_event" permission. + * @param eventId the event ID + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "rsvp_event" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + void acceptInvitation(String eventId); + + /** + * RSVPs to an event with a maybe. + * Requires "rsvp_event" permission. + * @param eventId the event ID + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "rsvp_event" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + void maybeInvitation(String eventId); + + /** + * Declines an invitation to an event. + * Requires "rsvp_event" permission. + * @param eventId the event ID + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "rsvp_event" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + void declineInvitation(String eventId); + + /** + * Search for events. + * @param query the search query (e.g., "Spring User Group") + * @return a list of {@link Event}s matching the search query + * @throws ApiException if there is an error while communicating with Facebook. + */ + List search(String query); + + /** + * Search for events. + * @param query the search query (e.g., "Spring User Group") + * @param offset the offset into the list of events + * @param limit the maximum number of events to return + * @return a list of {@link Event}s matching the search query + * @throws ApiException if there is an error while communicating with Facebook. + */ + List search(String query, int offset, int limit); + + /** + * Search for events using time-based paging. + * @param query the search query (e.g., "Spring User Group") + * @param since the date into the list of events. + * @param until the date up to events to be returned. + * @return a list of {@link Event}s matching the search query + * @throws ApiException if there is an error while communicating with Facebook. + */ + List search(String query, String since, String until); + +} diff --git a/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/FeedOperations.java b/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/FeedOperations.java index fb4adbf3d..e16cb0cd0 100644 --- a/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/FeedOperations.java +++ b/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/FeedOperations.java @@ -1,443 +1,622 @@ -/* - * Copyright 2011 the original author or authors. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package org.springframework.social.facebook.api; - -import java.util.List; - -import org.springframework.social.ApiException; -import org.springframework.social.DuplicateStatusException; -import org.springframework.social.InsufficientPermissionException; -import org.springframework.social.MissingAuthorizationException; -import org.springframework.social.RateLimitExceededException; - -/** - * Interface defining operations that can be performed on a Facebook feed. - * @author Craig Walls - */ -public interface FeedOperations { - - /** - * Retrieves recent posts for the authenticated user. - * Requires "read_stream" permission to read non-public posts. - * Returns up to the most recent 25 posts. - * @return a list of {@link Post}s for the authenticated user. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getFeed(); - - /** - * Retrieves recent posts for the authenticated user. - * Requires "read_stream" permission to read non-public posts. - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of {@link Post}s for the authenticated user. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getFeed(int offset, int limit); - - /** - * Retrieves recent feed entries for a given user. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission to read non-public posts. - * @param ownerId the Facebook ID or alias for the owner (user, group, event, page, etc) of the feed. - * @return a list of {@link Post}s for the specified user. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getFeed(String ownerId); - - /** - * Retrieves recent feed entries for a given user. - * Requires "read_stream" permission to read non-public posts. - * Returns up to the most recent 25 posts. - * @param ownerId the Facebook ID or alias for the owner (user, group, event, page, etc) of the feed. - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of {@link Post}s for the specified user. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getFeed(String ownerId, int offset, int limit); - - /** - * Retrieves the user's home feed. This includes entries from the user's friends. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission. - * @return a list of {@link Post}s from the authenticated user's home feed. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getHomeFeed(); - - /** - * Retrieves the user's home feed. This includes entries from the user's friends. - * Requires "read_stream" permission. - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of {@link Post}s from the authenticated user's home feed. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getHomeFeed(int offset, int limit); - - /** - * Retrieves a single post. - * @param entryId the entry ID - * @return the requested {@link Post} - * @throws ApiException if there is an error while communicating with Facebook. - */ - Post getPost(String entryId); - - /** - * Retrieves the status entries from the authenticated user's feed. - * Returns up to the most recent 25 posts. - * @return a list of status {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getStatuses(); - - /** - * Retrieves the status entries from the authenticated user's feed. - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of status {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getStatuses(int offset, int limit); - - /** - * Retrieves the status entries from the specified user's feed. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission. - * @param userId the user's ID - * @return a list of status {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getStatuses(String userId); - - /** - * Retrieves the status entries from the specified user's feed. - * Requires "read_stream" permission. - * @param userId the user's ID - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of status {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getStatuses(String userId, int offset, int limit); - - /** - * Retrieves the link entries from the authenticated user's feed. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission. - * @return a list of link {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getLinks(); - - /** - * Retrieves the link entries from the authenticated user's feed. - * Requires "read_stream" permission. - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of link {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getLinks(int offset, int limit); - - /** - * Retrieves the link entries from the specified owner's feed. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission. - * @param ownerId the owner of the feed (could be a user, page, event, etc) - * @return a list of link {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getLinks(String ownerId); - - /** - * Retrieves the link entries from the specified owner's feed. - * Requires "read_stream" permission. - * @param ownerId the owner of the feed (could be a user, page, event, etc) - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of link {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getLinks(String ownerId, int offset, int limit); - - /** - * Retrieves the note entries from the authenticated user's feed. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission. - * @return a list of note {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getNotes(); - - /** - * Retrieves the note entries from the authenticated user's feed. - * Requires "read_stream" permission. - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of note {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getNotes(int offset, int limit); - - /** - * Retrieves the note entries from the specified owner's feed. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission. - * @param ownerId the owner of the feed (could be a user, page, event, etc) - * @return a list of note {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getNotes(String ownerId); - - /** - * Retrieves the note entries from the specified owner's feed. - * Requires "read_stream" permission. - * @param ownerId the owner of the feed (could be a user, page, event, etc) - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of note {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getNotes(String ownerId, int offset, int limit); - - /** - * Retrieves the post entries from the authenticated user's feed. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission. - * @return a list of post {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getPosts(); - - /** - * Retrieves the post entries from the authenticated user's feed. - * Requires "read_stream" permission. - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of post {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getPosts(int offset, int limit); - - /** - * Retrieves the post entries from the specified owner's feed. - * Returns up to the most recent 25 posts. - * Requires "read_stream" permission. - * @param ownerId the owner of the feed (could be a user, page, event, etc) - * @return a list of post {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getPosts(String ownerId); - - /** - * Retrieves the post entries from the specified owner's feed. - * Requires "read_stream" permission. - * @param ownerId the owner of the feed (could be a user, page, event, etc) - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of post {@link Post}s. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getPosts(String ownerId, int offset, int limit); - - /** - * Posts a status update to the authenticated user's feed. - * Requires "publish_stream" permission. - * @param message the message to post. - * @return the ID of the new feed entry. - * @throws DuplicateStatusException if the status message duplicates a previously posted status. - * @throws RateLimitExceededException if the per-user/per-app rate limit is exceeded. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String updateStatus(String message); - - /** - * Posts a link to the authenticated user's feed. - * Requires "publish_stream" permission. - * @param message a message to send with the link. - * @return the ID of the new feed entry. - * @throws DuplicateStatusException if the post duplicates a previous post. - * @throws RateLimitExceededException if the per-user/per-app rate limit is exceeded. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String postLink(String message, FacebookLink link); - - /** - * Posts a message to a feed. - * Requires "publish_stream" permission. - * @param ownerId the feed owner ID. Could be a user ID or a page ID. - * @param message the message to post. - * @return the id of the new feed entry. - * @throws DuplicateStatusException if the post duplicates a previous post. - * @throws RateLimitExceededException if the per-user/per-app rate limit is exceeded. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String post(String ownerId, String message); - - /** - * Posts a link to a feed. - * Requires "publish_stream" permission. - * @param ownerId the feed owner ID. Could be a user ID or a page ID. - * @param message a message to send with the link. - * @return the ID of the new feed entry. - * @throws DuplicateStatusException if the post duplicates a previous post. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String postLink(String ownerId, String message, FacebookLink link); - - /** - * Deletes a post. - * Requires "publish_stream" permission and the post must have been created by the same application. - * @param id the feed entry ID - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - void deletePost(String id); - - /** - * Searches Facebook's public feed. - * Returns up to 25 posts that match the query. - * @param query the search query (e.g., "Dr Seuss") - * @return a list of {@link Post}s that match the search query - * @throws ApiException if there is an error while communicating with Facebook. - */ - List searchPublicFeed(String query); - - /** - * Searches Facebook's public feed. - * @param query the search query (e.g., "Dr Seuss") - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of {@link Post}s that match the search query - * @throws ApiException if there is an error while communicating with Facebook. - */ - List searchPublicFeed(String query, int offset, int limit); - - /** - * Searches the authenticated user's home feed. - * Returns up to 25 posts that match the query. - * @param query the search query (e.g., "Dr Seuss") - * @return a list of {@link Post}s that match the search query - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List searchHomeFeed(String query); - - /** - * Searches the authenticated user's home feed. - * @param query the search query (e.g., "Dr Seuss") - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of {@link Post}s that match the search query - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List searchHomeFeed(String query, int offset, int limit); - - /** - * Searches the authenticated user's feed. - * Returns up to 25 posts that match the query. - * @param query the search query (e.g., "football") - * @return a list of {@link Post}s that match the search query - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List searchUserFeed(String query); - - /** - * Searches the authenticated user's feed. - * @param query the search query (e.g., "football") - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of {@link Post}s that match the search query - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List searchUserFeed(String query, int offset, int limit); - - /** - * Searches a specified user's feed. - * Returns up to 25 posts that match the query. - * @param userId the ID of the user whose feed is to be searched - * @param query the search query (e.g., "football") - * @return a list of {@link Post}s that match the search query - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List searchUserFeed(String userId, String query); - - /** - * Searches a specified user's feed. - * @param userId the ID of the user whose feed is to be searched - * @param query the search query (e.g., "football") - * @param offset the offset into the feed to start retrieving posts. - * @param limit the maximum number of posts to return. - * @return a list of {@link Post}s that match the search query - * @throws ApiException if there is an error while communicating with Facebook. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List searchUserFeed(String userId, String query, int offset, int limit); - -} +/* + * Copyright 2011 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.social.facebook.api; + +import java.util.List; + +import org.springframework.social.ApiException; +import org.springframework.social.DuplicateStatusException; +import org.springframework.social.InsufficientPermissionException; +import org.springframework.social.MissingAuthorizationException; +import org.springframework.social.RateLimitExceededException; + +/** + * Interface defining operations that can be performed on a Facebook feed. + * @author Craig Walls + */ +public interface FeedOperations { + + /** + * Retrieves recent posts for the authenticated user. + * Requires "read_stream" permission to read non-public posts. + * Returns up to the most recent 25 posts. + * @return a list of {@link Post}s for the authenticated user. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getFeed(); + + /** + * Retrieves recent posts for the authenticated user. + * Requires "read_stream" permission to read non-public posts. + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of {@link Post}s for the authenticated user. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getFeed(int offset, int limit); + + /** + * Retrieves recent posts for the authenticated user using time-based paging. + * Requires "read_stream" permission to read non-public posts. + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of {@link Post}s for the authenticated user. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getFeed(String since, String until); + + /** + * Retrieves recent feed entries for a given user. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission to read non-public posts. + * @param ownerId the Facebook ID or alias for the owner (user, group, event, page, etc) of the feed. + * @return a list of {@link Post}s for the specified user. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getFeed(String ownerId); + + /** + * Retrieves recent feed entries for a given user. + * Requires "read_stream" permission to read non-public posts. + * Returns up to the most recent 25 posts. + * @param ownerId the Facebook ID or alias for the owner (user, group, event, page, etc) of the feed. + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of {@link Post}s for the specified user. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getFeed(String ownerId, int offset, int limit); + + /** + * Retrieves recent feed entries for a given user using time-based paging. + * Requires "read_stream" permission to read non-public posts. + * Returns up to the most recent 25 posts between since and until dates being the most recent the first element in the list. + * @param ownerId the Facebook ID or alias for the owner (user, group, event, page, etc) of the feed. + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of {@link Post}s for the specified user. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getFeed(String ownerId, String since, String until); + + /** + * Retrieves the user's home feed. This includes entries from the user's friends. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission. + * @return a list of {@link Post}s from the authenticated user's home feed. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getHomeFeed(); + + /** + * Retrieves the user's home feed. This includes entries from the user's friends. + * Requires "read_stream" permission. + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of {@link Post}s from the authenticated user's home feed. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getHomeFeed(int offset, int limit); + + + /** + * Retrieves the user's home feed using time-based paging. This includes entries from the user's friends. + * Requires "read_stream" permission. + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of {@link Post}s from the authenticated user's home feed. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getHomeFeed(String since, String until); + + /** + * Retrieves a single post. + * @param entryId the entry ID + * @return the requested {@link Post} + * @throws ApiException if there is an error while communicating with Facebook. + */ + Post getPost(String entryId); + + /** + * Retrieves the status entries from the authenticated user's feed. + * Returns up to the most recent 25 posts. + * @return a list of status {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getStatuses(); + + /** + * Retrieves the status entries from the authenticated user's feed. + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of status {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getStatuses(int offset, int limit); + + /** + * Retrieves the status entries from the authenticated user's feed using time-based paging. + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of status {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getStatuses(String since, String until); + + /** + * Retrieves the status entries from the specified user's feed. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission. + * @param userId the user's ID + * @return a list of status {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getStatuses(String userId); + + /** + * Retrieves the status entries from the specified user's feed. + * Requires "read_stream" permission. + * @param userId the user's ID + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of status {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getStatuses(String userId, int offset, int limit); + + /** + * Retrieves the status entries from the specified user's feed using time-based paging. + * Requires "read_stream" permission. + * @param userId the user's ID + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of status {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getStatuses(String userId, String since, String until); + + /** + * Retrieves the link entries from the authenticated user's feed. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission. + * @return a list of link {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getLinks(); + + /** + * Retrieves the link entries from the authenticated user's feed. + * Requires "read_stream" permission. + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of link {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getLinks(int offset, int limit); + + /** + * Retrieves the link entries from the authenticated user's feed using time-based paging. + * Requires "read_stream" permission. + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of link {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getLinks(String since, String until); + + /** + * Retrieves the link entries from the specified owner's feed. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @return a list of link {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getLinks(String ownerId); + + /** + * Retrieves the link entries from the specified owner's feed. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of link {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getLinks(String ownerId, int offset, int limit); + + /** + * Retrieves the link entries from the specified owner's feed using time-based paging. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of link {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getLinks(String ownerId, String since, String until); + + /** + * Retrieves the note entries from the authenticated user's feed. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission. + * @return a list of note {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getNotes(); + + /** + * Retrieves the note entries from the authenticated user's feed. + * Requires "read_stream" permission. + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of note {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getNotes(int offset, int limit); + + /** + * Retrieves the note entries from the authenticated user's feed using time-based paging. + * Requires "read_stream" permission. + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of note {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getNotes(String since, String until); + + /** + * Retrieves the note entries from the specified owner's feed. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @return a list of note {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getNotes(String ownerId); + + /** + * Retrieves the note entries from the specified owner's feed. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of note {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getNotes(String ownerId, int offset, int limit); + + /** + * Retrieves the note entries from the specified owner's feed using time-based paging. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of note {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getNotes(String ownerId, String since, String until); + + /** + * Retrieves the post entries from the authenticated user's feed. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission. + * @return a list of post {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getPosts(); + + /** + * Retrieves the post entries from the authenticated user's feed. + * Requires "read_stream" permission. + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of post {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getPosts(int offset, int limit); + + /** + * Retrieves the post entries from the authenticated user's feed using time-based paging. + * Requires "read_stream" permission. + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of post {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getPosts(String since, String until); + + /** + * Retrieves the post entries from the specified owner's feed. + * Returns up to the most recent 25 posts. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @return a list of post {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getPosts(String ownerId); + + /** + * Retrieves the post entries from the specified owner's feed. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of post {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getPosts(String ownerId, int offset, int limit); + + /** + * Retrieves the post entries from the specified owner's feed. + * Requires "read_stream" permission. + * @param ownerId the owner of the feed (could be a user, page, event, etc) + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of post {@link Post}s. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "read_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List getPosts(String ownerId, String since, String until); + + /** + * Posts a status update to the authenticated user's feed. + * Requires "publish_stream" permission. + * @param message the message to post. + * @return the ID of the new feed entry. + * @throws DuplicateStatusException if the status message duplicates a previously posted status. + * @throws RateLimitExceededException if the per-user/per-app rate limit is exceeded. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + String updateStatus(String message); + + /** + * Posts a link to the authenticated user's feed. + * Requires "publish_stream" permission. + * @param message a message to send with the link. + * @return the ID of the new feed entry. + * @throws DuplicateStatusException if the post duplicates a previous post. + * @throws RateLimitExceededException if the per-user/per-app rate limit is exceeded. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + String postLink(String message, FacebookLink link); + + /** + * Posts a message to a feed. + * Requires "publish_stream" permission. + * @param ownerId the feed owner ID. Could be a user ID or a page ID. + * @param message the message to post. + * @return the id of the new feed entry. + * @throws DuplicateStatusException if the post duplicates a previous post. + * @throws RateLimitExceededException if the per-user/per-app rate limit is exceeded. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + String post(String ownerId, String message); + + /** + * Posts a link to a feed. + * Requires "publish_stream" permission. + * @param ownerId the feed owner ID. Could be a user ID or a page ID. + * @param message a message to send with the link. + * @return the ID of the new feed entry. + * @throws DuplicateStatusException if the post duplicates a previous post. + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + String postLink(String ownerId, String message, FacebookLink link); + + /** + * Deletes a post. + * Requires "publish_stream" permission and the post must have been created by the same application. + * @param id the feed entry ID + * @throws ApiException if there is an error while communicating with Facebook. + * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + void deletePost(String id); + + /** + * Searches Facebook's public feed. + * Returns up to 25 posts that match the query. + * @param query the search query (e.g., "Dr Seuss") + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + */ + List searchPublicFeed(String query); + + /** + * Searches Facebook's public feed. + * @param query the search query (e.g., "Dr Seuss") + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + */ + List searchPublicFeed(String query, int offset, int limit); + + /** + * Searches Facebook's public feed. + * @param query the search query (e.g., "Dr Seuss") + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + */ + List searchPublicFeed(String query, String since, String until); + + /** + * Searches the authenticated user's home feed. + * Returns up to 25 posts that match the query. + * @param query the search query (e.g., "Dr Seuss") + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchHomeFeed(String query); + + /** + * Searches the authenticated user's home feed. + * @param query the search query (e.g., "Dr Seuss") + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchHomeFeed(String query, int offset, int limit); + + /** + * Searches the authenticated user's home feed. + * @param query the search query (e.g., "Dr Seuss") + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchHomeFeed(String query, String since, String until); + + /** + * Searches the authenticated user's feed. + * Returns up to 25 posts that match the query. + * @param query the search query (e.g., "football") + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchUserFeed(String query); + + /** + * Searches the authenticated user's feed. + * @param query the search query (e.g., "football") + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchUserFeed(String query, int offset, int limit); + + /** + * Searches the authenticated user's feed. + * @param query the search query (e.g., "football") + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchUserFeed(String query, String since, String until); + + /** + * Searches a specified user's feed. + * Returns up to 25 posts that match the query. + * @param userId the ID of the user whose feed is to be searched + * @param query the search query (e.g., "football") + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchUserFeed(String userId, String query); + + /** + * Searches a specified user's feed. + * @param userId the ID of the user whose feed is to be searched + * @param query the search query (e.g., "football") + * @param offset the offset into the feed to start retrieving posts. + * @param limit the maximum number of posts to return. + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchUserFeed(String userId, String query, int offset, int limit); + + /** + * Searches a specified user's feed. + * @param userId the ID of the user whose feed is to be searched + * @param query the search query (e.g., "football") + * @param since the date into the feed to start retrieving posts. + * @param until the date up to posts to be returned. + * @return a list of {@link Post}s that match the search query + * @throws ApiException if there is an error while communicating with Facebook. + * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. + */ + List searchUserFeed(String userId, String query, String since, String until); + +} diff --git a/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/MediaOperations.java b/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/MediaOperations.java index 65ac6cf98..b6895ca31 100644 --- a/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/MediaOperations.java +++ b/spring-social-facebook/src/main/java/org/springframework/social/facebook/api/MediaOperations.java @@ -1,341 +1,406 @@ -/* - * Copyright 2011 the original author or authors. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -package org.springframework.social.facebook.api; - -import java.util.List; - -import org.springframework.core.io.ClassPathResource; -import org.springframework.core.io.FileSystemResource; -import org.springframework.core.io.Resource; -import org.springframework.social.ApiException; -import org.springframework.social.InsufficientPermissionException; -import org.springframework.social.MissingAuthorizationException; - - -/** - * Defines operations for working with albums, photos, and videos. - * @author Craig Walls - */ -public interface MediaOperations { - - /** - * Retrieves a list of albums belonging to the authenticated user. - * Requires "user_photos" or "friends_photos" permission. - * @return a list {@link Album}s for the user, or an empty list if not available. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getAlbums(); - - /** - * Retrieves a list of albums belonging to the authenticated user. - * Requires "user_photos" or "friends_photos" permission. - * @param offset the offset into the list of albums - * @param limit the maximum number of albums to return - * @return a list {@link Album}s for the user, or an empty list if not available. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getAlbums(int offset, int limit); - - /** - * Retrieves a list of albums belonging to a specific owner (user, page, etc). - * Requires "user_photos" or "friends_photos" permission. - * @param ownerId the album owner's ID - * @return a list {@link Album}s for the user, or an empty list if not available. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getAlbums(String ownerId); - - /** - * Retrieves a list of albums belonging to a specific owner (user, page, etc). - * Requires "user_photos" or "friends_photos" permission. - * @param ownerId the album owner's ID - * @param offset the offset into the list of albums - * @param limit the maximum number of albums to return - * @return a list {@link Album}s for the user, or an empty list if not available. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getAlbums(String ownerId, int offset, int limit); - - /** - * Retrieves data for a specific album. - * Requires "user_photos" or "friends_photos" permission if the album is not public. - * @param albumId the album ID - * @return the requested {@link Album} object. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the album is not public and if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - Album getAlbum(String albumId); - - /** - * Creates a new photo album. - * Requires "publish_stream" permission. - * @param name the name of the album. - * @param description the album's description. - * @return the ID of the newly created album. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String createAlbum(String name, String description); - - /** - * 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. - * @param albumId the album ID - * @return an array of bytes containing the album's image. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the album is not public and if the user has not granted "user_photos" or "friends_photos" permission. - */ - byte[] getAlbumImage(String albumId); - - /** - * Retrieves an album's image as an array of bytes. - * Requires "user_photos" or "friends_photos" permission if the album is not public. - * @param albumId the album ID - * @param imageType the image type (eg., small, normal, large. square) - * @return an array of bytes containing the album's image. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the album is not public and if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - byte[] getAlbumImage(String albumId, ImageType imageType); - - /** - * 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. - * @param objectId either an album ID or a user ID - * @return a list of {@link Photo}s in the specified album. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the album is not public and if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getPhotos(String objectId); - - /** - * 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. - * @param objectId either an album ID or a user ID - * @param offset the offset into the list of photos - * @param limit the maximum number of photos to return - * @return a list of {@link Photo}s in the specified album. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the album is not public and if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List getPhotos(String objectId, int offset, int limit); - - /** - * Retrieve data for a specified photo. - * Requires "user_photos" or "friends_photos" permission if the photo is not public. - * @param photoId the photo's ID - * @return the requested {@link Photo} - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the photo is not public and if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - Photo getPhoto(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. - * @param photoId the photo ID - * @return an array of bytes containing the photo's image. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the photo is not public and if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - byte[] getPhotoImage(String photoId); - - /** - * Retrieves a photo's image as an array of bytes. - * Requires "user_photos" or "friends_photos" permission if the photo is not public. - * @param photoId the photo ID - * @param imageType the image type (eg., small, normal, large. square) - * @return an array of bytes containing the photo's image. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the photo is not public and if the user has not granted "user_photos" or "friends_photos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - byte[] getPhotoImage(String photoId, ImageType imageType); - - /** - * 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. - * @param photo A {@link Resource} for the photo data. The given Resource must implement the getFilename() method (such as {@link FileSystemResource} or {@link ClassPathResource}). - * @return the ID of the photo. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String postPhoto(Resource photo); - - /** - * 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. - * @param photo A {@link Resource} for the photo data. The given Resource must implement the getFilename() method (such as {@link FileSystemResource} or {@link ClassPathResource}). - * @param caption A caption describing the photo. - * @return the ID of the photo. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String postPhoto(Resource photo, String caption); - - /** - * Uploads a photo to a specific album. - * Requires "publish_stream" permission. - * @param albumId the ID of the album to upload the photo to. - * @param photo A {@link Resource} for the photo data. The given Resource must implement the getFilename() method (such as {@link FileSystemResource} or {@link ClassPathResource}). - * @return the ID of the photo. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String postPhoto(String albumId, Resource photo); - - /** - * Uploads a photo to a specific album. - * Requires "publish_stream" permission. - * @param albumId the ID of the album to upload the photo to. - * @param photo A {@link Resource} for the photo data. The given Resource must implement the getFilename() method (such as {@link FileSystemResource} or {@link ClassPathResource}). - * @param caption A caption describing the photo. - * @return the ID of the photo. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "publish_stream" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - String postPhoto(String albumId, Resource photo, String caption); - - /** - * Retrieves a list of up to 25 videos that the authenticated user is tagged in. - * Requires "user_videos" permission. - * @return a list of {@link Video} belonging to the authenticated user. - * @throws ApiException if there is an error while communicating with Facebook. - * @throws InsufficientPermissionException if the user has not granted "user_videos" permission. - * @throws MissingAuthorizationException if FacebookTemplate was not created with an access token. - */ - List