Javadoc refinements, exception fine-tuning, general polishing

Issue: SPR-13034

Author: jhoeller

spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupConfig.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,9 +19,9 @@
 import groovy.text.markup.MarkupTemplateEngine;
 
 /**
- * Interface to be implemented by objects that configure and manage a
- * Groovy MarkupTemplateEngine for automatic lookup in a web environment.
- * Detected and used by GroovyMarkupView.
+ * Interface to be implemented by objects that configure and manage a Groovy
+ * {@link MarkupTemplateEngine} for automatic lookup in a web environment.
+ * Detected and used by {@link GroovyMarkupView}.
  *
  * @author Brian Clozel
  * @since 4.1

spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupConfigurer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -46,7 +46,6 @@
  *
  * @Bean
  * public GroovyMarkupConfig groovyMarkupConfigurer() {
- *
  *     GroovyMarkupConfigurer configurer = new GroovyMarkupConfigurer();
  *     configurer.setResourceLoaderPath("classpath:/WEB-INF/groovymarkup/");
  *     return configurer;

spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupView.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -35,8 +35,7 @@
 import org.springframework.web.util.NestedServletException;
 
 /**
- * An {@link org.springframework.web.servlet.view.AbstractTemplateView AbstractTemplateView}
- * based on Groovy XML/XHTML markup templates.
+ * An {@link AbstractTemplateView} subclass based on Groovy XML/XHTML markup templates.
  *
  * <p>Spring's Groovy Markup Template support requires Groovy 2.3.1 and higher.
  *

spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupViewResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,10 +21,9 @@
 import org.springframework.web.servlet.view.AbstractTemplateViewResolver;
 
 /**
- * Convenience subclass of
- * {@link org.springframework.web.servlet.view.AbstractTemplateViewResolver}
- * that supports {@link GroovyMarkupView} (i.e. Groovy XML/XHTML markup templates)
- * and custom subclasses of it.
+ * Convenience subclass of @link AbstractTemplateViewResolver} that supports
+ * {@link GroovyMarkupView} (i.e. Groovy XML/XHTML markup templates) and
+ * custom subclasses of it.
  *
  * <p>The view class for all views created by this resolver can be specified
  * via the {@link #setViewClass(Class)} property.

spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/package-info.java

@@ -1,6 +1,6 @@
 /**
  * Support classes for the integration of
- * <a href="http://beta.groovy-lang.org/docs/groovy-2.3.0/html/documentation/markup-template-engine.html">
+ * <a href="http://docs.groovy-lang.org/docs/next/html/documentation/template-engines.html#_the_markuptemplateengine">
  * Groovy Templates</a> as Spring web view technology.
  * Contains a View implementation for Groovy templates.
  */

spring-webmvc/src/main/java/org/springframework/web/servlet/view/script/ScriptTemplateConfig.java

@@ -21,28 +21,53 @@
 
 /**
  * Interface to be implemented by objects that configure and manage a
- * {@link ScriptEngine} for automatic lookup in a web environment.
+ * JSR-223 {@link ScriptEngine} for automatic lookup in a web environment.
  * Detected and used by {@link ScriptTemplateView}.
  *
  * @author Sebastien Deleuze
  * @since 4.2
  */
 public interface ScriptTemplateConfig {
 
+	/**
+	 * Return the {@link ScriptEngine} to use by the views.
+	 */
 	ScriptEngine getEngine();
 
+	/**
+	 * Return the engine name that will be used to instantiate the {@link ScriptEngine}.
+	 */
 	String getEngineName();
 
+	/**
+	 * Return whether to use a shared engine for all threads or whether to create
+	 * thread-local engine instances for each thread.
+	 */
+	Boolean isSharedEngine();
+
+	/**
+	 * Return the scripts to be loaded by the script engine (library or user provided).
+	 */
 	String[] getScripts();
 
+	/**
+	 * Return the object where the render function belongs (optional).
+	 */
 	String getRenderObject();
 
+	/**
+	 * Return the render function name (mandatory).
+	 */
 	String getRenderFunction();
 
+	/**
+	 * Return the charset used to read script and template files.
+	 */
 	Charset getCharset();
 
+	/**
+	 * Return the resource loader path(s) via a Spring resource location.
+	 */
 	String getResourceLoaderPath();
 
-	Boolean isShareEngine();
-
 }

spring-webmvc/src/main/java/org/springframework/web/servlet/view/script/ScriptTemplateConfigurer.java

@@ -17,7 +17,6 @@
 package org.springframework.web.servlet.view.script;
 
 import java.nio.charset.Charset;
