Updated the Javadoc on the Publishing Foundation API

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

source/java/org/alfresco/repo/publishing/ChannelImpl.java

@@ -134,9 +134,8 @@ public class ChannelImpl implements Channel
         return channelType.getNodeUrl(mappedNode);
     }
 
-    @Override
     public boolean isAuthorised()
     {
-        return channelHelper.isChannelAuthorised(getNodeRef());
+        return channelHelper.isChannelAuthorised(nodeRef);
     }
 }

source/java/org/alfresco/repo/publishing/PublishEventActionTest.java

@@ -48,9 +48,9 @@ import javax.annotation.Resource;
 import org.alfresco.model.ContentModel;
 import org.alfresco.repo.content.MimetypeMap;
 import org.alfresco.service.cmr.publishing.MutablePublishingPackage;
-import org.alfresco.service.cmr.publishing.PublishingEvent;
 import org.alfresco.service.cmr.publishing.PublishingPackage;
 import org.alfresco.service.cmr.publishing.PublishingService;
+import org.alfresco.service.cmr.publishing.Status;
 import org.alfresco.service.cmr.publishing.StatusUpdate;
 import org.alfresco.service.cmr.publishing.channels.Channel;
 import org.alfresco.service.cmr.publishing.channels.ChannelService;
@@ -357,13 +357,13 @@ public class PublishEventActionTest extends AbstractPublishingIntegrationTest
         NodeRef eventNode = new NodeRef(eventId);
         assertTrue(nodeService.exists(eventNode));
         Serializable eventStatus = nodeService.getProperty(eventNode, PublishingModel.PROP_PUBLISHING_EVENT_STATUS);
-        assertEquals(PublishingEvent.Status.SCHEDULED.name(), eventStatus);
+        assertEquals(Status.SCHEDULED.name(), eventStatus);
 
         action.executeImpl(null, eventNode);
         
         // Check Status has changed to COMPLETE
         eventStatus = nodeService.getProperty(eventNode, PublishingModel.PROP_PUBLISHING_EVENT_STATUS);
-        assertEquals(PublishingEvent.Status.COMPLETED.name(), eventStatus);
+        assertEquals(Status.COMPLETED.name(), eventStatus);
 
         return eventNode;
     }

source/java/org/alfresco/repo/publishing/PublishWebContentJbpmTest.java

@@ -46,7 +46,7 @@ import org.alfresco.repo.workflow.WorkflowModel;
 import org.alfresco.service.ServiceRegistry;
 import org.alfresco.service.cmr.action.Action;
 import org.alfresco.service.cmr.action.ActionDefinition;
-import org.alfresco.service.cmr.publishing.PublishingEvent.Status;
+import org.alfresco.service.cmr.publishing.Status;
 import org.alfresco.service.cmr.repository.ChildAssociationRef;
 import org.alfresco.service.cmr.repository.NodeRef;
 import org.alfresco.service.cmr.repository.NodeService;

source/java/org/alfresco/repo/publishing/PublishingEventHelper.java

@@ -61,9 +61,9 @@ import org.alfresco.model.ContentModel;
 import org.alfresco.repo.node.NodeUtils;
 import org.alfresco.repo.workflow.WorkflowModel;
 import org.alfresco.service.cmr.publishing.PublishingEvent;
-import org.alfresco.service.cmr.publishing.PublishingEvent.Status;
 import org.alfresco.service.cmr.publishing.PublishingEventFilter;
 import org.alfresco.service.cmr.publishing.PublishingPackage;
+import org.alfresco.service.cmr.publishing.Status;
 import org.alfresco.service.cmr.publishing.StatusUpdate;
 import org.alfresco.service.cmr.repository.AssociationRef;
 import org.alfresco.service.cmr.repository.ChildAssociationRef;

source/java/org/alfresco/repo/publishing/PublishingEventHelperTest.java

@@ -48,11 +48,11 @@ import java.util.Map;
 
 import javax.annotation.Resource;
 
