org.springframework.social.facebook.api.FeedOperations Maven / Gradle / Ivy
The newest version!
/*
* Copyright 2015 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 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.
*/
PagedList getFeed();
/**
* Retrieves recent posts for the authenticated user.
* Requires "read_stream" permission to read non-public posts.
* @param pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getFeed(PagingParameters pagedListParameters);
/**
* 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.
*/
PagedList 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 pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getFeed(String ownerId, PagingParameters pagedListParameters);
/**
* 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.
*/
PagedList getHomeFeed();
/**
* Retrieves the user's home feed. This includes entries from the user's friends.
* Requires "read_stream" permission.
* @param pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getHomeFeed(PagingParameters pagedListParameters);
/**
* 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.
*/
PagedList getStatuses();
/**
* Retrieves the status entries from the authenticated user's feed.
* @param pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getStatuses(PagingParameters pagedListParameters);
/**
* 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.
*/
PagedList getStatuses(String userId);
/**
* Retrieves the status entries from the specified user's feed.
* Requires "read_stream" permission.
* @param userId the user's ID
* @param pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getStatuses(String userId, PagingParameters pagedListParameters);
/**
* 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.
*/
PagedList getLinks();
/**
* Retrieves the link entries from the authenticated user's feed.
* Requires "read_stream" permission.
* @param pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getLinks(PagingParameters pagedListParameters);
/**
* 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.
*/
PagedList 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 pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getLinks(String ownerId, PagingParameters pagedListParameters);
/**
* 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.
*/
PagedList getPosts();
/**
* Retrieves the post entries from the authenticated user's feed.
* Requires "read_stream" permission.
* @param pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getPosts(PagingParameters pagedListParameters);
/**
* 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.
*/
PagedList 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 pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getPosts(String ownerId, PagingParameters pagedListParameters);
/**
* Retrieves the post entries that the authenticated user was tagged in.
* 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.
*/
PagedList getTagged();
/**
* Retrieves the post entries that the authenticated user was tagged in.
* Requires "read_stream" permission.
* @param pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getTagged(PagingParameters pagedListParameters);
/**
* Retrieves the post entries that the specified user was tagged in.
* 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.
*/
PagedList getTagged(String ownerId);
/**
* Retrieves the post entries that the specified user was tagged in.
* Requires "read_stream" permission.
* @param ownerId the owner of the feed (could be a user, page, event, etc)
* @param pagedListParameters the parameters defining the bounds of the list 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.
*/
PagedList getTagged(String ownerId, PagingParameters pagedListParameters);
/**
* Posts a status update to the authenticated user's feed.
* Requires "publish_actions" 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_actions" 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_actions" permission.
* @param message a message to send with the link.
* @param link the {@link FacebookLink} object 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_actions" 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_actions" 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_actions" permission.
* @throws MissingAuthorizationException if FacebookTemplate was not created with an access token.
*/
String post(String ownerId, String message);
/**
* Adds a Post to a feed.
* @param post the new 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_actions" permission.
* @throws MissingAuthorizationException if FacebookTemplate was not created with an access token.
*/
String post(PostData post);
/**
* Posts a link to a feed.
* Requires "publish_actions" 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.
* @param link the {@link FacebookLink} object to post
* @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_actions" 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_actions" 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_actions" permission.
* @throws MissingAuthorizationException if FacebookTemplate was not created with an access token.
*/
void deletePost(String id);
/**
* Retrieves a list of up to 25 recent checkins for the authenticated user.
* Requires "read_stream" or "user_posts" permission.
* @return a list {@link Post}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_checkins" permission.
* @throws MissingAuthorizationException if FacebookTemplate was not created with an access token.
*/
PagedList getCheckins();
/**
* Retrieves a list of checkins for the authenticated user.
* Requires "read_stream" or "user_posts" permission.
* @param pagedListParameters the parameters defining the bounds of the list to return.
* @return a list {@link Post}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_checkins" permission.
* @throws MissingAuthorizationException if FacebookTemplate was not created with an access token.
*/
PagedList getCheckins(PagingParameters pagedListParameters);
/**
* Retrieves details for a single checkin.
* @param checkinId the checkin ID
* @return a {@link Post}
* @throws ApiException if there is an error while communicating with Facebook.
* @throws MissingAuthorizationException if FacebookTemplate was not created with an access token.
*/
Post getCheckin(String checkinId);
}