RatingService JavaScript API.

This is a preliminary JavaScript API for the RatingService.
  The intention is to get something committed to enable possible feedback and to lay the basis for any improvements that be needed later.
  It's the normal Alfresco JS API changes. The root object is 'ratingService' and all the methods are on that object.
  Highly non-OO.
  But it is tested.


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

source/java/org/alfresco/repo/rating/RatingServiceIntegrationTest.java

@@ -20,14 +20,17 @@
 package org.alfresco.repo.rating;
 
 import java.io.Serializable;
+import java.util.Arrays;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
 import org.alfresco.model.ContentModel;
+import org.alfresco.repo.jscript.ClasspathScriptLocation;
 import org.alfresco.repo.model.Repository;
 import org.alfresco.repo.security.authentication.AuthenticationUtil;
+import org.alfresco.repo.transaction.RetryingTransactionHelper;
 import org.alfresco.service.cmr.rating.Rating;
 import org.alfresco.service.cmr.rating.RatingScheme;
 import org.alfresco.service.cmr.rating.RatingService;
@@ -35,6 +38,8 @@ import org.alfresco.service.cmr.rating.RatingServiceException;
 import org.alfresco.service.cmr.repository.ChildAssociationRef;
 import org.alfresco.service.cmr.repository.CopyService;
 import org.alfresco.service.cmr.repository.NodeRef;
+import org.alfresco.service.cmr.repository.ScriptLocation;
+import org.alfresco.service.cmr.repository.ScriptService;
 import org.alfresco.service.cmr.security.PersonService;
 import org.alfresco.service.namespace.NamespaceService;
 import org.alfresco.service.namespace.QName;
@@ -49,11 +54,13 @@ import org.alfresco.util.PropertyMap;
 public class RatingServiceIntegrationTest extends BaseAlfrescoSpringTest
 {
     private static final String USER_ONE = "UserOne";
-    private static final String USER_USERTWO = "UserTwo";
+    private static final String USER_TWO = "UserTwo";
     private CopyService copyService;
     private PersonService personService;
     private RatingService ratingService;
     private Repository repositoryHelper;
+    private ScriptService scriptService;
+    private RetryingTransactionHelper transactionHelper;
     private NodeRef companyHome;
     
     // These NodeRefs are used by the test methods.
@@ -75,6 +82,8 @@ public class RatingServiceIntegrationTest extends BaseAlfrescoSpringTest
         this.personService = (PersonService)this.applicationContext.getBean("PersonService");
         this.ratingService = (RatingService) this.applicationContext.getBean("ratingService");
         this.repositoryHelper = (Repository) this.applicationContext.getBean("repositoryHelper");
+        this.transactionHelper = (RetryingTransactionHelper) this.applicationContext.getBean("retryingTransactionHelper");
+        this.scriptService = (ScriptService) this.applicationContext.getBean("scriptService");
 
         // Set the current security context as admin
         AuthenticationUtil.setFullyAuthenticatedUser(AuthenticationUtil.getAdminUserName());
@@ -86,10 +95,10 @@ public class RatingServiceIntegrationTest extends BaseAlfrescoSpringTest
         testFolderCopyDest = createNode(companyHome, "testFolderCopyDest", ContentModel.TYPE_FOLDER);
         testDoc_Admin = createNode(testFolder, "testDocInFolder", ContentModel.TYPE_CONTENT);
         
-        createUser(USER_USERTWO);
         createUser(USER_ONE);
+        createUser(USER_TWO);
         
-        AuthenticationUtil.setFullyAuthenticatedUser(USER_USERTWO);
+        AuthenticationUtil.setFullyAuthenticatedUser(USER_TWO);
         testDoc_UserOne = createNode(testFolder, "userOnesDoc", ContentModel.TYPE_CONTENT);
         AuthenticationUtil.setFullyAuthenticatedUser(USER_ONE);
         testDoc_UserTwo = createNode(testFolder, "userTwosDoc", ContentModel.TYPE_CONTENT);
@@ -102,7 +111,7 @@ public class RatingServiceIntegrationTest extends BaseAlfrescoSpringTest
     protected void onTearDownInTransaction() throws Exception
     {
         AuthenticationUtil.setFullyAuthenticatedUser(AuthenticationUtil.getAdminUserName());
-        deleteUser(USER_USERTWO);
+        deleteUser(USER_TWO);
         deleteUser(USER_ONE);
     }
     
@@ -173,7 +182,7 @@ public class RatingServiceIntegrationTest extends BaseAlfrescoSpringTest
     public void testApplyUpdateDeleteRatings_SingleUserMultipleSchemes() throws Exception
     {
         // We'll do all this as user 'UserOne'.
-        AuthenticationUtil.setFullyAuthenticatedUser(USER_USERTWO);
+        AuthenticationUtil.setFullyAuthenticatedUser(USER_TWO);
         
         //Before we start, let's ensure the read behaviour on a pristine node is correct.
         Rating nullRating = ratingService.getRatingByCurrentUser(testDoc_Admin, LIKES_SCHEME_NAME);
@@ -292,7 +301,7 @@ public class RatingServiceIntegrationTest extends BaseAlfrescoSpringTest
         AuthenticationUtil.setFullyAuthenticatedUser(USER_ONE);
         ratingService.applyRating(testDoc_Admin, 4.0f, FIVE_STAR_SCHEME_NAME);
         
-        AuthenticationUtil.setFullyAuthenticatedUser(USER_USERTWO);
+        AuthenticationUtil.setFullyAuthenticatedUser(USER_TWO);
         ratingService.applyRating(testDoc_Admin, 2.0f, FIVE_STAR_SCHEME_NAME);
         
         float meanRating = ratingService.getAverageRating(testDoc_Admin, FIVE_STAR_SCHEME_NAME);
@@ -345,4 +354,13 @@ public class RatingServiceIntegrationTest extends BaseAlfrescoSpringTest
             personService.deletePerson(userName);
         }
     }
