ALF-4106 (ALF-4103): AuditService REST API

- Full start/stop/status using WebScripts
 - AuditService API additions to support
 - .ftl to generate json response
 - Some javadoc and debug additions


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

config/alfresco/templates/webscripts/org/alfresco/repository/audit/application.lib.ftl

@@ -0,0 +1,8 @@
+<#-- Renders an Audit Application. -->
+<#macro auditApplicationJSON auditApplication>
+      {
+         "name": "${auditApplication.name}",
+         "path" : "${auditApplication.key}",
+         "enabled" : ${auditApplication.enabled?string("true","false")}
+      }
+</#macro>

config/alfresco/templates/webscripts/org/alfresco/repository/audit/control.get.desc.xml

@@ -1,7 +1,8 @@
 <webscript>
   <shortname>Alfresco Audit Service Control</shortname>
   <description>Get audit status for a given application and path</description>
-  <url>/api/audit/control?application={application?}&amp;path={path?}</url>
+  <url>/api/audit/control</url>
+  <url>/api/audit/control/{application}/{path}</url>
   <format default="json" />
   <authentication>admin</authentication>
   <transaction allow="readonly">required</transaction>
@@ -13,7 +14,7 @@
     </arg> 
     <arg>
       <name>path</name>
-      <description>Path within the application (omit to assume application root)</description>
+      <description>Path within the application (the root key of the application at least)</description>
     </arg> 
  </args>
   

config/alfresco/templates/webscripts/org/alfresco/repository/audit/control.get.json.ftl

@@ -0,0 +1,13 @@
+<#import "application.lib.ftl" as auditApplicationLib />
+<#escape x as jsonUtils.encodeJSONString(x)>
+{
+   "enabled" : ${enabled?string("true","false")},
+   "applications": 
+   [
+      <#list applications as application>
+         <@auditApplicationLib.auditApplicationJSON auditApplication=application />
+         <#if application_has_next>,</#if>
+      </#list>
+   ]
+}
+</#escape>

config/alfresco/templates/webscripts/org/alfresco/repository/audit/control.post.desc.xml

@@ -1,23 +1,24 @@
 <webscript>
   <shortname>Alfresco Audit Service Control</shortname>
   <description>Change the audit status for a given application and path</description>
-  <url>/api/audit/control/{action}?application={application?}&amp;path={path?}</url>
+  <url>/api/audit/control?enable={enable}</url>
+  <url>/api/audit/control/{application}/{path}?enable={enable}</url>
   <format default="json" />
   <authentication>admin</authentication>
   <transaction>required</transaction>
   <lifecycle>internal</lifecycle>
   <args>
-    <arg>
-      <name>action</name>
-      <description>Set to 'enable' or 'disable' to change the audit state</description>
-    </arg> 
     <arg>
       <name>application</name>
       <description>Name of the audit application (omit to assume all applications)</description>
     </arg> 
     <arg>
       <name>path</name>
-      <description>Path within the application (omit to assume application root)</description>
+      <description>Path within the application (the root key of the application at least)</description>
+    </arg> 
+    <arg>
+      <name>enable</name>
+      <description>'true' or 'false' to change the audit state</description>
     </arg> 
  </args>
   

config/alfresco/templates/webscripts/org/alfresco/repository/audit/control.post.json.ftl

@@ -0,0 +1,3 @@
+{
+   "enabled" : ${enabled?string("true","false")}
+}

config/alfresco/templates/webscripts/org/alfresco/repository/audit/control.properties

@@ -1,4 +1,4 @@
 # Audit Control Web Script I18N
-audit.err.app.mandatory=Parameter 'app' is mandatory
+audit.err.app.notFound=Application not found: {0}
-audit.err.path.startsWith=Parameter 'path', when supplied, must start with '/'
+audit.err.path.notProvided=No path was supplied after the application name.
 audit.err.action.invalid=Parameter 'action' must be either 'enable' or 'disable'

source/java/org/alfresco/repo/web/scripts/audit/AbstractAuditWebScript.java

@@ -24,9 +24,7 @@ import org.alfresco.service.cmr.audit.AuditService;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.springframework.extensions.surf.util.I18NUtil;
-import org.springframework.extensions.webscripts.AbstractWebScript;
+import org.springframework.extensions.webscripts.DeclarativeWebScript;
-import org.springframework.extensions.webscripts.Status;
-import org.springframework.extensions.webscripts.WebScriptException;
 import org.springframework.extensions.webscripts.WebScriptRequest;
 
 /**
@@ -35,18 +33,16 @@ import org.springframework.extensions.webscripts.WebScriptRequest;
  * @author Derek Hulley
  * @since 3.4
  */