-
 import javax.script.ScriptEngine;
 
 /**
@@ -40,9 +39,9 @@
  * }
  * </pre>
  *
- * <p>It is possible to use non thread-safe script engines and templating libraries, like
- * Handlebars or React running on Nashorn, by setting the
- * {@link #setSharedEngine(Boolean) sharedEngine} property to {@code false}.
+ * <p><b>NOTE:</b> It is possible to use non thread-safe script engines and
+ * templating libraries, like Handlebars or React running on Nashorn, by setting
+ * the {@link #setSharedEngine sharedEngine} property to {@code false}.
  *
  * @author Sebastien Deleuze
  * @since 4.2
@@ -54,6 +53,8 @@ public class ScriptTemplateConfigurer implements ScriptTemplateConfig {
 
 	private String engineName;
 
+	private Boolean sharedEngine;
+
 	private String[] scripts;
 
 	private String renderObject;
@@ -64,17 +65,14 @@ public class ScriptTemplateConfigurer implements ScriptTemplateConfig {
 
 	private String resourceLoaderPath;
 
-	private Boolean sharedEngine;
 
 	/**
 	 * Set the {@link ScriptEngine} to use by the view.
 	 * The script engine must implement {@code Invocable}.
 	 * You must define {@code engine} or {@code engineName}, not both.
-	 *
 	 * <p>When the {@code sharedEngine} flag is set to {@code false}, you should not specify
 	 * the script engine with this setter, but with the {@link #setEngineName(String)}
-	 * one (since it implies multiple lazy instanciations of the script engine).
-	 *
+	 * one (since it implies multiple lazy instantiations of the script engine).
 	 * @see #setEngineName(String)
 	 */
 	public void setEngine(ScriptEngine engine) {
@@ -101,17 +99,35 @@ public String getEngineName() {
 		return this.engineName;
 	}
 
+	/**
+	 * When set to {@code false}, use thread-local {@link ScriptEngine} instances instead
+	 * of one single shared instance. This flag should be set to {@code false} for those
+	 * using non thread-safe script engines and templating libraries, like Handlebars or
+	 * React running on Nashorn for example.
+	 * <p>When this flag is set to {@code false}, the script engine must be specified using
+	 * {@link #setEngineName(String)}. Using {@link #setEngine(ScriptEngine)} is not
+	 * possible because multiple instances of the script engine need to be created lazily
+	 * (one per thread).
+	 * @see <a href="http://docs.oracle.com/javase/8/docs/api/javax/script/ScriptEngineFactory.html#getParameter-java.lang.String-">THREADING ScriptEngine parameter<a/>
+	 */
+	public void setSharedEngine(Boolean sharedEngine) {
+		this.sharedEngine = sharedEngine;
+	}
+
+	@Override
+	public Boolean isSharedEngine() {
+		return this.sharedEngine;
+	}
+
 	/**
 	 * Set the scripts to be loaded by the script engine (library or user provided).
 	 * Since {@code resourceLoaderPath} default value is "classpath:", you can load easily
 	 * any script available on the classpath.
-	 *
-	 * For example, in order to use a Javascript library available as a WebJars dependency
+	 * <p>For example, in order to use a JavaScript library available as a WebJars dependency
 	 * and a custom "render.js" file, you should call
 	 * {@code configurer.setScripts("/META-INF/resources/webjars/library/version/library.js",
 	 * "com/myproject/script/render.js");}.
-	 *
-	 * @see #setResourceLoaderPath(String)
+	 * @see #setResourceLoaderPath
 	 * @see <a href="http://www.webjars.org">WebJars</a>
 	 */
 	public void setScripts(String... scriptNames) {
@@ -124,7 +140,7 @@ public String[] getScripts() {
 	}
 
 	/**
-	 * Set the object where belongs the render function (optional).
+	 * Set the object where the render function belongs (optional).
 	 * For example, in order to call {@code Mustache.render()}, {@code renderObject}
 	 * should be set to {@code "Mustache"} and {@code renderFunction} to {@code "render"}.
 	 */
@@ -138,11 +154,11 @@ public String getRenderObject() {
 	}
 
 	/**
-	 * Set the render function name (mandatory). This function will be called with the
-	 * following parameters:
+	 * Set the render function name (mandatory).
+	 * This function will be called with the following parameters:
 	 * <ol>
-	 *     <li>{@code template}: the view template content (String)</li>
-	 *     <li>{@code model}: the view model (Map)</li>
+	 * <li>{@code template}: the view template content (String)</li>
+	 * <li>{@code model}: the view model (Map)</li>
 	 * </ol>
 	 */
 	public void setRenderFunction(String renderFunction) {
@@ -173,7 +189,7 @@ public Charset getCharset() {
 	 * Standard URLs like "file:" and "classpath:" and pseudo URLs are supported
 	 * as understood by Spring's {@link org.springframework.core.io.ResourceLoader}.
 	 * Relative paths are allowed when running in an ApplicationContext.
-	 * Default is "classpath:".
+	 * <p>Default is "classpath:".
 	 */
 	public void setResourceLoaderPath(String resourceLoaderPath) {
 		this.resourceLoaderPath = resourceLoaderPath;
@@ -184,25 +200,4 @@ public String getResourceLoaderPath() {
 		return this.resourceLoaderPath;
 	}
 
-	/**
-	 * When set to {@code false}, use thread-local {@link ScriptEngine} instances instead
-	 * of one single shared instance. This flag should be set to {@code false} for those
-	 * using non thread-safe script engines and templating libraries, like Handlebars or
-	 * React running on Nashorn for example.
-	 *
-	 * <p>When this flag is set to {@code false}, the script engine must be specified using
-	 * {@link #setEngineName(String)}. Using {@link #setEngine(ScriptEngine)} is not
-	 * possible because multiple instances of the script engine need to be created lazily
-	 * (one per thread).
-	 * @see <a href="http://docs.oracle.com/javase/8/docs/api/javax/script/ScriptEngineFactory.html#getParameter-java.lang.String-">THREADING ScriptEngine parameter<a/>
-	 */
-	public void setSharedEngine(Boolean sharedEngine) {
-		this.sharedEngine = sharedEngine;
-	}
-
-	@Override
-	public Boolean isShareEngine() {
-		return this.sharedEngine;
-	}
-
 }