+
+    public void testJavascriptAPI() throws Exception
+    {
+        Map<String, Object> model = new HashMap<String, Object>();
+        model.put("testNode", this.testDoc_UserOne);
+        
+        ScriptLocation location = new ClasspathScriptLocation("org/alfresco/repo/rating/script/test_ratingService.js");
+        this.scriptService.executeScript(location, model);
+    }
 }

source/java/org/alfresco/repo/rating/script/ScriptRatingService.java

@@ -0,0 +1,167 @@
+/*
+ * 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.repo.rating.script;
+
+import java.util.Date;
+import java.util.Set;
+
+import org.alfresco.repo.jscript.BaseScopableProcessorExtension;
+import org.alfresco.repo.jscript.ScriptNode;
+import org.alfresco.service.ServiceRegistry;
+import org.alfresco.service.cmr.rating.Rating;
+import org.alfresco.service.cmr.rating.RatingService;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+/**
+ * Script object representing the rating service.
+ * 
+ * @author Neil McErlean
+ * @since 3.4
+ */
+public class ScriptRatingService extends BaseScopableProcessorExtension
+{
+    private static Log logger = LogFactory.getLog(ScriptRatingService.class);
+    
+    /** The Services registry */
+    private ServiceRegistry serviceRegistry;
+    private RatingService ratingService;
+
+    /**
+     * Set the service registry
+     * 
+     * @param serviceRegistry the service registry.
+     */
+    public void setServiceRegistry(ServiceRegistry serviceRegistry)
+    {
+        this.serviceRegistry = serviceRegistry;
+        this.ratingService = serviceRegistry.getRatingService();
+    }
+    
+    /**
+     * Gets the names for rating schemes currently in the system.
+     * @return
+     */
+    public String[] getRatingSchemeNames()
+    {
+        Set<String> schemeNames = ratingService.getRatingSchemes().keySet();
+        String[] result = new String[0];
+        result = schemeNames.toArray(result);
+        return result;
+    }
+    
+    /**
+     * Gets the minimum allowed rating for the specified rating scheme.
+     * 
+     * @param ratingSchemeName
+     * @return
+     */
+    public float getMin(String ratingSchemeName)
+    {
+        return ratingService.getRatingScheme(ratingSchemeName).getMinRating();
+    }
+    
+    /**
+     * Gets the maximum allowed rating for the specified rating scheme.
+     * 
+     * @param ratingSchemeName
+     * @return
+     */
+    public float getMax(String ratingSchemeName)
+    {
+        return ratingService.getRatingScheme(ratingSchemeName).getMaxRating();
+    }
+
+    /**
+     * Applies the given rating to the specified node using the specified ratingScheme.
+     * It is the responsibility of the caller to ensure that the rating scheme exists
+     * and that the rating is within the limits defined for that scheme.
+     * 
+     * @param node
+     * @param rating
+     * @param ratingSchemeName
+     * @see ScriptRatingService#getMin(String)
+     * @see ScriptRatingService#getMax(String)
+     */
+    public void applyRating(ScriptNode node, float rating, String ratingSchemeName)
+    {
+        ratingService.applyRating(node.getNodeRef(), rating, ratingSchemeName);
+    }
+    
+    /**
+     * Gets the rating applied to the specified node in the specified scheme by
+     * the currently authenticated user.
+     * @param node
+     * @param ratingSchemeName
+     * @return rating if there is one, else -1.
+     * TODO -1 could be a valid rating.
+     */
+    public float getRating(ScriptNode node, String ratingSchemeName)
+    {
+        final Rating ratingByCurrentUser = ratingService.getRatingByCurrentUser(node.getNodeRef(), ratingSchemeName);
+        return ratingByCurrentUser == null ? -1f : ratingByCurrentUser.getScore();
+    }
+    
+    /**
+     * Gets the rating applied date for the specified node in the specified scheme by
+     * the currently authenticated user.
+     * @param node
+     * @param ratingSchemeName
+     * @return rating applied date if there is one, else <code>null</code>
+     */
+    public Date getRatingAppliedAt(ScriptNode node, String ratingSchemeName)
+    {
+        final Rating ratingByCurrentUser = ratingService.getRatingByCurrentUser(node.getNodeRef(), ratingSchemeName);
+        return ratingByCurrentUser == null ? null : ratingByCurrentUser.getAppliedAt();
+    }
+
+    /**
+     * Gets the number of ratings applied to the specified node by all users in the specified
+     * scheme.
+     * @param node
+     * @param ratingSchemeName
+     * @return
+     */
+    public int getRatingsCount(ScriptNode node, String ratingSchemeName)
+    {
+        return ratingService.getRatingsCount(node.getNodeRef(), ratingSchemeName);
+    }
+
+    /**
+     * Gets the total (sum) rating by all users on the specified node in the specified scheme.
+     * @param node
+     * @param ratingSchemeName
+     * @return
+     */
+    public float getTotalRating(ScriptNode node, String ratingSchemeName)
+    {
+        return ratingService.getTotalRating(node.getNodeRef(), ratingSchemeName);
+    }
+
+    /**
+     * Gets the average (mean) rating by all users on the specified node in the specified scheme.
+     * @param node
+     * @param ratingSchemeName
+     * @return
+     */
+    public float getAverageRating(ScriptNode node, String ratingSchemeName)
+    {
+        return ratingService.getAverageRating(node.getNodeRef(), ratingSchemeName);
+    }
+}

