org.agorava.twitter.TwitterDirectMessageService Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of agorava-twitter-api Show documentation
The newest version!
/*
 * Copyright 2013 Agorava
 *
 * 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.agorava.twitter;

import org.agorava.twitter.model.DirectMessage;
import org.agorava.twitter.model.InvalidMessageRecipientException;
import org.agorava.twitter.model.MessageTooLongException;

import java.util.List;

/**
 * Interface defining the Twitter operations for working with direct messages.
 *
 * @author Craig Walls
 * @author Antoine Sabot-Durand
 */
public interface TwitterDirectMessageService {

    /**
     * Retrieve the 20 most recently received direct messages for the authenticating user. The most recently received messages
     * are listed first.
     *
     * @return a collection of {@link DirectMessage} with the authenticating user as the recipient.
     * @throws MissingAuthorizationException if TwitterTemplate was not created with OAuth credentials.
     * @throws ApiException                  if there is an error while communicating with Twitter.
     */
    List getDirectMessagesReceived();

    /**
     * Retrieve received direct messages for the authenticating user. The most recently received messages are listed first.
     *
     * @param page     The page to return
     * @param pageSize The number of {@link DirectMessage}s per page. Should be less than or equal to 200. (Will return at most
     *                 200 entries, even if pageSize is greater than 200.)
     * @return a collection of {@link DirectMessage} with the authenticating user as the recipient.
     * @throws MissingAuthorizationException if TwitterTemplate was not created with OAuth credentials.
     * @throws ApiException                  if there is an error while communicating with Twitter.
     */
    List getDirectMessagesReceived(int page, int pageSize);

    /**
     * Retrieve received direct messages for the authenticating user. The most recently received messages are listed first.
     *
     * @param page     The page to return
     * @param pageSize The number of {@link DirectMessage}s per page. Should be less than or equal to 200. (Will return at most
     *                 200 entries, even if pageSize is greater than 200.)
     * @param sinceId  The minimum {@link DirectMessage} ID to return in the results
     * @param maxId    The maximum {@link DirectMessage} ID to return in the results
     * @return a collection of {@link DirectMessage} with the authenticating user as the recipient.
     * @throws MissingAuthorizationException if TwitterTemplate was not created with OAuth credentials.
     * @throws ApiException                  if there is an error while communicating with Twitter.
     */
    List getDirectMessagesReceived(int page, int pageSize, long sinceId, long maxId);

    /**
     * Retrieve the 20 most recent direct messages sent by the authenticating user. The most recently sent messages are listed
     * first.
     *
     * @return a collection of {@link DirectMessage} with the authenticating user as the sender.
     * @throws ApiException                  if there is an error while communicating with Twitter.
     * @throws MissingAuthorizationException if TwitterTemplate was not created with OAuth credentials.
     */
    List getDirectMessagesSent();

    /**
     * Retrieve direct messages sent by the authenticating user. The most recently sent messages are listed first.
     *
     * @param page     The page to return
     * @param pageSize The number of {@link DirectMessage}s per page. Should be less than or equal to 200. (Will return at most
     *                 200 entries, even if pageSize is greater than 200.)
     * @return a collection of {@link DirectMessage} with the authenticating user as the sender.
     * @throws ApiException                  if there is an error while communicating with Twitter.
     * @throws MissingAuthorizationException if TwitterTemplate was not created with OAuth credentials.
     */
    List getDirectMessagesSent(int page, int pageSize);

    /**
     * Retrieve direct messages sent by the authenticating user. The most recently sent messages are listed first.
     *
     * @param page     The page to return
     * @param pageSize The number of {@link DirectMessage}s per page. Should be less than or equal to 200. (Will return at most
     *                 200 entries, even if pageSize is greater than 200.)
     * @param sinceId  The minimum {@link DirectMessage} ID to return in the results
     * @param maxId    The maximum {@link DirectMessage} ID to return in the results
     * @return a collection of {@link DirectMessage} with the authenticating user as the sender.
     * @throws ApiException                  if there is an error while communicating with Twitter.
     * @throws MissingAuthorizationException if TwitterTemplate was not created with OAuth credentials.
     */
    List getDirectMessagesSent(int page, int pageSize, long sinceId, long maxId);

    /**
     * Gets a direct message by its ID. The message must be readable by the authenticating user.
     *
     * @param id the message ID
     * @return the direct message
     * @throws ApiException                  if there is an error while communicating with Twitter.
     * @throws MissingAuthorizationException if TwitterTemplate was not created with OAuth credentials.
     */
    DirectMessage getDirectMessage(long id);

    /**
     * Sends a direct message to another Twitter user. The recipient of the message must follow the authenticated user in order
     * for the message to be delivered. If the recipient is not following the authenticated user, an
     * {@link InvalidMessageRecipientException} will be thrown.
     *
     * @param toScreenName the screen name of the recipient of the messages.
     * @param text         the message text.
     * @return the {@link DirectMessage}
     * @throws ApiException                     if there is an error while communicating with Twitter.
     * @throws InvalidMessageRecipientException if the recipient is not following the authenticating user.
     * @throws DuplicateTweetException          if the message duplicates a previously sent message.
     * @throws MessageTooLongException          if the message length exceeds Twitter's 140 character limit.
     * @throws MissingAuthorizationException    if TwitterTemplate was not created with OAuth credentials.
     */
    DirectMessage sendDirectMessage(String toScreenName, String text);

    /**
     * Sends a direct message to another Twitter user. The recipient of the message must follow the authenticated user in order
     * for the message to be delivered. If the recipient is not following the authenticated user, an
     * {@link InvalidMessageRecipientException} will be thrown.
     *
     * @param toUserId the Twitter user ID of the recipient of the messages.
     * @param text     the message text.
     * @return the {@link DirectMessage}
     * @throws ApiException                     if there is an error while communicating with Twitter.
     * @throws InvalidMessageRecipientException if the recipient is not following the authenticating user.
     * @throws DuplicateTweetException          if the message duplicates a previously sent message.
     * @throws MessageTooLongException          if the message length exceeds Twitter's 140 character limit.
     * @throws MissingAuthorizationException    if TwitterTemplate was not created with OAuth credentials.
     */
    DirectMessage sendDirectMessage(long toUserId, String text);

    /**
     * Deletes a direct message for the authenticated user.
     *
     * @param messageId the ID of the message to be removed.
     * @throws ApiException                  if there is an error while communicating with Twitter.
     * @throws MissingAuthorizationException if TwitterTemplate was not created with OAuth credentials.
     */
    void deleteDirectMessage(long messageId);
}