Web Scripts:

- add URL for generating reference docs for HTTP APIs - allow guest to issue opensearch git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@5373 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261
2025-08-07 17:49:17 +00:00 · 2007-03-09 16:07:00 +00:00
parent 7d1810db7b
commit cbe897337c
13 changed files with 237 additions and 29 deletions
--- a/config/alfresco/templates/webscripts/org/alfresco/index_get_desc.xml
+++ b/config/alfresco/templates/webscripts/org/alfresco/index_get_desc.xml
@@ -1,5 +1,6 @@
 <webscript>
  <shortname>Web Script Index</shortname>
-  <description>Index of all Web Scripts</description>
+  <description>Retrieve an index of all Web Scripts</description>
  <url format="html" template="/index" />
+  <url format="wiki" template="/index?format=wiki" />
 </webscript>
--- a/config/alfresco/templates/webscripts/org/alfresco/index_get_html.ftl
+++ b/config/alfresco/templates/webscripts/org/alfresco/index_get_html.ftl
@@ -2,7 +2,7 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
  <head> 
-    <title>Alfresco Web APIs</title> 
+    <title>Alfresco Web Scripts</title> 
    <link rel="stylesheet" href="${url.context}/css/main.css" TYPE="text/css">
  </head>
  <body>
@@ -11,24 +11,33 @@
       <table>
 	     <tr>
 	        <td><img src="${url.context}/images/logo/AlfrescoLogo32.png" alt="Alfresco" /></td>
-	        <td><nobr><span class="mainTitle">Alfresco Web APIs</span></nobr></td>
+	        <td><nobr><span class="mainTitle">Alfresco Web Scripts</span></nobr></td>
 	     </tr>
 	     <tr><td><td>Alfresco ${server.edition} v${server.version}
-	     <tr><td><td>${webscripts?size} apis - <a href="http://wiki.alfresco.com/wiki/REST">Online documentation</a>. <input type="submit" name="submit" value="Refresh list of Web APIs">
+	     <tr><td><td>${webscripts?size} Web Scripts - <a href="http://wiki.alfresco.com/wiki/HTTP_API">Online documentation</a>. <input type="submit" name="submit" value="Refresh list of Web Scripts">
 	    </table>
    </form>     
 	<br>
 	<br>
-    <table border="0" cellpadding="4">
-      <tr align="left"><td><b>Id<td><b>Method<td><b>Authentication</tr>
    <#list webscripts as webscript>
    <#assign desc = webscript.description>
-      <tr><td>${desc.id}<td>${desc.method}<td>${desc.requiredAuthentication}</tr>
-      <tr><td colspan="3">&nbsp;&nbsp;[${desc.description}]</tr>
-      <tr><td colspan="3"></tr>
+    <span class="mainSubTitle">${desc.shortName}</span>
+    <table>
    <#list desc.URIs as uri>
-         <tr><td>&nbsp;&nbsp;${uri.format}<#if uri.format = desc.defaultFormat> (default)</#if><td colspan="3"><a href="${url.serviceContext}${uri.URI}">${url.serviceContext}${uri.URI}</a></tr>
-      </#list>
+      <tr><td><a href="${url.serviceContext}${uri.URI}">${desc.method} ${url.serviceContext}${uri.URI}</a> => ${uri.format}<#if uri.format = desc.defaultFormat> (default)</#if>
    </#list>
+      <tr><td>
    </table>
+    <table>
+      <#if desc.description??><tr><td>Description:<td>${desc.description}<#else></#if>
+      <tr><td>Authentication:<td>${desc.requiredAuthentication}
+      <tr><td>Transaction:<td>${desc.requiredTransaction}
+      <tr><td>
+      <tr><td>Store:<td>${desc.sourceStore}
+      <tr><td>Location:<td><a href="${url.serviceContext}/description/${desc.id?replace(".", "/")}">${desc.sourceLocation}</a>
+      <tr><td>Id:<td>${desc.id}
+    </table>
+    <br>
+    </#list>
+  </body>
 </html>