-public abstract class AbstractAuditWebScript extends AbstractWebScript
+public abstract class AbstractAuditWebScript extends DeclarativeWebScript
 {
-    public static final String PARAM_APP = "app";
+    public static final String PARAM_APPLICATION = "application";
     public static final String PARAM_PATH="path";
-    public static final String PARAM_ACTION = "action";
+    public static final String PARAM_ENABLED = "enabled";
     
+    public static final String JSON_KEY_ENABLED = "enabled";
     public static final String JSON_KEY_APPLICATIONS = "applications";
     public static final String JSON_KEY_NAME = "name";
     public static final String JSON_KEY_PATH = "path";
-    public static final String JSON_KEY_ENABLED = "enabled";
-    
-    private static enum AuditWebScriptAction {enable, disable};
     
     /**
      * Logger that can be used by subclasses.
@@ -76,59 +72,45 @@ public abstract class AbstractAuditWebScript extends AbstractWebScript
     /**
      * Get the application name from the request.
      * 
-     * @param mandatory         <tt>true</tt> if the application name is expected
      * @return                  Returns the application name or <tt>null</tt> if not present
      */
-    protected final String getApp(WebScriptRequest req, boolean mandatory)
+    protected final String getAppName(WebScriptRequest req)
     {
-        // All URLs must contain the application
+        Map<String, String> templateVars = req.getServiceMatch().getTemplateVars();
-        String paramApp = req.getParameter(PARAM_APP);
+        String app = templateVars.get(PARAM_APPLICATION);
-        if (paramApp == null && mandatory)
+        if (app == null || app.length() == 0)
         {
-            throw new WebScriptException(Status.STATUS_BAD_REQUEST, "audit.err.app.mandatory");
+            return null;
+        }
+        else
+        {
+            return app;
         }
-        return paramApp;
     }
     /**
-     * Get the path from the request.  If it is mandatory, then a value must have been supplied
+     * Get the path from the request.
-     * otherwise <tt>null</tt> is returned.
+     * 
-     * @param mandatory         <tt>true</tt> if the parameter is expected
      * @return                  Returns the path or <tt>null</tt> if not present
      */
     protected String getPath(WebScriptRequest req)
     {
-        String paramPath = req.getParameter(PARAM_PATH);
+        Map<String, String> templateVars = req.getServiceMatch().getTemplateVars();
+        String paramPath = templateVars.get(PARAM_PATH);
         if (paramPath == null || paramPath.length() == 0)
         {
             paramPath = null;
         }
         else if (!paramPath.startsWith("/"))
         {
-            throw new WebScriptException(Status.STATUS_BAD_REQUEST, "audit.err.path.startsWith");
+            // It won't ever, so we can expect to be here all the time
+            paramPath = "/" + paramPath;
         }
         return paramPath;
     }
     
     protected boolean getEnableDisable(WebScriptRequest req)
     {
-        Map<String, String> templateVars = req.getServiceMatch().getTemplateVars();
+        String enableStr = req.getParameter(PARAM_ENABLED);
-        String enableStr = templateVars.get(PARAM_ACTION);
+        return Boolean.parseBoolean(enableStr);
-        try
-        {
-            AuditWebScriptAction action = AuditWebScriptAction.valueOf(enableStr);
-            switch (action)
-            {
-                case enable:
-                    return true;
-                case disable:
-                    return false;
-                default:
-                    return false;
-            }
-        }
-        catch (IllegalArgumentException e)
-        {
-            throw new WebScriptException(Status.STATUS_BAD_REQUEST, "audit.err.action.invalid");
-        }
     }
 }

source/java/org/alfresco/repo/web/scripts/audit/AuditControlGet.java

@@ -18,15 +18,15 @@
  */
 package org.alfresco.repo.web.scripts.audit;
 
-import java.io.IOException;
-import java.nio.charset.Charset;
 import java.util.Collections;
-import java.util.Set;
+import java.util.HashMap;
+import java.util.Map;
 
+import org.alfresco.service.cmr.audit.AuditService.AuditApplication;
+import org.springframework.extensions.webscripts.Cache;
 import org.springframework.extensions.webscripts.Status;
+import org.springframework.extensions.webscripts.WebScriptException;
 import org.springframework.extensions.webscripts.WebScriptRequest;