source/java/org/alfresco/repo/rating/script/test_ratingService.js

@@ -0,0 +1,46 @@
+function testRatingSchemes()
+{
+	var schemeNames = ratingService.getRatingSchemeNames();
+    test.assertEquals(2, schemeNames.length);
+    test.assertEquals('likesRatingScheme', schemeNames[0]);
+    test.assertEquals('fiveStarRatingScheme', schemeNames[1]);
+    
+    test.assertEquals(1, ratingService.getMin('likesRatingScheme'));
+    test.assertEquals(1, ratingService.getMax('likesRatingScheme'));
+
+    test.assertEquals(1, ratingService.getMin('fiveStarRatingScheme'));
+    test.assertEquals(5, ratingService.getMax('fiveStarRatingScheme'));
+}
+
+function testApplyAndGetRatings()
+{
+	// Check the pristine state of the test node.
+	test.assertEquals(0, ratingService.getRatingsCount(testNode, 'fiveStarRatingScheme'));
+	test.assertEquals(0, ratingService.getTotalRating(testNode, 'fiveStarRatingScheme'));
+	test.assertEquals(-1, ratingService.getAverageRating(testNode, 'fiveStarRatingScheme'));
+	
+	// Now apply some ratings.
+	ratingService.applyRating(testNode, 2.0, 'fiveStarRatingScheme');
+	test.assertEquals(2.0, ratingService.getRating(testNode, 'fiveStarRatingScheme'));
+	//TODO Date formats in JS API?
+	test.assertNotNull(ratingService.getRatingAppliedAt(testNode, 'fiveStarRatingScheme'));
+	
+	test.assertEquals(1, ratingService.getRatingsCount(testNode, 'fiveStarRatingScheme'));
+	test.assertEquals(2, ratingService.getTotalRating(testNode, 'fiveStarRatingScheme'));
+	test.assertEquals(2, ratingService.getAverageRating(testNode, 'fiveStarRatingScheme'));
+
+	
+	// And update them
+	ratingService.applyRating(testNode, 4.5, 'fiveStarRatingScheme');
+	test.assertEquals(4.5, ratingService.getRating(testNode, 'fiveStarRatingScheme'));
+	//TODO Date formats in JS API?
+	test.assertNotNull(ratingService.getRatingAppliedAt(testNode, 'fiveStarRatingScheme'));
+	
+	test.assertEquals(1, ratingService.getRatingsCount(testNode, 'fiveStarRatingScheme'));
+	test.assertEquals(4.5, ratingService.getTotalRating(testNode, 'fiveStarRatingScheme'));
+	test.assertEquals(4.5, ratingService.getAverageRating(testNode, 'fiveStarRatingScheme'));
+}
+
+// Execute tests
+testRatingSchemes();
+testApplyAndGetRatings();

source/java/org/alfresco/service/cmr/rating/RatingService.java

@@ -37,8 +37,6 @@ import org.alfresco.service.cmr.repository.NodeRef;
  * {@link RatingService#applyRating(NodeRef, float, String) updated} and
  * {@link RatingService#removeRatingByCurrentUser(NodeRef, RatingScheme) removed}.
  * 
- * TODO Get average/total
- * 
  * @author Neil McErlean
  * @since 3.4
  */