--- a/config/alfresco/templates/webscripts/org/alfresco/index_get_wiki.ftl
+++ b/config/alfresco/templates/webscripts/org/alfresco/index_get_wiki.ftl
@@ -0,0 +1,38 @@
+Back to [[HTTP API]].
+
+
+'''NOTE:'''<br>
+'''This document describes features to be found in Alfresco v2.1 (not yet released).'''<br>
+'''Documentation for v2.0 can be found [[REST|here]].'''
+
+
+= Introduction =
+
+This page provides reference documentation for the Alfresco [[HTTP API]].
+
+Generated on ${date?datetime} from
+
+ GET <nowiki>http://</nowiki><host>:<port>/alfresco/service/index?format=wiki
+
+= API Reference =
+<#list webscripts as webscript>
+<#assign desc = webscript.description>
+
+== ${desc.shortName} ==
+
+<#if desc.description??><#if desc.description?ends_with(".")>${desc.description}<#else>${desc.description}.</#if><#else></#if>
+
+<#list desc.URIs as uri>
+ [http://localhost:8080/${url.serviceContext}${uri.URI} ${desc.method} ${url.serviceContext}${uri.URI}] => ${uri.format}<#if uri.format = desc.defaultFormat> (default)</#if>
+</#list>
+
+Requirements:
+* Authentication: ${desc.requiredAuthentication}
+* Transaction: ${desc.requiredTransaction}
+
+Definition:
+* Store: ${desc.sourceStore}
+* Location: ${desc.sourceLocation}
+* Id: ${desc.id}
+
+</#list>
--- a/config/alfresco/templates/webscripts/org/alfresco/index_post_html.ftl
+++ b/config/alfresco/templates/webscripts/org/alfresco/index_post_html.ftl
@@ -2,23 +2,24 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
  <head> 
-    <title>Alfresco Web APIs Maintenance</title> 
+    <title>Alfresco Web Scripts Maintenance</title> 
    <link rel="stylesheet" href="${url.context}/css/main.css" TYPE="text/css">
  </head>
  <body>
    <table>
     <tr>
        <td><img src="${url.context}/images/logo/AlfrescoLogo32.png" alt="Alfresco" /></td>
-        <td><nobr><span class="mainTitle">Alfresco Web APIs Maintenance</span></nobr></td>
+        <td><nobr><span class="mainTitle">Alfresco Web Scripts Maintenance</span></nobr></td>
     </tr>
     <tr><td><td>Alfresco ${server.edition} v${server.version}
-     <tr><td><td><a href="${url.match}">${webscripts?size} apis</a>.
    </table>
 	<br>
-    <table border="0" cellpadding="4">
-      <tr align="left"><td><b>Completed Task</tr>
+    <table>
+      <tr align="left"><td><b>Maintenance Completed</tr>
 <#list tasks as task>
      <tr><td>${task}<td></tr>
 </#list>
    </table>
+    <br>
+    <table><tr><td><a href="${url.match}">List Web Scripts</a></td></tr></table>
 </html>
--- a/config/alfresco/templates/webscripts/org/alfresco/repository/keywordsearch_get_desc.xml
+++ b/config/alfresco/templates/webscripts/org/alfresco/repository/keywordsearch_get_desc.xml
@@ -4,5 +4,5 @@
  <url format="html" template="/search/keyword?q={searchTerms}&amp;p={startPage?}&amp;c={count?}&amp;l={language?}&amp;guest={alf:guest?}"/>
  <url format="atom" template="/search/keyword?q={searchTerms}&amp;p={startPage?}&amp;c={count?}&amp;l={language?}&amp;guest={alf:guest?}&amp;format=atom"/>
  <url format="rss" template="/search/keyword?q={searchTerms}&amp;p={startPage?}&amp;c={count?}&amp;l={language?}&amp;guest={alf:guest?}&amp;format=rss"/>
-  <authentication>user</authentication>
+  <authentication>guest</authentication>
 </webscript>
--- a/config/alfresco/templates/webscripts/org/alfresco/scriptdescription_get_desc.xml
+++ b/config/alfresco/templates/webscripts/org/alfresco/scriptdescription_get_desc.xml
@@ -0,0 +1,5 @@
+<webscript>
+  <shortname>Web Script Description</shortname>
+  <description>Retrieve description document for identified Web Script</description>
+  <url format="html" template="/description/{serviceId}" />
+</webscript>
--- a/config/alfresco/web-scripts-application-context.xml
+++ b/config/alfresco/web-scripts-application-context.xml
@@ -110,11 +110,13 @@
      <property name="formats">
         <props>
            <prop key="html">text/html</prop>
+            <prop key="text">text/plain</prop>
            <prop key="xml">text/xml</prop>
            <prop key="atom">application/atom+xml</prop>
            <prop key="rss">application/rss+xml</prop>
            <prop key="json">application/json</prop>
            <prop key="opensearchdescription">application/opensearchdescription+xml</prop>
+            <prop key="wiki">text/plain</prop>
         </props>
      </property>
   </bean>
@@ -177,6 +179,9 @@
   <!--  Maintain list of available Web APIs -->
   <bean id="webscript.org.alfresco.index_post" class="org.alfresco.web.scripts.bean.IndexUpdate" parent="webscript" />

+   <!--  Retrieve Web Script Description Document -->
+   <bean id="webscript.org.alfresco.scriptdescription_get" class="org.alfresco.web.scripts.bean.ServiceDescription" parent="webscript" />
+
   <!--  List of registered (OpenSearch) search engines -->
   <bean id="webscript.org.alfresco.repository.searchengines_get" class="org.alfresco.web.scripts.bean.SearchEngines" parent="webscript">
      <property name="configService" ref="webscripts.config" />
--- a/source/java/org/alfresco/web/scripts/DeclarativeWebScriptRegistry.java
+++ b/source/java/org/alfresco/web/scripts/DeclarativeWebScriptRegistry.java
@@ -183,7 +183,6 @@ public class DeclarativeWebScriptRegistry implements WebScriptRegistry, Applicat
            if (logger.isDebugEnabled())
                logger.debug("Locating Web Scripts within " + apiStore.getBasePath());
            
-            String basePath = apiStore.getBasePath();
            String[] serviceDescPaths = apiStore.getDescriptionDocumentPaths();
            for (String serviceDescPath : serviceDescPaths)
            {
@@ -193,7 +192,7 @@ public class DeclarativeWebScriptRegistry implements WebScriptRegistry, Applicat
                try
                {
                    serviceDescIS = apiStore.getDescriptionDocument(serviceDescPath);
-                    serviceDesc = createDescription(basePath, serviceDescPath, serviceDescIS);
+                    serviceDesc = createDescription(apiStore, serviceDescPath, serviceDescIS);
                }
                catch(IOException e)
                {
@@ -219,7 +218,10 @@ public class DeclarativeWebScriptRegistry implements WebScriptRegistry, Applicat
                    if (logger.isDebugEnabled())
                    {
                        WebScript existingService = webscriptsById.get(id);
-                        logger.debug("Web Script description document " + serviceDesc.getSourceLocation() + " overridden by " + existingService.getDescription().getSourceLocation());
+                        WebScriptDescription existingDesc = existingService.getDescription();
+                        String msg = "Web Script description document " + serviceDesc.getSourceStore() + "/" + serviceDesc.getSourceLocation();
+                        msg += " overridden by " + existingDesc.getSourceStore() + "/" + existingDesc.getSourceLocation();
+                        logger.debug(msg);
                    }
                    continue;
                }
@@ -319,13 +321,13 @@ public class DeclarativeWebScriptRegistry implements WebScriptRegistry, Applicat
    /**
     * Create an Web Script Description
     * 
-     * @param basePath
+     * @param store
     * @param serviceDescPath
     * @param serviceDoc
     * 
     * @return  web script service description
     */
-    private WebScriptDescription createDescription(String basePath, String serviceDescPath, InputStream serviceDoc)
+    private WebScriptDescription createDescription(WebScriptStore store, String serviceDescPath, InputStream serviceDoc)
    {
        SAXReader reader = new SAXReader();
        try
@@ -430,7 +432,8 @@ public class DeclarativeWebScriptRegistry implements WebScriptRegistry, Applicat
            
            // construct service description
            WebScriptDescriptionImpl serviceDesc = new WebScriptDescriptionImpl();
-            serviceDesc.setSourceLocation(basePath + "/" + serviceDescPath);
+            serviceDesc.setSourceStore(store);
+            serviceDesc.setSourceLocation(serviceDescPath);
            serviceDesc.setId(id);
            serviceDesc.setShortName(shortName);
            serviceDesc.setDescription(description);
--- a/source/java/org/alfresco/web/scripts/WebScriptDescription.java
+++ b/source/java/org/alfresco/web/scripts/WebScriptDescription.java
@@ -24,6 +24,9 @@
 */
 package org.alfresco.web.scripts;

+import java.io.IOException;
+import java.io.InputStream;
+

 /**
 * Web Script Description
@@ -53,6 +56,21 @@ public interface WebScriptDescription
    }
    
    
+    /**
+     * Gets the source document of this web script
+     * 
+     * @return  source document
+     */
+    public InputStream getSourceDocument()
+        throws IOException;
+    
+    /**
+     * Gets the store this web script is located in
+     * 
+     * @return  path to store
+     */
+    public String getSourceStore();
+    
    /**
     * Gets the source document location of this service description
     * 
--- a/source/java/org/alfresco/web/scripts/WebScriptDescriptionImpl.java
+++ b/source/java/org/alfresco/web/scripts/WebScriptDescriptionImpl.java
@@ -24,6 +24,8 @@
 */
 package org.alfresco.web.scripts;

+import java.io.IOException;
+import java.io.InputStream;
 import java.util.HashMap;
 import java.util.Map;

@@ -35,6 +37,7 @@ import java.util.Map;
 */
 public class WebScriptDescriptionImpl implements WebScriptDescription
 {
+    private WebScriptStore sourceStore;
    private String sourceLocation;
    private String id;
    private String shortName;
@@ -47,6 +50,33 @@ public class WebScriptDescriptionImpl implements WebScriptDescription
    private Map<String, URI> uriByFormat;

    
+    /**
+     * Sets the source store
+     * 
+     * @param store  source store
+     */
+    public void setSourceStore(WebScriptStore store)
+    {
+        this.sourceStore = store;
+    }
+
+    /* (non-Javadoc)
+     * @see org.alfresco.web.scripts.WebScriptDescription#getSourceDocument()
+     */
+    public InputStream getSourceDocument()
+        throws IOException
+    {
+        return this.sourceStore.getDescriptionDocument(sourceLocation);
+    }
+
+    /* (non-Javadoc)
+     * @see org.alfresco.web.scripts.WebScriptDescription#getSourceStore()
+     */
+    public String getSourceStore()
+    {
+        return this.sourceStore.getBasePath();
+    }
+
    /**
     * Sets the source location
     * 
--- a/source/java/org/alfresco/web/scripts/bean/Index.java
+++ b/source/java/org/alfresco/web/scripts/bean/Index.java
@@ -33,7 +33,7 @@ import org.alfresco.web.scripts.WebScriptResponse;


 /**
- * Retrieves the list of available Web APIs
+ * Retrieves the list of available Web Scripts
 * 
 * @author davidc
 */
--- a/source/java/org/alfresco/web/scripts/bean/IndexUpdate.java
+++ b/source/java/org/alfresco/web/scripts/bean/IndexUpdate.java
@@ -35,7 +35,7 @@ import org.alfresco.web.scripts.WebScriptResponse;


 /**
- * Retrieves the list of available Web APIs
+ * Retrieves the list of available Web Scripts
 * 
 * @author davidc
 */
--- a/source/java/org/alfresco/web/scripts/bean/ServiceDescription.java
+++ b/source/java/org/alfresco/web/scripts/bean/ServiceDescription.java
@@ -0,0 +1,98 @@
+/*
+ * Copyright (C) 2005-2007 Alfresco Software Limited.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+
+ * This program 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 General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+
+ * As a special exception to the terms and conditions of version 2.0 of 
+ * the GPL, you may redistribute this Program in connection with Free/Libre 
+ * and Open Source Software ("FLOSS") applications as described in Alfresco's 
+ * FLOSS exception.  You should have recieved a copy of the text describing 
+ * the FLOSS exception, and it is also available here: 
+ * http://www.alfresco.com/legal/licensing"
+ */
+package org.alfresco.web.scripts.bean;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+
+import org.alfresco.repo.content.MimetypeMap;
+import org.alfresco.web.scripts.AbstractWebScript;
+import org.alfresco.web.scripts.WebScript;
+import org.alfresco.web.scripts.WebScriptDescription;
+import org.alfresco.web.scripts.WebScriptException;
+import org.alfresco.web.scripts.WebScriptRequest;
+import org.alfresco.web.scripts.WebScriptResponse;
+
+
+/**
+ * Retrieves a Web Script Description Document 
+ * 
+ * @author davidc
+ */
+public class ServiceDescription extends AbstractWebScript
+{
+
+    public void execute(WebScriptRequest req, WebScriptResponse res) throws IOException
+    {
+        // extract web script id
+        String extensionPath = req.getExtensionPath();
+        if (extensionPath == null || extensionPath.length() == 0)
+        {
+            throw new WebScriptException("Web Script Id not provided");
+        }
+        String scriptId = extensionPath.replace("/", ".");
+        
+        // locate web script
+        WebScript script = getWebScriptRegistry().getWebScript(scriptId);
+        if (script == null)
+        {
+            throw new WebScriptException("Web Script Id '" + scriptId + "' not found");
+        }
+
+        // retrieve description document
+        WebScriptDescription desc = script.getDescription();
+        InputStream serviceDescIS = null;
+        try
+        {
+            serviceDescIS = desc.getSourceDocument();
+            OutputStream out = res.getOutputStream();
+            res.setContentType(MimetypeMap.MIMETYPE_XML + ";charset=UTF-8");
+            byte[] buffer = new byte[2048];
+            int read = serviceDescIS.read(buffer);
+            while (read != -1)
+            {
+                out.write(buffer, 0, read);
+                read = serviceDescIS.read(buffer);
+            }
+        }
+        catch(IOException e)
+        {
+            throw new WebScriptException("Failed to read Web Script description document for '" + scriptId + "'", e);
+        }
+        finally
+        {
+            try
+            {
+                if (serviceDescIS != null) serviceDescIS.close();
+            }
+            catch(IOException e)
+            {
+                // NOTE: ignore close exception
+            }
+        }
+    }
+
+}