Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Javadoc for all Operations interfaces

  • Loading branch information...
commit 33d0f12f80ba45eff09187a37a792cd802e69c30 1 parent dbaf668
@magott authored
View
2  spring-social-yammer/src/main/java/org/springframework/social/yammer/api/Group.java
@@ -19,6 +19,8 @@
/**
* @author Morten Andersen-Gott
+ *
+ * Represents a group on Yammer
*
*/
public class Group {
View
33 spring-social-yammer/src/main/java/org/springframework/social/yammer/api/GroupOperations.java
@@ -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,11 +60,12 @@
* @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);
@@ -70,14 +73,30 @@
* 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);
}
View
189 spring-social-yammer/src/main/java/org/springframework/social/yammer/api/MessageOperations.java
@@ -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);
View
19 spring-social-yammer/src/main/java/org/springframework/social/yammer/api/SearchOperations.java
@@ -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);
}
View
38 spring-social-yammer/src/main/java/org/springframework/social/yammer/api/SubscriptionOperations.java
@@ -15,24 +15,60 @@
*/
package org.springframework.social.yammer.api;
+import org.springframework.social.OperationNotPermittedException;
+
/**
+ * Sub-API for subscriptions (following/unfollowing).
* @author Morten Andersen-Gott
*
*/
public interface SubscriptionOperations {
+ /**
+ * Follow a user with the given id
+ * @param userId
+ * @throws OperationNotPermittedException if user does not exist
+ */
void followUser(long userId);
+ /**
+ * Follow a topic with the given id
+ * @param topicId
+ * @throws OperationNotPermittedException if user does not exist
+ */
void followTopic(long topicId);
+ /**
+ * Check whether you are following the given user
+ * @param userId
+ * @return <code>true</code> if you are following the user, otherwise <code>false</code>
+ */
boolean isFollowingUser(long userId);
+ /**
+ * Check whether you are following the given topic
+ * @param topicId
+ * @return <code>true</code> if you are following the topic, otherwise <code>false</code>
+ */
boolean isFollowingTopic(long topicId);
-
+
+ /**
+ * Check whether you are following the given thread
+ * @param threadId
+ * @return <code>true</code> if you are following the thread, otherwise <code>false</code>
+ */
boolean isFollowingThread(long threadId);
+ /**
+ * Stop following a topic
+ * @param topicId
+ */
void unfollowTopic(long topicId);
+ /**
+ * Stop following a user
+ * @param userId
+ */
void unfollowUser(long userId);
}
View
6 spring-social-yammer/src/main/java/org/springframework/social/yammer/api/ThreadOperations.java
@@ -17,11 +17,17 @@
/**
+ * Sub-API for Thread operations
* @author Morten Andersen-Gott
*
*/
public interface ThreadOperations {
+ /**
+ * Get information about a thread
+ * @param id the thread id
+ * @return {@link YammerThread}
+ */
YammerThread getThread(long id);
}
View
6 spring-social-yammer/src/main/java/org/springframework/social/yammer/api/TopicOperations.java
@@ -17,11 +17,17 @@
/**
+ * Sub-API for topic operations
* @author Morten Andersen-Gott
*
*/
public interface TopicOperations {
+ /**
+ * Get information about a topic
+ * @param id topic id
+ * @return {@link Topic}
+ */
Topic getTopic(long id);
}
View
36 spring-social-yammer/src/main/java/org/springframework/social/yammer/api/UserOperations.java
@@ -17,8 +17,10 @@
import java.util.List;
+import org.springframework.social.ResourceNotFoundException;
/**
+ * Sub-API for User related operations
* @author Morten Andersen-Gott
*
*/
@@ -34,16 +36,50 @@
*/
public static final String SORT_BY_FOLLOWERS = "followers";
+ /**
+ * Get the user profile of the logged in user
+ * @return {@link YammerProfile} of the logged in user
+ */
YammerProfile getUserProfile();
+ /**
+ * Get user with the given user id
+ * @param id of user
+ * @return {@link YammerProfile}
+ * @throws ResourceNotFoundException if no user corresponds to that Id in your network
+ */
YammerProfile getUser(long id);
+ /**
+ * Get user by e-mail
+ * @param email address
+ * @return {@link YammerProfile} with given e-mail or <code>null</code> if no user exists with that e-mail
+ *
+ */
YammerProfile getUserByEmail(String email);
+ /**
+ * List users
+ * @param page the page number in the result set
+ * @param sortBy sorting key. Valid values are {@link #SORT_BY_FOLLOWERS} (default) or {@link #SORT_BY_MESSAGES}
+ * @param reverse <code>true</code> if you want the results in reversed order
+ * @param letter the letter you want the user to start with, or <code>null</code> if you don't want to filter by letter
+ * @return List of {@link YammerProfile}s matching criteria
+ */
List<YammerProfile> getUsers(int page, String sortBy, boolean reverse, Character letter);
+ /**
+ * List users using the yammer defaults by followers.
+ * @param page the page number in the result set
+ * @return List of {@link YammerProfile}s matching criteria
+ */
List<YammerProfile> getUsers(int page);
+ /**
+ * Update user profile
+ * @param userId your user id
+ * @param userInfo your user info
+ */
void updateProfile(long userId, UserInfo userInfo);
}
Please sign in to comment.
Something went wrong with that request. Please try again.