jspwiki-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dvit...@apache.org
Subject svn commit: r1655958 - in /jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax: AjaxUtil.java WikiAjaxDispatcherServlet.java WikiAjaxServlet.java
Date Fri, 30 Jan 2015 08:25:31 GMT
Author: dvittor
Date: Fri Jan 30 08:25:30 2015
New Revision: 1655958

URL: http://svn.apache.org/r1655958
Log:
Updated javadoc documentation.

Modified:
    jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/AjaxUtil.java
    jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxDispatcherServlet.java
    jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxServlet.java

Modified: jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/AjaxUtil.java
URL: http://svn.apache.org/viewvc/jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/AjaxUtil.java?rev=1655958&r1=1655957&r2=1655958&view=diff
==============================================================================
--- jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/AjaxUtil.java (original)
+++ jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/AjaxUtil.java Fri Jan 30
08:25:30 2015
@@ -25,10 +25,20 @@ import org.apache.commons.lang.StringUti
 
 import com.google.gson.Gson;
 
+/**
+ * Helpful utilities for the Ajax functions.
+ * 
+ * @since 2.10.2-svn12
+ */
 public class AjaxUtil extends HttpServlet {
 	private static final long serialVersionUID = 3170439306358345408L;
 	private static Gson gson = new Gson();
-	
+
+	/**
+	 * Uses Google Gson (https://code.google.com/p/google-gson/) to convert to JSON
+	 * @param input the object to be converted to JSON
+	 * @return the JSON string of the object
+	 */
 	public static String toJson(Object input) {
 		String result = "";
 		if (input != null) {
@@ -37,6 +47,18 @@ public class AjaxUtil extends HttpServle
 		return result;
 	}
 	
+	/**
+	 * Given a requestUri path, find the next uri "fragment" after the "/lastPart/" one.
+	 * E.g. given url "/test/abc/travel", and lastPart "abc", this will return "travel". Given
lastPart "test" will return "abc".
+	 * 
+	 * This could be done better using a <a href="http://en.wikipedia.org/wiki/URL_Template">URITemplate</a>
+	 * (as <a href="https://tools.ietf.org/html/rfc6570">RFC6570</a>) 
+	 * 
+	 * @param path the RequestURI to search usually done by calling request.getRequestUri().
+	 * @param lastPart the previousPart of the path to search after.
+	 * @return the next part of the path.
+	 * @throws ServletException
+	 */
 	public static String getNextPathPart(String path, String lastPart) throws ServletException
{
         String result = null;
         if (StringUtils.isBlank(path)) {

Modified: jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxDispatcherServlet.java
URL: http://svn.apache.org/viewvc/jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxDispatcherServlet.java?rev=1655958&r1=1655957&r2=1655958&view=diff
==============================================================================
--- jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxDispatcherServlet.java
(original)
+++ jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxDispatcherServlet.java
Fri Jan 30 08:25:30 2015
@@ -37,14 +37,15 @@ import org.apache.commons.lang.StringUti
 import org.apache.log4j.Logger;
 import org.apache.wiki.WikiEngine;
 import org.apache.wiki.WikiSession;
+import org.apache.wiki.auth.AuthorizationManager;
 import org.apache.wiki.auth.permissions.PagePermission;
 import org.apache.wiki.util.TextUtil;
 
 /**
  * This provides a simple ajax servlet for handling /ajax/<ClassName> requests.
- * HttpServlet classes need to be registered using {@link WikiAjaxDispatcherServlet.registerServlet(HttpServlet)}
+ * HttpServlet classes need to be registered using {@link WikiAjaxDispatcherServlet.registerServlet(WikiAjaxServlet)}
  *
- * @since 2.10.2-svn10
+ * @since 2.10.2-svn12
  */
 public class WikiAjaxDispatcherServlet extends HttpServlet {
 	private static final long serialVersionUID = 1L;
@@ -54,6 +55,9 @@ public class WikiAjaxDispatcherServlet e
 
     /**
      * {@inheritDoc}
+     * 
+     * This sets the AjaxPath to "/ajax/" as configured in "jspwiki.ajax.url.prefix".
+     * Note: Do not change this without also changing the web.xml file.
      */
     public void init(ServletConfig config)
             throws ServletException {
@@ -64,19 +68,26 @@ public class WikiAjaxDispatcherServlet e
     }
 
     /**
-     * Register a servlet using the class simple name as the alias
+     * Register a {@link WikiAjaxServlet} using the servlet mapping as the alias
      */
     public static void registerServlet(WikiAjaxServlet servlet) {
     	registerServlet(servlet.getServletMapping(),servlet);
     }
     
     /**
-     * Register a servlet with an alias, using the default permission {@link PagePermission.VIEW}.
+     * Register a {@link WikiAjaxServlet} with a specific alias, and default permission {@link
PagePermission.VIEW}.
      */
     public static void registerServlet(String alias, WikiAjaxServlet servlet) {
     	registerServlet(alias, servlet, PagePermission.VIEW);
     }
     
+    /**
+     * Regster a {@link WikiAjaxServlet} given an alias, the servlet, and the permission.
+     * Thie creates a temporary bundle object called {@link AjaxServletContainer} 
+     * @param alias the uri link to this servlet
+     * @param servlet the servlet being registered
+     * @param perm the permission required to execute the servlet.
+     */
     public static void registerServlet(String alias, WikiAjaxServlet servlet, Permission
perm) {
     	log.info("WikiAjaxDispatcherServlet registering "+alias+"="+servlet+" perm="+perm);
         ajaxServlets.put(alias,new AjaxServletContainer(alias, servlet, perm));
@@ -101,7 +112,7 @@ public class WikiAjaxDispatcherServlet e
     /**
      * The main method which get the requestURI "/ajax/<ServletName>", gets the 
      * {@link this.getServletName} and finds the servlet using {@link this.findServletByName}.

-     * It then calls servlet.service().
+     * It then calls {@link WikiAjaxServlet.service} method.
      * @param req the inbound request
      * @param res the outbound response
      * @throws IOException
@@ -138,6 +149,13 @@ public class WikiAjaxDispatcherServlet e
         }
     }
     
+    /**
+     * Validate the permission of the {@link WikiAjaxServlet} using the {@link AuthorizationManager.checkPermission}
+     * 
+     * @param req the servlet request
+     * @param container the container info of the servlet
+     * @return true if permission is valid
+     */
     private boolean validatePermission(HttpServletRequest req, AjaxServletContainer container)
{
         WikiEngine e = WikiEngine.getInstance(req.getSession().getServletContext(), null);
         boolean valid = false;
@@ -148,7 +166,8 @@ public class WikiAjaxDispatcherServlet e
     }
 
     /**
-     * Get the name of the servlet given the requestURI.
+     * Get the ServletName from the requestURI "/ajax/<ServletName>", using {@link
AjaxUtil.getNextPathPath}.
+     * 
      * @param path The requestURI, which must contains "/ajax/<ServletName>" in the
path
      * @return The ServletName for the requestURI, or null
      * @throws ServletException if the path is invalid
@@ -158,15 +177,21 @@ public class WikiAjaxDispatcherServlet e
     }
     
     /**
-     * Find the servlet as registered in {@link WikiAjaxDispatcherServlet.register}.
+     * Find the {@link AjaxServletContainer} as registered in {@link WikiAjaxDispatcherServlet.registerServlet}.
      * 
      * @param servletName the name of the servlet from {@link this.getServletName}
      * @return The first servlet found, or null.
      */
-    public AjaxServletContainer findServletContainer(String servletAlias) {
+    private AjaxServletContainer findServletContainer(String servletAlias) {
     	return ajaxServlets.get(servletAlias);
     }
 
+    /**
+     * Find the {@link WikiAjaxServlet} given the servletAlias that it was registered with.
+     * 
+     * @param servletAlias the value provided to {@link this.registerServlet}
+     * @return
+     */
     public WikiAjaxServlet findServletByName(String servletAlias) {
     	AjaxServletContainer container = ajaxServlets.get(servletAlias);
     	if (container != null) {

Modified: jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxServlet.java
URL: http://svn.apache.org/viewvc/jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxServlet.java?rev=1655958&r1=1655957&r2=1655958&view=diff
==============================================================================
--- jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxServlet.java (original)
+++ jspwiki/trunk/jspwiki-war/src/main/java/org/apache/wiki/ajax/WikiAjaxServlet.java Fri
Jan 30 08:25:30 2015
@@ -7,6 +7,14 @@ import javax.servlet.ServletException;
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
 
+import org.apache.wiki.plugin.SampleAjaxPlugin;
+
+/**
+ * An interface for a servlet that wants to use Ajax functionality.
+ * See {@link SampleAjaxPlugin}
+ * 
+ * @since 2.10.2-svn12
+ */
 public interface WikiAjaxServlet {
 
 	public String getServletMapping();



Mime
View raw message