-import org.alfresco.service.cmr.publishing.PublishingEvent.Status;
 import org.alfresco.model.ContentModel;
 import org.alfresco.service.cmr.publishing.PublishingEvent;
 import org.alfresco.service.cmr.publishing.PublishingPackage;
 import org.alfresco.service.cmr.publishing.PublishingPackageEntry;
+import org.alfresco.service.cmr.publishing.Status;
 import org.alfresco.service.cmr.repository.ChildAssociationRef;
 import org.alfresco.service.cmr.repository.ContentReader;
 import org.alfresco.service.cmr.repository.ContentService;

source/java/org/alfresco/repo/publishing/PublishingEventImpl.java

@@ -25,6 +25,7 @@ import java.util.Date;
 import org.alfresco.service.cmr.publishing.MutablePublishingEvent;
 import org.alfresco.service.cmr.publishing.PublishingEvent;
 import org.alfresco.service.cmr.publishing.PublishingPackage;
+import org.alfresco.service.cmr.publishing.Status;
 import org.alfresco.service.cmr.publishing.StatusUpdate;
 
 /**
@@ -79,7 +80,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public String getId()
     {
         return id;
@@ -88,7 +88,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public Status getStatus()
     {
         return status;
@@ -105,7 +104,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public Calendar getScheduledTime()
     {
         return (Calendar) scheduledTime.clone();
@@ -114,7 +112,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public PublishingPackage getPackage()
     {
         return publishingPackage;
@@ -123,7 +120,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public Date getCreatedTime()
     {
         return new Date(createdTime.getTime());
@@ -132,7 +128,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public String getCreator()
     {
         return creator;
@@ -141,7 +136,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public Date getModifiedTime()
     {
         return new Date(modifiedTime.getTime());
@@ -150,7 +144,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public String getModifier()
     {
         return modifier;
@@ -159,7 +152,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public String getComment()
     {
         return comment;
@@ -168,7 +160,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public StatusUpdate getStatusUpdate()
     {
         return statusUpdate;
@@ -177,7 +168,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public MutablePublishingEvent edit()
     {
         return new MutablePublishingEventImpl(this);
@@ -186,7 +176,6 @@ public class PublishingEventImpl implements PublishingEvent
     /**
     * {@inheritDoc}
     */
