Permalink
Browse files

Javadoc for all Operations interfaces

  • Loading branch information...
1 parent dbaf668 commit 33d0f12f80ba45eff09187a37a792cd802e69c30 @magott committed Oct 13, 2011
@@ -19,6 +19,8 @@
/**
* @author Morten Andersen-Gott
+ *
+ * Represents a group on Yammer
*
*/
public class Group {
@@ -17,8 +17,10 @@
import java.util.List;
+import org.springframework.social.ResourceNotFoundException;
/**
+ * Sub-API for all Group related methods
* @author Morten Andersen-Gott
*
*/
@@ -58,26 +60,43 @@
* @param letter
* return groups beginning with the given letter
* @param sortBy
- * sort key. Valid values are messages | members | privacy |
- * created_at | creator
+ * sort key. Valid values are {@value #SORT_BY_CREATOR} | {@value #SORT_BY_MEMBERS} | {@value #SORT_BY_PRIVACY} |
+ * {@value #SORT_BY_CREATED_AT} | {@value #SORT_BY_MESSAGES}.
+ * Use convenience constants
* @param reverse
* indicating whether sort should be reversed
- * @return
+ * @return <code>List</code> of {@link Group}s
*/
List<Group> getGroups(int page, Character letter, String sortBy, boolean reverse);
/**
* Returns the group with the given id
*
* @param groupId
- * @return
+ * @return Group for given id
+ * @throws ResourceNotFoundException if there is no group with the given id in the network
*/
Group getGroup(long groupId);
-
+
+ /**
+ * Create a new group
+ * @param name of group
+ * @param isPrivate whether the group is public (anyone can join) or private
+ */
void createGroup(String name, boolean isPrivate);
- public abstract void leaveGroup(long groupId);
+ /**
+ * Join group with given group id
+ * @param groupId
+ * @throws ResourceNotFoundException if you are not a member of that group or group does not exist
+ */
+ void leaveGroup(long groupId);
- public abstract void joinGroup(long groupId);
+ /**
+ * Join a group with given group id
+ * @param groupId
+ * @throws ResourceNotFoundException if that group does not exist in your network
+ */
+ void joinGroup(long groupId);
}
@@ -15,72 +15,219 @@
*/
package org.springframework.social.yammer.api;
+import org.springframework.social.OperationNotPermittedException;
import org.springframework.social.yammer.api.impl.YammerPostDetails;
/**
+ * Sub-API for all message related operations
* @author Morten Andersen-Gott
- *
+ *
*/
public interface MessageOperations {
-
+
/**
- * Convenience constant for viewing messages by thread.
- * Will return first message of each thread.
+ * Convenience constant for viewing messages by thread. Will return first
+ * message of each thread.
*/
public static final String THREADED = "true";
-
+
/**
- * Convenience constant for viewing messages as extended threads.
- * Will return first message of each thread and the last two messages of each thread.
+ * Convenience constant for viewing messages as extended threads. Will
+ * return first message of each thread and the last two messages of each
+ * thread.
*/
public static final String THREADED_EXTENDED = "extended";
-
+
/**
- * Convenience constant not threading
- * Will return first message of each thread and the last two messages of each thread.
+ * Convenience constant not threading Will return first message of each
+ * thread and the last two messages of each thread.
*/
public static final String NO_THREADING = null;
MessageInfo getMessages(long olderThan, long newerThan, String threadedView, int limit);
void like(long messageId);
-
+
void unlike(long messageId);
-
+
/**
+ * Gets the message posted by a given user
*
* @param userId
+ * the user id you want to see the messages for
* @param olderThan
+ * return only messages older than this message id
* @param newerThan
- * @param threadedView type of threaded view or null if no threaded view is required.
- * @param limit
+ * return only messages newer than this message id
+ * @param threadedView
+ * type of threaded view or null if no threaded view is required.
+ * Valid values are:
+ * {@link #THREADED_EXTENDED}: return first message of thread and two most recent messages of thread,
+ * {@link #THREADED}: returns first message of each thread,
+ * {@link #NO_THREADING}: no threading
+ * @param limit the limit of number of messages returned (50 max)
* @return MessageInfo containing meta data and a list of messages
*
* @see #THREADED
* @see #THREADED_EXTENDED
+ * @see #NO_THREADING
*/
MessageInfo getMessagesFromUser(long userId, long olderThan, long newerThan, String threadedView, int limit);
+ /**
+ * Gets your private messages
+ *
+ * @param olderThan
+ * return only messages older than this message id
+ * @param newerThan
+ * return only messages newer than this message id
+ * @param threadedView
+ * type of threaded view or null if no threaded view is required.
+ * Valid values are:
+ * {@link #THREADED_EXTENDED}: return first message of thread and two most recent messages of thread,
+ * {@link #THREADED}: returns first message of each thread,
+ * {@link #NO_THREADING}: no threading
+ * @param limit the limit of number of messages returned (50 max)
+ * @return MessageInfo containing meta data and a list of messages
+ *
+ * @see #THREADED
+ * @see #THREADED_EXTENDED
+ * @see #NO_THREADING
+ */
MessageInfo getMessagesPrivate(long olderThan, long newerThan, String threadedView, int limit);
- MessageInfo getMessagesSent(long olderThan, long newerThan, String threaded, int limit);
+ /**
+ * Gets your sent messages
+ *
+ * @param olderThan
+ * return only messages older than this message id
+ * @param newerThan
+ * return only messages newer than this message id
+ * @param threadedView
+ * type of threaded view or null if no threaded view is required.
+ * Valid values are:
+ * {@link #THREADED_EXTENDED}: return first message of thread and two most recent messages of thread,
+ * {@link #THREADED}: returns first message of each thread,
+ * {@link #NO_THREADING}: no threading
+ * @param limit the limit of number of messages returned (50 max)
+ * @return MessageInfo containing meta data and a list of messages
+ *
+ * @see #THREADED
+ * @see #THREADED_EXTENDED
+ * @see #NO_THREADING
+ */
+ MessageInfo getMessagesSent(long olderThan, long newerThan, String threadedView, int limit);
- MessageInfo getMessagesFollowing(long olderThan, long newerThan, String threaded, int limit);
+ /**
+ * Gets messages from groups, topics and users you are following
+ *
+ * @param olderThan
+ * return only messages older than this message id
+ * @param newerThan
+ * return only messages newer than this message id
+ * @param threadedView
+ * type of threaded view or null if no threaded view is required.
+ * Valid values are:
+ * {@link #THREADED_EXTENDED}: return first message of thread and two most recent messages of thread,
+ * {@link #THREADED}: returns first message of each thread,
+ * {@link #NO_THREADING}: no threading
+ * @param limit the limit of number of messages returned (50 max)
+ * @return MessageInfo containing meta data and a list of messages
+ *
+ * @see #THREADED
+ * @see #THREADED_EXTENDED
+ * @see #NO_THREADING
+ */
+ MessageInfo getMessagesFollowing(long olderThan, long newerThan, String threadedView, int limit);
- MessageInfo getMessagesReceived(long olderThan, long newerThan, String threaded, int limit);
+ /**
+ * Gets messages you've received
+ *
+ * @param olderThan
+ * return only messages older than this message id
+ * @param newerThan
+ * return only messages newer than this message id
+ * @param threadedView
+ * type of threaded view or null if no threaded view is required.
+ * Valid values are:
+ * {@link #THREADED_EXTENDED}: return first message of thread and two most recent messages of thread,
+ * {@link #THREADED}: returns first message of each thread,
+ * {@link #NO_THREADING}: no threading
+ * @param limit the limit of number of messages returned (50 max)
+ * @return MessageInfo containing meta data and a list of messages
+ *
+ * @see #THREADED
+ * @see #THREADED_EXTENDED
+ * @see #NO_THREADING
+ */
+ MessageInfo getMessagesReceived(long olderThan, long newerThan, String threadedView, int limit);
- MessageInfo getMessagesAboutTopic(long topicId, long olderThan, long newerThan, String threaded, int limit);
+ /**
+ * Gets messages on a specified topic
+ *
+ * @param topicId the id of the topic for which you want to see messages
+ * @param olderThan
+ * return only messages older than this message id
+ * @param newerThan
+ * return only messages newer than this message id
+ * @param threadedView
+ * type of threaded view or null if no threaded view is required.
+ * Valid values are:
+ * {@link #THREADED_EXTENDED}: return first message of thread and two most recent messages of thread,
+ * {@link #THREADED}: returns first message of each thread,
+ * {@link #NO_THREADING}: no threading
+ * @param limit the limit of number of messages returned (50 max)
+ * @return MessageInfo containing meta data and a list of messages
+ *
+ * @see #THREADED
+ * @see #THREADED_EXTENDED
+ * @see #NO_THREADING
+ */
+ MessageInfo getMessagesAboutTopic(long topicId, long olderThan, long newerThan, String threadedView, int limit);
- MessageInfo getMessagesLikedByUser(long userId, long olderThan, long newerThan, String threaded, int limit);
+ /**
+ * Gets messages liked by a specified user
+ *
+ * @param userId of the person who've liked the messages
+ * @param olderThan
+ * return only messages older than this message id
+ * @param newerThan
+ * return only messages newer than this message id
+ * @param threadedView
+ * type of threaded view or null if no threaded view is required.
+ * Valid values are:
+ * {@link #THREADED_EXTENDED}: return first message of thread and two most recent messages of thread,
+ * {@link #THREADED}: returns first message of each thread,
+ * {@link #NO_THREADING}: no threading
+ * @param limit the limit of number of messages returned (50 max)
+ * @return MessageInfo containing meta data and a list of messages
+ *
+ * @see #THREADED
+ * @see #THREADED_EXTENDED
+ * @see #NO_THREADING
+ */
+ MessageInfo getMessagesLikedByUser(long userId, long olderThan, long newerThan, String threadedView, int limit);
+ /**
+ * Post an update to your network with details (ie attachments etc)
+ * @param message the text part of your message
+ * @param details additional details for your message
+ * @return MessageInfo containing meta data and your newly posted message
+ */
MessageInfo postUpdate(String message, YammerPostDetails details);
+ /**
+ * Post a textual message to your network
+ * @param message
+ * @return MessageInfo containing meta data and your newly posted message
+ */
MessageInfo postUpdate(String message);
-
+
/**
* Deletes a message, current user must be owner
- * Bad request (400) in case of not owner or no such message
+ *
* @param messageId
+ * @throws OperationNotPermittedException if the message does not exist or you are not the owner of that message
*/
void delete(long messageId);
@@ -17,15 +17,34 @@
/**
+ * Sub-API for search operations
* @author Morten Andersen-Gott
*
*/
public interface SearchOperations {
+ /**
+ * Search among messages, users, tags and groups for the given string
+ * @param searchString
+ * @return search results potentially containing messages, users, tags and groups as well as stats
+ */
SearchResults search(String searchString);
+ /**
+ * Search among messages, users, tags and groups for the given string
+ * @param searchString
+ * @param page the page number in the search result (max 50 results per page)
+ * @return search results potentially containing messages, users, tags and groups as well as stats
+ */
SearchResults search(String searchString, int page);
+ /**
+ * Search among messages, users, tags and groups for the given string
+ * @param searchString
+ * @param page the page number in the search result
+ * @param numberPerPage number of results per page (max 50)
+ * @return search results potentially containing messages, users, tags and groups as well as stats
+ */
SearchResults search(String searchString, int page, int numberPerPage);
}
Oops, something went wrong.

0 comments on commit 33d0f12

Please sign in to comment.