-import org.springframework.extensions.webscripts.WebScriptResponse;
-import org.springframework.extensions.webscripts.json.JSONWriter;
 
 /**
  * @author Derek Hulley
@@ -35,60 +35,40 @@ import org.springframework.extensions.webscripts.json.JSONWriter;
 public class AuditControlGet extends AbstractAuditWebScript
 {
     @Override
-    public void execute(WebScriptRequest req, WebScriptResponse res) throws IOException
+    protected Map<String, Object> executeImpl(WebScriptRequest req, Status status, Cache cache)
     {
-        // return the unique transfer id (the lock id)
+        Map<String, Object> model = new HashMap<String, Object>(7);
-        JSONWriter json = new JSONWriter(res.getWriter());
+        
-
+        String appName = getAppName(req);
-        String app = getApp(req, false);
         String path = getPath(req);
-        Set<String> apps = auditService.getAuditApplications();
+        boolean enabledGlobal = auditService.isAuditEnabled();
+        Map<String, AuditApplication> appsByName = auditService.getAuditApplications();
         
         // Check that the application exists
-        if (app != null)
+        if (appName != null)
         {
-            if (apps.contains(app))
+            if (path == null)
             {
-                apps = Collections.singleton(app);
+                throw new WebScriptException(Status.STATUS_BAD_REQUEST, "audit.err.path.notProvided");
             }
-            else
+            
+            AuditApplication app = appsByName.get(appName);
+            if (app == null)
             {
-                apps = Collections.emptySet();
+                throw new WebScriptException(Status.STATUS_NOT_FOUND, "audit.err.app.notFound", app);
             }
+            // Discard all the other applications
+            appsByName = Collections.singletonMap(appName, app);
         }
         
-        boolean enabledGlobal = auditService.isAuditEnabled();
+        model.put(JSON_KEY_ENABLED, enabledGlobal);
-        json.startObject();
+        model.put(JSON_KEY_APPLICATIONS, appsByName.values());
-        {
-            json.writeValue(JSON_KEY_ENABLED, enabledGlobal);
-            json.startValue(JSON_KEY_APPLICATIONS);
-            {
-                json.startArray();
-                {
-                    for (String appName : apps)
-                    {
-                        boolean enabled = auditService.isAuditEnabled(appName, path);
-                        json.startObject();
-                        {
-                            json.writeValue(JSON_KEY_NAME, appName);
-                            json.writeValue(JSON_KEY_PATH, path);
-                            json.writeValue(JSON_KEY_ENABLED, enabled);
-                        }
-                        json.endObject();
-                    }
-                }
-                json.endArray();
-            }
-            json.endValue();
-        }
-        json.endObject();
         
-        // Close off
+        // Done
-        res.getWriter().close();
+        if (logger.isDebugEnabled())
-
+        {
-        res.setContentType("application/json");
+            logger.debug("Result: \n\tRequest: " + req + "\n\tModel: " + model);
-        res.setContentEncoding(Charset.defaultCharset().displayName());     // TODO: Should be settable on JSONWriter
+        }
-        //        res.addHeader("Content-Length", "" + length);             // TODO: Do we need this?
+        return model;
-        res.setStatus(Status.STATUS_OK);
     }
 }

source/java/org/alfresco/repo/web/scripts/audit/AuditControlPost.java

@@ -18,11 +18,12 @@
  */
 package org.alfresco.repo.web.scripts.audit;
 
-import java.io.IOException;
+import java.util.HashMap;
+import java.util.Map;
 
+import org.springframework.extensions.webscripts.Cache;
 import org.springframework.extensions.webscripts.Status;
 import org.springframework.extensions.webscripts.WebScriptRequest;
-import org.springframework.extensions.webscripts.WebScriptResponse;
 
 /**
  * @author Derek Hulley
@@ -31,14 +32,16 @@ import org.springframework.extensions.webscripts.WebScriptResponse;
 public class AuditControlPost extends AbstractAuditWebScript
 {
     @Override
-    public void execute(WebScriptRequest req, WebScriptResponse res) throws IOException
+    protected Map<String, Object> executeImpl(WebScriptRequest req, Status status, Cache cache)
     {
-        String app = getApp(req, false);
+        Map<String, Object> model = new HashMap<String, Object>(7);
+
+        String appName = getAppName(req);
         String path = getPath(req);
         
         boolean enable = getEnableDisable(req);
         
-        if (app == null)
+        if (appName == null)
         {
             // Global operation
             auditService.setAuditEnabled(enable);
@@ -46,12 +49,22 @@ public class AuditControlPost extends AbstractAuditWebScript
         else
         {
             // Apply to a specific application
-            auditService.enableAudit(app, path);
+            if (enable)
+            {
+                auditService.enableAudit(appName, path);
+            }
+            else
+            {
+                auditService.disableAudit(appName, path);
+            }
         }
-
+        model.put(JSON_KEY_ENABLED, enable);
-//        res.setContentType("application/json");
+        
-//        res.setContentEncoding(Charset.defaultCharset().displayName());     // TODO: Should be settable on JSONWriter
+        // Done
-        //        res.addHeader("Content-Length", "" + length);             // TODO: Do we need this?
+        if (logger.isDebugEnabled())
-        res.setStatus(Status.STATUS_OK);
+        {
+            logger.debug("Result: \n\tRequest: " + req + "\n\tModel: " + model);
+        }
+        return model;
     }
 }

source/java/org/alfresco/repo/web/scripts/audit/AuditWebScriptTest.java

@@ -18,15 +18,17 @@
  */
 package org.alfresco.repo.web.scripts.audit;
 