-    @Override
     public int compareTo(PublishingEvent event)
     {
         if(event == null)

source/java/org/alfresco/repo/publishing/PublishingEventProcessor.java

@@ -38,6 +38,7 @@ import org.alfresco.service.cmr.dictionary.DictionaryService;
 import org.alfresco.service.cmr.publishing.NodeSnapshot;
 import org.alfresco.service.cmr.publishing.PublishingEvent;
 import org.alfresco.service.cmr.publishing.PublishingPackageEntry;
+import org.alfresco.service.cmr.publishing.Status;
 import org.alfresco.service.cmr.publishing.StatusUpdate;
 import org.alfresco.service.cmr.publishing.channels.Channel;
 import org.alfresco.service.cmr.publishing.channels.ChannelService;
@@ -71,7 +72,7 @@ public class PublishingEventProcessor
         try
         {
             behaviourFilter.disableAllBehaviours();
-            String inProgressStatus = PublishingEvent.Status.IN_PROGRESS.name();
+            String inProgressStatus = Status.IN_PROGRESS.name();
             nodeService.setProperty(eventNode, PublishingModel.PROP_PUBLISHING_EVENT_STATUS, inProgressStatus);
             PublishingEvent event = eventHelper.getPublishingEvent(eventNode);
             String channelName = event.getChannelId();
@@ -84,7 +85,7 @@ public class PublishingEventProcessor
             {
                 publishEvent(channel, event);
                 updateStatus(channel, event.getStatusUpdate());
-                String completedStatus = PublishingEvent.Status.COMPLETED.name();
+                String completedStatus = Status.COMPLETED.name();
                 nodeService.setProperty(eventNode, PublishingModel.PROP_PUBLISHING_EVENT_STATUS, completedStatus);
             }
         }
@@ -150,7 +151,7 @@ public class PublishingEventProcessor
 
      public void fail(NodeRef eventNode, String msg)
      {
-         String completedStatus = PublishingEvent.Status.FAILED.name();
+         String completedStatus = Status.FAILED.name();
          nodeService.setProperty(eventNode, PublishingModel.PROP_PUBLISHING_EVENT_STATUS, completedStatus);
      }
 

source/java/org/alfresco/repo/publishing/PublishingQueueImplTest.java

@@ -36,10 +36,10 @@ import org.alfresco.model.ContentModel;
 import org.alfresco.repo.security.authentication.AuthenticationUtil;
 import org.alfresco.service.cmr.publishing.MutablePublishingPackage;
 import org.alfresco.service.cmr.publishing.PublishingEvent;
-import org.alfresco.service.cmr.publishing.PublishingEvent.Status;
 import org.alfresco.service.cmr.publishing.PublishingPackage;
 import org.alfresco.service.cmr.publishing.PublishingPackageEntry;
 import org.alfresco.service.cmr.publishing.PublishingService;
+import org.alfresco.service.cmr.publishing.Status;
 import org.alfresco.service.cmr.publishing.StatusUpdate;
 import org.alfresco.service.cmr.repository.NodeRef;
 import org.alfresco.service.cmr.workflow.WorkflowInstance;

source/java/org/alfresco/service/cmr/publishing/PublishingEvent.java

@@ -22,6 +22,9 @@ package org.alfresco.service.cmr.publishing;
 import java.util.Calendar;
 import java.util.Date;
 
+import org.alfresco.service.cmr.publishing.channels.Channel;
+import org.alfresco.service.cmr.repository.NodeRef;
+
 
 /**
  * @author Brian
@@ -29,29 +32,58 @@ import java.util.Date;
  */
 public interface PublishingEvent extends Comparable<PublishingEvent>
 {
-    enum Status {SCHEDULED, IN_PROGRESS, CANCEL_REQUESTED, COMPLETED, FAILED}
+    /**
-    
+     * @return a unique {@link String} identifier for this {@link PublishingEvent}
+     */
     String getId();
     
+    /**
+     * @return the current {@link Status} of this {@link PublishingEvent}.
+     */
     Status getStatus();
     
+    /**
+     * @return the date and time when this {@link PublishingEvent} is scheduled to publish its content.
+     */
     Calendar getScheduledTime();
     
+    /**
+     * @return the {@link PublishingPackage} containing all the {@link NodeRef}s to be published and unpublished.
+     */
     PublishingPackage getPackage();
     
+    /**
+     * @return the date and time when this {@link PublishingEvent} was created.
+     */
     Date getCreatedTime();
     
+    /**
+     * @return the name of the user who created this {@link PublishingEvent}.
+     */
     String getCreator();
     
+    /**
+     * @return the date and time when this {@link PublishingEvent} was last modified.
+     */
     Date getModifiedTime();
     
+    /**
+     * @return the name of the user who last modified this {@link PublishingEvent}.
+     */
     String getModifier();
     
+    /**
+     * @return the comment associatied with this {@link PublishingEvent}.
+     */
     String getComment();
     
-    MutablePublishingEvent edit();
+    /**
-
+     * @return a unique identifier indicating which {@link Channel} this {@link PublishingEvent} publishes to.
+     */
     String getChannelId();
     
+    /**
+     * @return the {@link StatusUpdate} information, if any.
+     */
     StatusUpdate getStatusUpdate();
 }

source/java/org/alfresco/service/cmr/publishing/PublishingPackage.java

@@ -31,7 +31,20 @@ public interface PublishingPackage
      * @return The collection of publishing package entries. Never <code>null</code>.
      */
     Collection<PublishingPackageEntry> getEntries();
+    
+    /**
+     * Returns a {@link Map} from the {@link NodeRef} to be published/unpublished to the corresponding {@link PublishingPackageEntry}.
+     * @return the {@link Map} of Publishing Package Entries.
+     */
     Map<NodeRef,PublishingPackageEntry> getEntryMap();
+    
+    /**
+     * @return a {@link Set} of all the {@link NodeRef}s to be published.
+     */
     Set<NodeRef> getNodesToPublish();
+
+    /**
+     * @return a {@link Set} of all the {@link NodeRef}s to be unpublished.
+     */
     Set<NodeRef> getNodesToUnpublish();
 }

