ALF-9153 Update the new discussions service interfaces following review with Gav, and webscript testing experience

git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@29670 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/service/cmr/discussion/DiscussionService.java

@@ -18,6 +18,7 @@
  */
 package org.alfresco.service.cmr.discussion;
 
+import org.alfresco.model.ForumModel;
 import org.alfresco.query.PagingRequest;
 import org.alfresco.query.PagingResults;
 import org.alfresco.service.NotAuditable;
@@ -31,94 +32,102 @@ import org.alfresco.service.cmr.repository.NodeRef;
  */
 public interface DiscussionService {
    /**
-    * Creates a new {@link ForumPostInfo} in the given topic,
-    *  specified settings
+    * Creates a new {@link PostInfo} in the given topic,
+    *  specified contents
     *  
-    * @return The newly created {@link ForumPostInfo}
+    * @return The newly created {@link PostInfo}
     */
    @NotAuditable
-   ForumPostInfo createForumPost(ForumTopicInfo topic, String title,
-         String contents);
+   PostInfo createPost(TopicInfo topic, String contents);
    
    /**
-    * Creates a new {@link ForumTopicInfo} in the given site
+    * Creates a new {@link TopicInfo} in the given site
     */
    @NotAuditable
-   ForumTopicInfo createForumTopic(String siteShortName);
+   TopicInfo createTopic(String siteShortName);
    
    /**
-    * Creates a new {@link ForumTopicInfo} attached to the
-    *  specified Node
+    * Creates a new {@link TopicInfo} attached to the specified Node. 
+    * The parent Node should normally either be a Site Container, or a 
+    * {@link ForumModel#TYPE_FORUM}
     */
    @NotAuditable
-   ForumTopicInfo createForumTopic(NodeRef nodeRef);
+   TopicInfo createTopic(NodeRef nodeRef, String title);
    
    /**
-    * Updates an existing {@link ForumPostInfo} in the repository.
+    * Updates an existing {@link PostInfo} in the repository.
     *  
-    * @return The updated {@link ForumPostInfo}
+    * @return The updated {@link PostInfo}
     */
    @NotAuditable
-   ForumPostInfo updateForumPost(ForumPostInfo post);
+   PostInfo updatePost(PostInfo post);
    
    /**
-    * Deletes an existing {@link ForumPostInfo} from the repository
+    * Deletes an existing {@link PostInfo} from the repository
     */
    @NotAuditable
-   void deleteForumPost(ForumPostInfo post);
+   void deletePost(PostInfo post);
    
    /**
-    * Deletes an existing {@link ForumTopicInfo} from the repository
+    * Deletes an existing {@link TopicInfo} from the repository
     */
    @NotAuditable
-   void deleteForumTopic(ForumTopicInfo topic);
+   void deleteTopic(TopicInfo topic);
    
    /**
-    * Retrieves an existing {@link ForumPostInfo} from the repository
+    * Retrieves an existing {@link PostInfo} from the repository
     */
    @NotAuditable
-   ForumPostInfo getForumPost(ForumTopicInfo topic, String linkName);
+   PostInfo getPost(TopicInfo topic, String linkName);
 
    /**
-    * Retrieves an existing {@link ForumTopicInfo} from the repository,
+    * Retrieves the Primary (Root) Post in a topic, to which all
+    *  replies belong.
+    * Returns null if the topic currently has no posts
+    */
+   @NotAuditable
+   PostInfo getPrimaryPost(TopicInfo topic);
+   
+   /**
+    * Retrieves an existing {@link TopicInfo} from the repository,
     *  which is within a site
     */
    @NotAuditable
-   ForumTopicInfo getForumTopic(String siteShortName, String linkName);
+   TopicInfo getTopic(String siteShortName, String linkName);
    
    /**
-    * Retrieves an existing {@link ForumTopicInfo} from the repository,
-    *  which is attached to the specified Node
+    * Retrieves an existing {@link TopicInfo} from the repository,
+    *  which is attached to the specified Node.
+    * The parent Node should normally either be a Site Container, or a 
+    *  {@link ForumModel#TYPE_FORUM}
     */
    @NotAuditable
-   ForumTopicInfo getForumTopic(NodeRef nodeRef, String linkName);
-   
-   // TODO Decide about the primary post on a topic
+   TopicInfo getTopic(NodeRef nodeRef, String linkName);
    
    
    /**
     * Retrieves all replies on a Topic
     */
    @NotAuditable
-   PagingResults<ForumPostInfo> listForumPostReplies(ForumTopicInfo forum, int levels, PagingRequest paging);
+   PagingResults<PostInfo> listPostReplies(TopicInfo forum, int levels, PagingRequest paging);
 
    /**
     * Retrieves all replies to a Post
     */
    @NotAuditable
-   PagingResults<ForumPostInfo> listForumPostReplies(ForumPostInfo primaryPost, int levels, PagingRequest paging);
+   PagingResults<PostInfo> listPostReplies(PostInfo primaryPost, int levels, PagingRequest paging);
    
    /**
     * Retrieves all posts in a site
     */
    @NotAuditable
-   PagingResults<ForumPostInfo> listForumPosts(String siteShortName, PagingRequest paging);
+   PagingResults<PostInfo> listPosts(String siteShortName, PagingRequest paging);
 
    /**
     * Retrieves all posts attached to the specified Node
     */
    @NotAuditable
-   PagingResults<ForumPostInfo> listForumPosts(NodeRef nodeRef, PagingRequest paging);
+   PagingResults<PostInfo> listPosts(NodeRef nodeRef, PagingRequest paging);
 
    // TODO Hot, New and Mine listing support
 }