-import java.util.Set;
+import java.util.Map;
 
 import org.alfresco.repo.content.MimetypeMap;
 import org.alfresco.repo.security.authentication.AuthenticationUtil;
 import org.alfresco.repo.web.scripts.BaseWebScriptTest;
 import org.alfresco.service.cmr.audit.AuditService;
+import org.alfresco.service.cmr.audit.AuditService.AuditApplication;
 import org.json.JSONArray;
 import org.json.JSONObject;
 import org.springframework.context.ApplicationContext;
+import org.springframework.extensions.webscripts.Status;
 import org.springframework.extensions.webscripts.TestWebScriptServer;
 import org.springframework.extensions.webscripts.TestWebScriptServer.Response;
 
@@ -41,6 +43,7 @@ public class AuditWebScriptTest extends BaseWebScriptTest
     private ApplicationContext ctx;
     private AuditService auditService;
     private String admin;
+    private boolean globallyEnabled;
 
     @Override
     protected void setUp() throws Exception
@@ -51,12 +54,31 @@ public class AuditWebScriptTest extends BaseWebScriptTest
         admin = AuthenticationUtil.getAdminUserName();
         
         AuthenticationUtil.setFullyAuthenticatedUser(admin);
+        
+        globallyEnabled = auditService.isAuditEnabled();
+        // Only enable if required
+        if (!globallyEnabled)
+        {
+            auditService.setAuditEnabled(true);
+        }
     }
 
     @Override
     protected void tearDown() throws Exception
     {
         super.tearDown();
+        // Leave audit in correct state
+        try
+        {
+            if (!globallyEnabled)
+            {
+                auditService.setAuditEnabled(false);
+            }
+        }
+        catch (Throwable e)
+        {
+            throw new RuntimeException("Failed to set audit back to globally enabled/disabled state", e);
+        }
     }
     
     public void testGetWithoutPermissions() throws Exception
@@ -68,55 +90,46 @@ public class AuditWebScriptTest extends BaseWebScriptTest
     
     public void testGetIsAuditEnabledGlobally() throws Exception
     {
-        boolean checkEnabled = auditService.isAuditEnabled();
+        boolean wasEnabled = auditService.isAuditEnabled();
-        Set<String> checkApps = auditService.getAuditApplications();
+        Map<String, AuditApplication> checkApps = auditService.getAuditApplications();
 
         String url = "/api/audit/control";
         TestWebScriptServer.GetRequest req = new TestWebScriptServer.GetRequest(url);
         
-        Response response = sendRequest(req, 200, admin);
+        Response response = sendRequest(req, Status.STATUS_OK, admin);
         JSONObject json = new JSONObject(response.getContentAsString());
-        boolean enabled = json.getBoolean("enabled");
+        boolean enabled = json.getBoolean(AbstractAuditWebScript.JSON_KEY_ENABLED);
-        assertEquals("Mismatched global audit enabled", checkEnabled, enabled);
+        assertEquals("Mismatched global audit enabled", wasEnabled, enabled);
         JSONArray apps = json.getJSONArray(AbstractAuditWebScript.JSON_KEY_APPLICATIONS);
         assertEquals("Incorrect number of applications reported", checkApps.size(), apps.length());
     }
     
     public void testGetIsAuditEnabledMissingApp() throws Exception
     {
-        boolean checkEnabled = auditService.isAuditEnabled();
+        String url = "/api/audit/control/xxx";
-
-        String url = "/api/audit/control?app=xxx";
         TestWebScriptServer.GetRequest req = new TestWebScriptServer.GetRequest(url);
         
-        //First, we'll try the request as a simple, non-admin user (expect a 401)
+        sendRequest(req, 404, admin);
-        Response response = sendRequest(req, 200, admin);
-        JSONObject json = new JSONObject(response.getContentAsString());
-        boolean enabled = json.getBoolean("enabled");
-        assertEquals("Mismatched global audit enabled", checkEnabled, enabled);
-        JSONArray apps = json.getJSONArray(AbstractAuditWebScript.JSON_KEY_APPLICATIONS);
-        // We expect that the unknown application is returned with the others
-        assertEquals("Should not be any apps listed", 0, apps.length());
     }
     