source/java/org/alfresco/service/cmr/publishing/PublishingService.java

@@ -22,6 +22,7 @@ import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 
+import org.alfresco.service.cmr.publishing.channels.Channel;
 import org.alfresco.service.cmr.repository.NodeRef;
 
 
@@ -69,11 +70,17 @@ public interface PublishingService
     
     /**
      * Discover the publishing status of each of the specified nodes
-     * @param channelId TODO
+     * @param channelId an identifier indicating which {@link Channel} to check the status for.
-     * @param nodes The identifiers of the nodes whose publishing status is being sought
+     * @param nodes The nodes whose publishing status is being sought
      * @return A map associating a NodePublishStatus object with each of the supplied NodeRef objects
      */
     Map<NodeRef,NodePublishStatus> checkPublishStatus(String channelId, Collection<NodeRef> nodes);
 
+    /**
+     * Discover the publishing status of each of the specified nodes
+     * @param channelId an identifier indicating which {@link Channel} to check the status for.
+     * @param nodes The nodes whose publishing status is being sought
+     * @return A map associating a NodePublishStatus object with each of the supplied NodeRef objects
+     */
     Map<NodeRef,NodePublishStatus> checkPublishStatus(String channelId, NodeRef... nodes);
 }

source/java/org/alfresco/service/cmr/publishing/Status.java

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2005-2010 Alfresco Software Limited.
+ *
+ * This file is part of Alfresco
+ *
+ * Alfresco is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alfresco 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 Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with Alfresco. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.alfresco.service.cmr.publishing;
+
+public enum Status {
+    SCHEDULED,
+    IN_PROGRESS,
+    CANCEL_REQUESTED,
+    COMPLETED,
+    FAILED}

source/java/org/alfresco/service/cmr/publishing/StatusUpdate.java

@@ -21,6 +21,7 @@ package org.alfresco.service.cmr.publishing;
 
 import java.util.Set;
 
+import org.alfresco.service.cmr.publishing.channels.Channel;
 import org.alfresco.service.cmr.repository.NodeRef;
 
 /**
@@ -30,7 +31,19 @@ import org.alfresco.service.cmr.repository.NodeRef;
  */
 public interface StatusUpdate
 {
+    /**
+     * @return the status message to be published.
+     */
     String getMessage();
+    
+    /**
+     * @return a {@link Set} of String identifiers indicating which {@link Channel} the status update will be published to.
+     */
     Set<String> getChannelIds();
+
+    /**
+     * Returns a {@link NodeRef}. The returned {@link NodeRef} is one of the {@link NodeRef}s to be published by the associated {@link PublishingEvent}. The status update message will have a URL appended to it which links to the published resource represented by this {@link NodeRef}.
+     * @return the {@link NodeRef} to link to.
+     */
     NodeRef getNodeToLinkTo();
 }

source/java/org/alfresco/service/cmr/publishing/channels/Channel.java

@@ -31,7 +31,14 @@ import org.alfresco.service.namespace.QName;
  */
 public interface Channel
 {
+    /**
+     * @return a unique identifier for this {@link Channel}.
+     */
     String getId();
+    
+    /**
+     * @return the {@link ChannelType} for this Channel.
+     */
     ChannelType getChannelType();
     
     /**

source/java/org/alfresco/service/cmr/publishing/channels/ChannelService.java

@@ -28,6 +28,7 @@ import org.alfresco.service.namespace.QName;
 
 /**
  * @author Brian
+ * @author Nick Smith
  *
  */
 public interface ChannelService
@@ -70,7 +71,7 @@ public interface ChannelService
     
     /**
      * Rename the specified channel
-     * @param channel The current name of the channel that is to be renamed.
+     * @param channel The channel that is to be renamed.
      * @param newName The new name of the channel
      */
     void renameChannel(Channel channel, String newName);