From dfa90a86b10846af9131f6be83d2130c0e01ec69 Mon Sep 17 00:00:00 2001 From: Sebastian Sdorra Date: Mon, 13 Aug 2012 17:29:36 +0200 Subject: [PATCH] added some javadoc for the template engine --- .../sonia/scm/template/DefaultEngine.java | 2 + .../java/sonia/scm/template/Template.java | 12 +++-- .../sonia/scm/template/TemplateEngine.java | 16 +++--- .../scm/template/TemplateEngineFactory.java | 49 ++++++++++++------- .../scm/template/TemplateRenderException.java | 2 + .../java/sonia/scm/template/TemplateType.java | 16 +++--- .../java/sonia/scm/template/package-info.java | 37 ++++++++++++++ 7 files changed, 99 insertions(+), 35 deletions(-) create mode 100644 scm-core/src/main/java/sonia/scm/template/package-info.java diff --git a/scm-core/src/main/java/sonia/scm/template/DefaultEngine.java b/scm-core/src/main/java/sonia/scm/template/DefaultEngine.java index 78aab19ce7..4ecde27c3d 100644 --- a/scm-core/src/main/java/sonia/scm/template/DefaultEngine.java +++ b/scm-core/src/main/java/sonia/scm/template/DefaultEngine.java @@ -30,6 +30,7 @@ */ + package sonia.scm.template; //~--- non-JDK imports -------------------------------------------------------- @@ -44,6 +45,7 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** + * Identifies the default {@link TemplateEngine}. * * @author Sebastian Sdorra * @since 1.19 diff --git a/scm-core/src/main/java/sonia/scm/template/Template.java b/scm-core/src/main/java/sonia/scm/template/Template.java index afa8644ba8..a1d14f6b16 100644 --- a/scm-core/src/main/java/sonia/scm/template/Template.java +++ b/scm-core/src/main/java/sonia/scm/template/Template.java @@ -30,6 +30,7 @@ */ + package sonia.scm.template; //~--- JDK imports ------------------------------------------------------------ @@ -38,6 +39,8 @@ import java.io.IOException; import java.io.Writer; /** + * The template represents a single template file and is able to render this + * template. * * @author Sebastian Sdorra * @since 1.19 @@ -46,12 +49,13 @@ public interface Template { /** - * Method description + * Renders the template and writes the output to the given writer. + * The template will use the given model to replace the placeholder in the + * template file. * * - * @param writer - * @param environment - * @param model + * @param writer writer for the rendered template + * @param model model for the template * * @throws IOException */ diff --git a/scm-core/src/main/java/sonia/scm/template/TemplateEngine.java b/scm-core/src/main/java/sonia/scm/template/TemplateEngine.java index 7abb253d26..49836c7b7d 100644 --- a/scm-core/src/main/java/sonia/scm/template/TemplateEngine.java +++ b/scm-core/src/main/java/sonia/scm/template/TemplateEngine.java @@ -37,6 +37,8 @@ package sonia.scm.template; import java.io.IOException; /** + * The {@link TemplateEngine} searches for {@link Template}s and prepares the + * template for the rendering process. * * @author Sebastian Sdorra * @since 1.19 @@ -45,22 +47,24 @@ public interface TemplateEngine { /** - * Method description + * Returns the template associated with the given path. The template engine + * will search the template in the folder of the web application and in + * the classpath. This method will return null, + * if no template could be found for the given path. * * - * @param templatePath + * @param templatePath path of the template * - * @return + * @return template associated withe the given path or null * * @throws IOException */ public Template getTemplate(String templatePath) throws IOException; /** - * Method description + * Returns the type of this template engine. * - * - * @return + * @return type of template engine */ public TemplateType getType(); } diff --git a/scm-core/src/main/java/sonia/scm/template/TemplateEngineFactory.java b/scm-core/src/main/java/sonia/scm/template/TemplateEngineFactory.java index 2352504f3a..171d0f157e 100644 --- a/scm-core/src/main/java/sonia/scm/template/TemplateEngineFactory.java +++ b/scm-core/src/main/java/sonia/scm/template/TemplateEngineFactory.java @@ -30,6 +30,7 @@ */ + package sonia.scm.template; //~--- non-JDK imports -------------------------------------------------------- @@ -48,9 +49,14 @@ import java.util.Map; import java.util.Set; /** + * The {@link TemplateEngineFactory} is the entrypoint of the template api. + * The factory return available template engines. The + * {@link TemplateEngineFactory} is available via injection. * * @author Sebastian Sdorra * @since 1.19 + * + * @apiviz.landmark */ @Singleton public final class TemplateEngineFactory @@ -65,11 +71,12 @@ public final class TemplateEngineFactory //~--- constructors --------------------------------------------------------- /** - * Constructs ... + * Constructs new template engine factory. This constructor should only be + * called from the injection framework. * * - * @param engines - * @param defaultEngine + * @param engines Set of available template engines + * @param defaultEngine default template engine */ @Inject public TemplateEngineFactory(Set engines, @@ -104,10 +111,12 @@ public final class TemplateEngineFactory //~--- get methods ---------------------------------------------------------- /** - * Method description + * Returns the default template engine. In the normal case the should be a + * implementation of the + * mustache template + * system. * - * - * @return + * @return default template engine */ public TemplateEngine getDefaultEngine() { @@ -115,12 +124,13 @@ public final class TemplateEngineFactory } /** - * Method description + * Returns template engine by its name. The name of a template engine can be + * inquired by calling {@link TemplateType#getName()}. If no engine with the + * given name registered this method will return null. * + * @param engineName name of the engine * - * @param engineName - * - * @return + * @return engine with the given name or null */ public TemplateEngine getEngine(String engineName) { @@ -128,12 +138,15 @@ public final class TemplateEngineFactory } /** - * Method description + * Returns template engine by its extension. This method will use the + * extension of the given path and search a template engine for this + * extension. If no extension could be found in the the path, the method will + * handle the whole path as a extension. If no engine could be found for the + * given extension, this method will return null. * + * @param path template path with extension * - * @param path - * - * @return + * @return template engine for the given path or null */ public TemplateEngine getEngineByExtension(String path) { @@ -159,10 +172,10 @@ public final class TemplateEngineFactory } /** - * Method description + * Returns all registered template engines. * * - * @return + * @return all registered template engines */ public Collection getEngines() { @@ -171,9 +184,9 @@ public final class TemplateEngineFactory //~--- fields --------------------------------------------------------------- - /** Field description */ + /** default template engine */ private TemplateEngine defaultEngine; - /** Field description */ + /** map of registered template engines */ private Map engineMap; } diff --git a/scm-core/src/main/java/sonia/scm/template/TemplateRenderException.java b/scm-core/src/main/java/sonia/scm/template/TemplateRenderException.java index 2c28fafd3f..75f9dd2694 100644 --- a/scm-core/src/main/java/sonia/scm/template/TemplateRenderException.java +++ b/scm-core/src/main/java/sonia/scm/template/TemplateRenderException.java @@ -37,6 +37,8 @@ package sonia.scm.template; import java.io.IOException; /** + * This exception is thrown, if an error during the template rendering + * phase occurs. * * @author Sebastian Sdorra * @since 1.19 diff --git a/scm-core/src/main/java/sonia/scm/template/TemplateType.java b/scm-core/src/main/java/sonia/scm/template/TemplateType.java index 0aaff505af..be95ab8ea4 100644 --- a/scm-core/src/main/java/sonia/scm/template/TemplateType.java +++ b/scm-core/src/main/java/sonia/scm/template/TemplateType.java @@ -30,6 +30,7 @@ */ + package sonia.scm.template; //~--- non-JDK imports -------------------------------------------------------- @@ -45,20 +46,21 @@ import java.io.Serializable; import java.util.Collection; /** + * Represents the type of a {@link TemplateType}. * * @author Sebastian Sdorra * @since 1.19 */ -public class TemplateType extends Type implements Serializable +public final class TemplateType extends Type implements Serializable { - /** Field description */ + /** serial version uid */ private static final long serialVersionUID = 7947596921895752539L; //~--- constructors --------------------------------------------------------- /** - * Constructs ... + * Constructs new template type. * * * @param name @@ -73,7 +75,7 @@ public class TemplateType extends Type implements Serializable } /** - * Constructs ... + * Constructs new template type. * * * @param name @@ -90,10 +92,10 @@ public class TemplateType extends Type implements Serializable //~--- get methods ---------------------------------------------------------- /** - * Method description + * Returns all extensions associated with this template engine. * * - * @return + * @return all extensions */ public Collection getExtensions() { @@ -102,6 +104,6 @@ public class TemplateType extends Type implements Serializable //~--- fields --------------------------------------------------------------- - /** Field description */ + /** extensions */ private Collection extensions; } diff --git a/scm-core/src/main/java/sonia/scm/template/package-info.java b/scm-core/src/main/java/sonia/scm/template/package-info.java new file mode 100644 index 0000000000..74aa0b1ac0 --- /dev/null +++ b/scm-core/src/main/java/sonia/scm/template/package-info.java @@ -0,0 +1,37 @@ +/** + * Copyright (c) 2010, Sebastian Sdorra + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * 3. Neither the name of SCM-Manager; nor the names of its + * contributors may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY + * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + * http://bitbucket.org/sdorra/scm-manager + * + */ + + + +/** + * API for template rendering. + */ +package sonia.scm.template;