-    public void testSetAuditEnabled() throws Exception
+    public void testSetAuditEnabledGlobally() throws Exception
     {
-        boolean checkEnabled = auditService.isAuditEnabled();
+        boolean wasEnabled = auditService.isAuditEnabled();
 
         // We need to set this back after the test
         try
         {
-            if (checkEnabled)
+            if (wasEnabled)
             {
-                String url = "/api/audit/control/disable";
+                String url = "/api/audit/control?enable=false";
                 TestWebScriptServer.PostRequest req = new TestWebScriptServer.PostRequest(url, "", MimetypeMap.MIMETYPE_JSON);
-                sendRequest(req, 200, admin);
+                sendRequest(req, Status.STATUS_OK, admin);
             }
             else
             {
-                String url = "/api/audit/control/enable";
+                String url = "/api/audit/control?enable=true";
                 TestWebScriptServer.PostRequest req = new TestWebScriptServer.PostRequest(url, "", MimetypeMap.MIMETYPE_JSON);
-                sendRequest(req, 200, admin);
+                sendRequest(req, Status.STATUS_OK, admin);
             }
             
             // Check that it worked
@@ -124,7 +137,72 @@ public class AuditWebScriptTest extends BaseWebScriptTest
         }
         finally
         {
-            auditService.setAuditEnabled(checkEnabled);
+            auditService.setAuditEnabled(wasEnabled);
+        }
+    }
+    
+    private static final String APP_REPO_NAME = "AlfrescoRepository";
+    private static final String APP_REPO_PATH = "/repository";
+    public void testGetIsAuditEnabledRepo() throws Exception
+    {
+        boolean wasEnabled = auditService.isAuditEnabled(APP_REPO_NAME, null);
+
+        String url = "/api/audit/control/" + APP_REPO_NAME + APP_REPO_PATH;
+        TestWebScriptServer.GetRequest req = new TestWebScriptServer.GetRequest(url);
+        
+        if (wasEnabled)
+        {
+            Response response = sendRequest(req, Status.STATUS_OK, admin);
+            JSONObject json = new JSONObject(response.getContentAsString());
+            JSONArray apps = json.getJSONArray(AbstractAuditWebScript.JSON_KEY_APPLICATIONS);
+            assertEquals("Incorrect number of applications reported", 1, apps.length());
+            JSONObject app = apps.getJSONObject(0);
+            String appName = app.getString(AbstractAuditWebScript.JSON_KEY_NAME);
+            String appPath = app.getString(AbstractAuditWebScript.JSON_KEY_PATH);
+            boolean appEnabled = app.getBoolean(AbstractAuditWebScript.JSON_KEY_ENABLED);
+            assertEquals("Mismatched application audit enabled", wasEnabled, appEnabled);
+            assertEquals("Mismatched application audit name", APP_REPO_NAME, appName);
+            assertEquals("Mismatched application audit path", APP_REPO_PATH, appPath);
+        }
+        else
+        {
+            
+        }
+    }
+    
+    public void testSetAuditEnabledRepo() throws Exception
+    {
+        boolean wasEnabled = auditService.isAuditEnabled(APP_REPO_NAME, APP_REPO_PATH);
+
+        // We need to set this back after the test
+        try
+        {
+            if (wasEnabled)
+            {
+                String url = "/api/audit/control/" + APP_REPO_NAME + APP_REPO_PATH + "?enable=false";
+                TestWebScriptServer.PostRequest req = new TestWebScriptServer.PostRequest(url, "", MimetypeMap.MIMETYPE_JSON);
+                sendRequest(req, Status.STATUS_OK, admin);
+            }
+            else
+            {
+                String url = "/api/audit/control/" + APP_REPO_NAME + APP_REPO_PATH + "?enable=true";
+                TestWebScriptServer.PostRequest req = new TestWebScriptServer.PostRequest(url, "", MimetypeMap.MIMETYPE_JSON);
+                sendRequest(req, Status.STATUS_OK, admin);
+            }
+            
+            // Check that it worked
+            testGetIsAuditEnabledRepo();
+        }
+        finally
+        {
+            if (wasEnabled)
+            {
+                auditService.enableAudit(APP_REPO_NAME, APP_REPO_PATH);
+            }
+            else
+            {
+                auditService.disableAudit(APP_REPO_NAME, APP_REPO_PATH);
+            }
         }
     }
 }