source/java/org/alfresco/service/cmr/discussion/PostInfo.java

@@ -25,21 +25,24 @@ import org.alfresco.repo.security.permissions.PermissionCheckValue;
 import org.alfresco.service.cmr.repository.NodeRef;
 
 /**
- * This class represents a Post in a Forum Topic 
+ * This class represents a Post in a Forum Topic.
+ * 
+ * To retrieve replies to this, see 
+ *  {@link DiscussionService#listPostReplies(PostInfo, int, org.alfresco.query.PagingRequest)}
  * 
  * @author Nick Burch
  * @since 4.0
  */
-public interface ForumPostInfo extends Serializable, PermissionCheckValue {
+public interface PostInfo extends Serializable, PermissionCheckValue {
    /**
     * @return the NodeRef of the underlying post
     */
    NodeRef getNodeRef();
    
    /**
-    * @return the NodeRef of the topic this belongs to
+    * @return the {@link TopicInfo} representing the topic this belongs to
     */
-   NodeRef getTopicNodeRef();
+   TopicInfo getTopic();
    
    /**
     * @return the System generated name for the post
@@ -47,12 +50,13 @@ public interface ForumPostInfo extends Serializable, PermissionCheckValue {
    String getSystemName();
    
    /**
-    * @return the Title of the post
+    * @return the Title of the post (if set)
     */
    String getTitle();
    
    /**
-    * Sets the Title of the post
+    * Sets the Title of the post. Normally only the Primary Post
+    *  in a Topic has a Title set.
     */
    void setTitle(String title);
    

source/java/org/alfresco/service/cmr/discussion/TopicInfo.java

@@ -26,14 +26,16 @@ import org.alfresco.repo.security.permissions.PermissionCheckValue;
 import org.alfresco.service.cmr.repository.NodeRef;
 
 /**
- * This class represents a Topic in a forum
+ * This class represents a Topic in a forum.
  * 
- * TODO Decide about the primary post on a topic
+ * To retrieve either the Primary Post, or all Posts,
+ *  use {@link DiscussionService#getPrimaryPost(TopicInfo)}
+ *  and {@link DiscussionService#listPostReplies(TopicInfo, int, org.alfresco.query.PagingRequest)}
  *
  * @author Nick Burch
  * @since 4.0
  */
-public interface ForumTopicInfo extends Serializable, PermissionCheckValue {
+public interface TopicInfo extends Serializable, PermissionCheckValue {
    /**
     * @return the NodeRef of the underlying topic
     */
@@ -49,6 +51,17 @@ public interface ForumTopicInfo extends Serializable, PermissionCheckValue {
     */
    String getSystemName();
    
+   /**
+    * @return the Title of the topic.
+    */
+   String getTitle();
+   
+   /**
+    * Sets the Title of the topic. The Title of the
+    *  topic will be shared with the Primary Post
+    */
+   void setTitle(String title);
+   
    /**
     * @return the creator of the topic
     */