/*
* Firetweet - Twitter client for Android
*
* Copyright (C) 2012-2015 Mariotaku Lee <mariotaku.lee@gmail.com>
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package twitter4j.api;
import twitter4j.CursorPaging;
import twitter4j.PageableResponseList;
import twitter4j.Paging;
import twitter4j.ResponseList;
import twitter4j.Status;
import twitter4j.TwitterException;
import twitter4j.User;
import twitter4j.UserList;
/**
* @author Joern Huxhorn - jhuxhorn at googlemail.com
*/
public interface ListsResources {
/**
* Adds a member to a list. The authenticated user must own the list to be
* able to add members to it. Lists are limited to having 500 members. <br>
* This method calls http://api.twitter.com/1.1/lists/members/create.json
*
* @param listId The id of the list.
* @param userId The id of the user to add as a member of the list.
* @return the updated list
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/members/create">POST
* lists/members/create | Twitter Developers</a>
* @since Twitter4J 2.1.0
*/
UserList addUserListMember(long listId, long userId) throws TwitterException;
UserList addUserListMember(long listId, String userScreenName) throws TwitterException;
/**
* Adds multiple members to a list, by specifying a comma-separated list of
* member ids or screen names. The authenticated user must own the list to
* be able to add members to it. Lists are limited to having 500 members,
* and you are limited to adding up to 100 members to a list at a time with
* this method. <br>
* This method calls
* http://api.twitter.com/1.1/lists/members/create_all.json
*
* @param listId The id of the list.
* @param userIds The array of ids of the user to add as member of the list.
* up to 100 are allowed in a single request.
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/members/create_all">POST
* lists/members/create_all | Twitter Developers</a>
* @since Twitter4J 2.1.7
*/
UserList addUserListMembers(long listId, long[] userIds) throws TwitterException;
/**
* Adds multiple members to a list, by specifying a comma-separated list of
* member ids or screen names. The authenticated user must own the list to
* be able to add members to it. Lists are limited to having 500 members,
* and you are limited to adding up to 100 members to a list at a time with
* this method. <br>
* This method calls
* http://api.twitter.com/1.1/lists/members/create_all.json
*
* @param listId The id of the list.
* @param screenNames The array of screen names of the user to add as member
* of the list. up to 100 are allowed in a single request.
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/members/create_all">POST
* lists/members/create_all | Twitter Developers</a>
* @since Twitter4J 2.1.7
*/
UserList addUserListMembers(long listId, String[] screenNames) throws TwitterException;
/**
* Creates a new list for the authenticated user. Accounts are limited to 20
* lists. <br>
* This method calls http://api.twitter.com/1.1/lists/create.json
*
* @param listName The name of the list you are creating. Required.
* @param isPublicList set true if you wish to make a public list
* @param description The description of the list you are creating.
* Optional.
* @return the list that was created
* @throws twitter4j.TwitterException when Twitter service or network is
* unavailable, or the authenticated user already has 20
* lists(TwitterException.getStatusCode() == 403).
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/create ">POST
* lists/create | Twitter Developers</a>
* @since Twitter4J 2.1.0
*/
UserList createUserList(String listName, boolean isPublicList, String description) throws TwitterException;
/**
* Make the authenticated user follow the specified list. <br>
* This method calls http://api.twitter.com/1.1/list/subscribers/create.json
*
* @param listId The id of the list.
* @return the updated list
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/create">POST
* lists/subscribers/create | Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
UserList createUserListSubscription(long listId) throws TwitterException;
/**
* Removes the specified member from the list. The authenticated user must
* be the list's owner to remove members from the list. <br>
* This method calls http://api.twitter.com/1.1/lists/members/destroy.json
*
* @param listId The id of the list.
* @param userId The screen name of the member you wish to remove from the
* list.
* @return the updated list
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy">POST
* lists/members/destroy | Twitter Developers</a>
* @since Twitter4J 2.1.0
*/
UserList deleteUserListMember(long listId, long userId) throws TwitterException;
UserList deleteUserListMember(long listId, String screenName) throws TwitterException;
UserList deleteUserListMembers(long listId, long[] userIds) throws TwitterException;
UserList deleteUserListMembers(long listId, String[] screenNames) throws TwitterException;
/**
* Deletes the specified list. Must be owned by the authenticated user. <br>
* This method calls http://api.twitter.com/1.1/lists/destroy.json
*
* @param listId The id of the list to delete
* @return the deleted list
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/destroy">POST
* lists/destroy | Twitter Developers</a>
* @since Twitter4J 2.1.0
*/
UserList destroyUserList(long listId) throws TwitterException;
/**
* Unsubscribes the authenticated user form the specified list. <br>
* This method calls http://api.twitter.com/1.1/subscribers/destroy.json
*
* @param listId The id of the list.
* @return the updated list
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/destroy">POST
* lists/subscribers/destroy | Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
UserList destroyUserListSubscription(long listId) throws TwitterException;
/**
* Returns the members of the specified list. <br>
* This method calls http://api.twitter.com/1.1/lists/members.json
*
* @param listId The id of the list
* @param paging Breaks the results into pages. A single page contains 20
* lists. Provide a value of -1 to begin paging. Provide values
* as returned to in the response body's next_cursor and
* previous_cursor attributes to page back and forth in the list.
* @return the members of the specified list.
* @throws TwitterException when Twitter service or network is unavailable
* @see <a href="https://dev.twitter.com/docs/api/1.1/get/lists/members">GET
* lists/members | Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
PageableResponseList<User> getUserListMembers(long listId, CursorPaging paging) throws TwitterException;
PageableResponseList<User> getUserListMembers(String slug, long ownerId, CursorPaging paging)
throws TwitterException;
PageableResponseList<User> getUserListMembers(String slug, String ownerScreenName, CursorPaging paging)
throws TwitterException;
/**
* List the lists the authenticating user has been added to. <br>
* This method calls http://api.twitter.com/1.1/lists/memberships.json
*
* @param cursor Breaks the results into pages. A single page contains 20
* lists. Provide a value of -1 to begin paging. Provide values
* as returned to in the response body's next_cursor and
* previous_cursor attributes to page back and forth in the list.
* @return the list of lists
* @throws TwitterException when Twitter service or network is unavailable
* @throws IllegalStateException when authorization is not enabled
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/memberships">GET
* lists/memberships | Twitter Developers</a>
* @since Twitter4J 2.2.4
*/
PageableResponseList<UserList> getUserListMemberships(long cursor) throws TwitterException;
/**
* List the lists the specified user has been added to. <br>
* This method calls http://api.twitter.com/1.1/lists/memberships.json
*
* @param listMemberId The id of the list member
* @param cursor Breaks the results into pages. A single page contains 20
* lists. Provide a value of -1 to begin paging. Provide values
* as returned to in the response body's next_cursor and
* previous_cursor attributes to page back and forth in the list.
* @return the list of lists
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/memberships">GET
* lists/memberships | Twitter Developers</a>
* @since Twitter4J 2.2.4
*/
PageableResponseList<UserList> getUserListMemberships(long listMemberId, long cursor) throws TwitterException;
/**
* List the lists the specified user has been added to. <br>
* This method calls http://api.twitter.com/1.1/lists/memberships.json
*
* @param listMemberId The id of the list member
* @param cursor Breaks the results into pages. A single page contains 20
* lists. Provide a value of -1 to begin paging. Provide values
* as returned to in the response body's next_cursor and
* previous_cursor attributes to page back and forth in the list.
* @param filterToOwnedLists Whether to return just lists the authenticating
* user owns, and the user represented by listMemberId is a
* member of.
* @return the list of lists
* @throws TwitterException when Twitter service or network is unavailable
* @throws IllegalStateException when filerToOwnedLists is true but
* authorization is not enabled
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/memberships">GET
* lists/memberships | Twitter Developers</a>
* @since Twitter4J 2.2.4
*/
PageableResponseList<UserList> getUserListMemberships(long listMemberId, long cursor, boolean filterToOwnedLists)
throws TwitterException;
/**
* List the lists the specified user has been added to. <br>
* This method calls http://api.twitter.com/1.1/lists/memberships.json
*
* @param listMemberScreenName The screen name of the list member
* @param cursor Breaks the results into pages. A single page contains 20
* lists. Provide a value of -1 to begin paging. Provide values
* as returned to in the response body's next_cursor and
* previous_cursor attributes to page back and forth in the list.
* @return the list of lists
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/memberships">GET
* lists/memberships | Twitter Developers</a>
* @since Twitter4J 2.1.0
*/
PageableResponseList<UserList> getUserListMemberships(String listMemberScreenName, long cursor)
throws TwitterException;
/**
* List the lists the specified user has been added to. <br>
* This method calls http://api.twitter.com/1.1/lists/memberships.json
*
* @param listMemberScreenName The screen name of the list member
* @param cursor Breaks the results into pages. A single page contains 20
* lists. Provide a value of -1 to begin paging. Provide values
* as returned to in the response body's next_cursor and
* previous_cursor attributes to page back and forth in the list.
* @param filterToOwnedLists Whether to return just lists the authenticating
* user owns, and the user represented by listMemberScreenName is
* a member of.
* @return the list of lists
* @throws TwitterException when Twitter service or network is unavailable
* @throws IllegalStateException when filerToOwnedLists is true but
* authorization is not enabled
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/memberships">GET
* lists/memberships | Twitter Developers</a>
* @since Twitter4J 2.2.4
*/
PageableResponseList<UserList> getUserListMemberships(String listMemberScreenName, long cursor,
boolean filterToOwnedLists) throws TwitterException;
PageableResponseList<UserList> getUserListOwnerships(long cursor) throws TwitterException;
PageableResponseList<UserList> getUserListOwnerships(long listMemberId, long cursor) throws TwitterException;
PageableResponseList<UserList> getUserListOwnerships(String listMemberScreenName, long cursor)
throws TwitterException;
/**
* List the lists of the specified user. Private lists will be included if
* the authenticated users is the same as the user whose lists are being
* returned. <br>
* This method calls http://api.twitter.com/1.1/lists.json
*
* @param userId The id of the list owner
* @return the list of lists
* @throws TwitterException when Twitter service or network is unavailable
* @see <a href="https://dev.twitter.com/docs/api/1.1/get/lists">GET lists |
* Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
ResponseList<UserList> getUserLists(long userId, boolean reverse) throws TwitterException;
/**
* List the lists of the specified user. Private lists will be included if
* the authenticated users is the same as the user whose lists are being
* returned. <br>
* This method calls http://api.twitter.com/1.1/lists.json
*
* @param screenName The screen name of the user
* @return the list of lists
* @throws TwitterException when Twitter service or network is unavailable
* @see <a href="https://dev.twitter.com/docs/api/1.1/get/lists">GET lists |
* Twitter Developers</a>
* @since Twitter4J 2.1.0
*/
ResponseList<UserList> getUserLists(String screenName, boolean reverse) throws TwitterException;
/**
* Show tweet timeline for members of the specified list. <br>
* http://api.twitter.com/1.1/user/lists/list_id/statuses.json
*
* @param listId The id of the list
* @param paging controls pagination. Supports since_id, max_id, count and
* page parameters.
* @return list of statuses for members of the specified list
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/statuses">GET
* lists/statuses | Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
ResponseList<Status> getUserListStatuses(long listId, Paging paging) throws TwitterException;
ResponseList<Status> getUserListStatuses(String slug, long ownerId, Paging paging) throws TwitterException;
ResponseList<Status> getUserListStatuses(String slug, String ownerScreenName, Paging paging)
throws TwitterException;
/**
* Returns the subscribers of the specified list. <br>
* This method calls http://api.twitter.com/1.1/lists/subscribers.json
*
* @param listId The id of the list
* @param paging Breaks the results into pages. A single page contains 20
* lists. Provide a value of -1 to begin paging. Provide values
* as returned to in the response body's next_cursor and
* previous_cursor attributes to page back and forth in the list.
* @return the members of the specified list.
* @throws twitter4j.TwitterException when Twitter service or network is
* unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/subscribers">GET
* lists/subscribers | Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
PageableResponseList<User> getUserListSubscribers(long listId, CursorPaging paging) throws TwitterException;
PageableResponseList<User> getUserListSubscribers(String slug, long ownerId, CursorPaging paging)
throws TwitterException;
PageableResponseList<User> getUserListSubscribers(String slug, String ownerScreenName, CursorPaging paging)
throws TwitterException;
/**
* List the lists the specified user follows. <br>
* This method calls http://api.twitter.com/1.1/lists/subscriptions.json
*
* @param listOwnerScreenName The screen name of the list owner
* @param cursor Breaks the results into pages. A single page contains 20
* lists. Provide a value of -1 to begin paging. Provide values
* as returned to in the response body's next_cursor and
* previous_cursor attributes to page back and forth in the list.
* @return the list of lists
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/subscriptions">GET
* lists/subscriptions | Twitter Developers</a>
* @since Twitter4J 2.1.0
*/
PageableResponseList<UserList> getUserListSubscriptions(String listOwnerScreenName, long cursor)
throws TwitterException;
/**
* Show the specified list. Private lists will only be shown if the
* authenticated user owns the specified list. <br>
* This method calls http://api.twitter.com/1.1/lists/show.json
*
* @param listId The id of the list to show
* @return the specified list
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/show">https://dev.twitter.com/docs/api/1.1/get/lists/show | Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
UserList showUserList(long listId) throws TwitterException;
UserList showUserList(String slug, long ownerId) throws TwitterException;
UserList showUserList(String slug, String ownerScreenName) throws TwitterException;
/**
* Check if a user is a member of the specified list.<br>
* <br>
* This method calls http://api.twitter.com/1.1/lists/members/show.json
*
* @param listId The id of the list.
* @param userId The id of the user who you want to know is a member or not
* of the specified list.
* @return the updated list
* @throws TwitterException when Twitter service or network is unavailable ,
* or the user is not a member of the specified
* list(TwitterException.getStatusCode() returns 404 in that
* case.)
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/members/show">GET
* lists/members/show | Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
User showUserListMembership(long listId, long userId) throws TwitterException;
/**
* Check if the specified user is a subscriber of the specified list. <br>
* This method calls http://api.twitter.com/1.1/lists/subscribers/show.json
*
* @param listId The id of the list.
* @param userId The id of the user who you want to know is a member or not
* of the specified list.
* @return the updated list
* @throws TwitterException when Twitter service or network is unavailable ,
* or the user is not a member of the specified
* list(TwitterException.getStatusCode() returns 404 in that
* case.)
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/get/lists/subscribers/show">GET
* lists/subscribers/show | Twitter Developers</a>
* @since Twitter4J 2.2.3
*/
User showUserListSubscription(long listId, long userId) throws TwitterException;
/**
* Updates the specified list. <br>
* This method calls http://api.twitter.com/1.1/lists/update.json
*
* @param listId The id of the list to update.
* @param newListName What you'd like to change the list's name to.
* @param isPublicList Whether your list is public or private. Optional.
* Values can be public or private. Lists are public by default
* if no mode is specified.
* @param newDescription What you'd like to change the list description to.
* @return the updated list
* @throws TwitterException when Twitter service or network is unavailable
* @see <a
* href="https://dev.twitter.com/docs/api/1.1/post/lists/update ">POST
* lists/update | Twitter Developers</a>
* @since Twitter4J 2.1.0
*/
UserList updateUserList(long listId, String newListName, boolean isPublicList, String newDescription)
throws TwitterException;
}