fix javadocs for 1.0.0 release

sangupta · Dec 23, 2016 · 5d5345f · 5d5345f
1 parent a3bcc0e
commit 5d5345f
Show file tree

Hide file tree

Showing 24 changed files with 288 additions and 95 deletions.
diff --git a/src/main/java/com/sangupta/jerry/web/filters/ExceptionCatchingFilter.java b/src/main/java/com/sangupta/jerry/web/filters/ExceptionCatchingFilter.java
@@ -43,10 +43,13 @@
  * {@link RuntimeException}.
  * 
  * @author sangupta
- *
+ * @since 1.0.0
  */
 public class ExceptionCatchingFilter implements Filter {
 
+	/**
+	 * My internal logger
+	 */
 	private static final Logger LOGGER = LoggerFactory.getLogger(ExceptionCatchingFilter.class);
 
 	/**
@@ -76,7 +79,23 @@ public void init(FilterConfig filterConfig) throws ServletException {
 	}
 
 	/**
-	 * @see javax.servlet.Filter#doFilter(javax.servlet.ServletRequest, javax.servlet.ServletResponse, javax.servlet.FilterChain)
+	 * @param request
+	 *            the incoming {@link ServletRequest} instance
+	 * 
+	 * @param response
+	 *            the outgoing {@link ServletResponse} instance
+	 * 
+	 * @param chain
+	 *            the {@link FilterChain} being executed
+	 * 
+	 * @throws IOException
+	 *             if something fails
+	 * 
+	 * @throws ServletException
+	 *             if something fails
+	 *             
+	 * @see javax.servlet.Filter#doFilter(javax.servlet.ServletRequest,
+	 *      javax.servlet.ServletResponse, javax.servlet.FilterChain)
 	 */
 	@Override
 	public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {

diff --git a/src/main/java/com/sangupta/jerry/web/filters/JavascriptMinificationFilter.java b/src/main/java/com/sangupta/jerry/web/filters/JavascriptMinificationFilter.java
@@ -57,12 +57,18 @@
  * using Google closure compiler.
  * 
  * @author sangupta
- *
+ * @since 1.0.0
  */
 public class JavascriptMinificationFilter implements Filter {
 
+	/**
+	 * My internal logger
+	 */
 	private static final Logger LOGGER = LoggerFactory.getLogger(JavascriptMinificationFilter.class);
 
+	/**
+	 * Cache that holds minified files so that they can be served faster
+	 */
     private final Map<String, ModifiedServletResponse> CACHE = new HashMap<String, ModifiedServletResponse>();
 
 	@Override
@@ -78,6 +84,23 @@ public void destroy() {
 	/**
 	 * Compress JS and CSS files using the Google compiler.
 	 * 
+	 * @param servletRequest
+	 *            the incoming {@link ServletRequest} instance
+	 * 
+	 * @param servletResponse
+	 *            the outgoing {@link ServletResponse} instance
+	 * 
+	 * @param filterChain
+	 *            the {@link FilterChain} being executed
+	 * 
+	 * @throws IOException
+	 *             if something fails
+	 * 
+	 * @throws ServletException
+	 *             if something fails
+	 *             
+	 * @see javax.servlet.Filter#doFilter(javax.servlet.ServletRequest,
+	 *      javax.servlet.ServletResponse, javax.servlet.FilterChain)
 	 */
 	@Override
 	public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
@@ -197,12 +220,16 @@ private boolean isJavascript(String type) {
     }
 
     /**
-     * Compress the Javascript.
-     * 
-     * @param uri
-     * @param code
-     * @return
-     */
+	 * Compress the Javascript.
+	 * 
+	 * @param uri
+	 *            the URI for the JS file
+	 * 
+	 * @param code
+	 *            the actual Javascript code
+	 * 
+	 * @return the compressed code for the JS file
+	 */
     private String compressJavascriptEmbedded(final String uri, final String code) {
         if(code == null || code.isEmpty()) {
             return code;
@@ -230,11 +257,13 @@ private String compressJavascriptEmbedded(final String uri, final String code) {
     }
 
     /**
-     * UnGZIP a given byte stream.
-     * 
-     * @param bytes
-     * @return
-     */
+	 * UnGZIP a given byte stream.
+	 * 
+	 * @param bytes
+	 *            the byte-stream to unGZIP
+	 * 
+	 * @return the unGZIPed byte-array
+	 */
     private byte[] unGZip(byte[] bytes) {
         if(bytes == null || bytes.length == 0) {
             return bytes;
@@ -280,11 +309,14 @@ private byte[] unGZip(byte[] bytes) {
     }
 
     /**
-     * Check if a byte stream is GZIP compressed or not.
-     * 
-     * @param bytes
-     * @return
-     */
+	 * Check if a byte stream is GZIP compressed or not.
+	 * 
+	 * @param bytes
+	 *            the byte-array representing the stream
+	 * 
+	 * @return <code>true</code> if its compressed with GZIP, <code>false</code>
+	 *         otherwise
+	 */
     private boolean isGZip(byte[] bytes) {
         if(bytes == null || bytes.length == 0) {
             return false;

diff --git a/src/main/java/com/sangupta/jerry/web/filters/JavascriptReorderingFilter.java b/src/main/java/com/sangupta/jerry/web/filters/JavascriptReorderingFilter.java
@@ -51,7 +51,7 @@
  * parser to achieve the same.
  * 
  * @author sangupta
- *
+ * @since 1.0.0
  */
 public class JavascriptReorderingFilter implements Filter {
 
@@ -67,6 +67,29 @@ public void destroy() {
 		// do nothing
 	}
 
+	/**
+	 * Move all included JavaScript files to the end of <code>BODY</code> tag in the same order
+	 * that they appeared in the original HTML response.
+	 * 
+	 * @param servletRequest
+	 *            the incoming {@link ServletRequest} instance
+	 * 
+	 * @param servletResponse
+	 *            the outgoing {@link ServletResponse} instance
+	 * 
+	 * @param filterChain
+	 *            the {@link FilterChain} being executed
+	 * 
+	 * @throws IOException
+	 *             if something fails
+	 * 
+	 * @throws ServletException
+	 *             if something fails
+	 *             
+	 * @see javax.servlet.Filter#doFilter(javax.servlet.ServletRequest,
+	 *      javax.servlet.ServletResponse, javax.servlet.FilterChain)
+	 *      
+	 */
 	@Override
 	public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
 		// try and see if this request is for an HTML page

diff --git a/src/main/java/com/sangupta/jerry/web/filters/LeverageBrowserCacheFilter.java b/src/main/java/com/sangupta/jerry/web/filters/LeverageBrowserCacheFilter.java
@@ -22,6 +22,8 @@
 package com.sangupta.jerry.web.filters;
 
 import java.io.IOException;
+import java.util.HashSet;
+import java.util.Set;
 
 import javax.servlet.Filter;
 import javax.servlet.FilterChain;
@@ -35,6 +37,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import com.sangupta.jerry.util.AssertUtils;
 import com.sangupta.jerry.util.DateUtils;
 
 /**
@@ -43,14 +46,50 @@
  * number of calls.
  *
  * @author sangupta
+ * @since 1.0.0
  */
 public class LeverageBrowserCacheFilter implements Filter {
 
-    private static final String[] STATIC_RESOURCE_EXTENSIONS = { ".css", ".png" , ".js", ".gif", ".jpg" };
+    private static final Set<String> STATIC_RESOURCE_EXTENSIONS = new HashSet<>();
+
+    static {
+    	STATIC_RESOURCE_EXTENSIONS.add(".css");
+    	STATIC_RESOURCE_EXTENSIONS.add(".png");
+    	STATIC_RESOURCE_EXTENSIONS.add(".js");
+    	STATIC_RESOURCE_EXTENSIONS.add(".git");
+    	STATIC_RESOURCE_EXTENSIONS.add(".jpg");
+    	STATIC_RESOURCE_EXTENSIONS.add(".jpeg");
+    	STATIC_RESOURCE_EXTENSIONS.add(".woff");
+    	STATIC_RESOURCE_EXTENSIONS.add(".bmp");
+    	STATIC_RESOURCE_EXTENSIONS.add(".tiff");
+    }
 
     private static final Logger LOGGER = LoggerFactory.getLogger(LeverageBrowserCacheFilter.class);
 
     private static String ONE_YEAR_AS_SECONDS = String.valueOf(((long) DateUtils.ONE_YEAR / 1000l));
+
+    /**
+	 * Add the given extension to the list of static resources.
+	 * 
+	 * @param extension
+	 *            the extension to add
+	 * 
+	 * @return <code>true</code> if extension was added, <code>false</code>
+	 *         otherwise
+	 */
+    public static boolean addStaticExtension(String extension) {
+    	if(AssertUtils.isEmpty(extension)) {
+    		return false;
+    	}
+
+    	if(!extension.startsWith(".")) {
+    		extension = "." + extension;
+    	}
+
+    	extension = extension.toLowerCase();
+
+    	return STATIC_RESOURCE_EXTENSIONS.add(extension);
+    }
 
     @Override
     public void init(FilterConfig filterConfig) throws ServletException {
@@ -63,13 +102,27 @@ public void destroy() {
     }
 
     /**
-     *
-     * @param servletRequest
-     * @param servletResponse
-     * @param filterChain
-     * @throws IOException
-     * @throws ServletException
-     */
+	 * Execute the filter by appending the <b>Expires</b> and
+	 * <b>Cache-Control</b> response headers.
+	 * 
+	 * @param servletRequest
+	 *            the incoming {@link ServletRequest} instance
+	 * 
+	 * @param servletResponse
+	 *            the outgoing {@link ServletResponse} instance
+	 * 
+	 * @param filterChain
+	 *            the {@link FilterChain} being executed
+	 * 
+	 * @throws IOException
+	 *             if something fails
+	 * 
+	 * @throws ServletException
+	 *             if something fails
+	 * 
+	 * @see javax.servlet.Filter#doFilter(javax.servlet.ServletRequest,
+	 *      javax.servlet.ServletResponse, javax.servlet.FilterChain)
+	 */
     @Override
     public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
         HttpServletRequest request = (HttpServletRequest) servletRequest;
@@ -109,13 +162,7 @@ private boolean isStaticResource(String uri) {
         }
 
         String currentExtension = uri.substring(index);
-        for(String extension : STATIC_RESOURCE_EXTENSIONS) {
-            if(extension.equals(currentExtension)) {
-                return true;
-            }
-        }
-
-        // nothing found
-        return false;
+
+        return STATIC_RESOURCE_EXTENSIONS.contains(currentExtension);
     }
 }
diff --git a/src/main/java/com/sangupta/jerry/web/filters/RequestCapturingFilter.java b/src/main/java/com/sangupta/jerry/web/filters/RequestCapturingFilter.java
@@ -41,7 +41,7 @@
  * information is logged at INFO level.
  * 
  * @author sangupta
- *
+ * @since 1.0.0
  */
 public class RequestCapturingFilter implements Filter {
 
@@ -52,6 +52,27 @@ public void init(FilterConfig filterConfig) throws ServletException {
 		// do nothing
 	}
 
+	/**
+	 * 
+	 * @param request
+	 *            the incoming {@link ServletRequest} instance
+	 * 
+	 * @param response
+	 *            the outgoing {@link ServletResponse} instance
+	 * 
+	 * @param chain
+	 *            the {@link FilterChain} being executed
+	 * 
+	 * @throws IOException
+	 *             if something fails
+	 * 
+	 * @throws ServletException
+	 *             if something fails
+	 *             
+	 * @see javax.servlet.Filter#doFilter(javax.servlet.ServletRequest,
+	 *      javax.servlet.ServletResponse, javax.servlet.FilterChain)
+	 *      
+	 */
 	@Override
 	public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
 		if(LOGGER.isInfoEnabled()) {

diff --git a/src/main/java/com/sangupta/jerry/web/taglib/AllJavascriptTag.java b/src/main/java/com/sangupta/jerry/web/taglib/AllJavascriptTag.java
@@ -37,7 +37,8 @@
  * location in the page.
  * 
  * @author sangupta
- *
+ * @since 1.0.0
+ * 
  */
 public class AllJavascriptTag extends SimpleTagSupport {
 

diff --git a/src/main/java/com/sangupta/jerry/web/taglib/AnonymousTag.java b/src/main/java/com/sangupta/jerry/web/taglib/AnonymousTag.java
@@ -27,7 +27,11 @@
 import com.sangupta.jerry.security.SecurityContext;
 
 /**
+ * Include the body if the user is an anoymous user, as returned by the
+ * {@link SecurityContext#isAnonymousUser()} method.
+ * 
  * @author sangupta
+ * @since 1.0.0
  * 
  */
 public class AnonymousTag extends BodyTagSupport {

diff --git a/src/main/java/com/sangupta/jerry/web/taglib/Base62Tag.java b/src/main/java/com/sangupta/jerry/web/taglib/Base62Tag.java
@@ -30,8 +30,11 @@
 import com.sangupta.jerry.encoder.Base62Encoder;
 
 /**
+ * Encode/decode the given value via {@link Base62Encoder}.
+ * 
  * @author sangupta
- *
+ * @since 1.0.0
+ * 
  */
 public class Base62Tag extends SimpleTagSupport {
 

diff --git a/src/main/java/com/sangupta/jerry/web/taglib/Base64Tag.java b/src/main/java/com/sangupta/jerry/web/taglib/Base64Tag.java
@@ -33,8 +33,12 @@
 import com.sangupta.jerry.util.AssertUtils;
 
 /**
+ * Encode/decode the given value via {@link Base64Encoder} - optionally can
+ * store the encoded/decoded value in a request attribute.
+ * 
  * @author sangupta
- *
+ * @since 1.0.0
+ * 
  */
 public class Base64Tag extends SimpleTagSupport {
 

diff --git a/src/main/java/com/sangupta/jerry/web/taglib/CheckBoxTag.java b/src/main/java/com/sangupta/jerry/web/taglib/CheckBoxTag.java
@@ -31,7 +31,7 @@
 
 /**
  * @author sangupta
- *
+ * @since 1.0.0
  */
 public class CheckBoxTag extends SimpleTagSupport {