You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by ra...@apache.org on 2014/11/11 20:36:26 UTC
[1/3] deltaspike git commit: DELTASPIKE-767 Comprehensive review of
javadoc: core/api
Repository: deltaspike
Updated Branches:
refs/heads/master 8138f1bb4 -> 34b713b41
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ViewAccessScoped.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ViewAccessScoped.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ViewAccessScoped.java
index a42901e..627ea39 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ViewAccessScoped.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ViewAccessScoped.java
@@ -30,10 +30,8 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * The scope is active as long as it's bean is accessed by a view.
- * Basically @ViewAccessScoped is a DeltaSpike Conversation which
- * automatically gets ended when the next view tree gets restored
- * without hitting the bean.
+ * The scope is active as long as its bean is accessed by a view. Basically @ViewAccessScoped is a DeltaSpike
+ * Conversation which automatically gets ended when the next view tree gets restored without hitting the bean.
*/
@Target( { METHOD,TYPE,FIELD } )
@Retention(RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/WindowScoped.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/WindowScoped.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/WindowScoped.java
index 692faac..07fda54 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/WindowScoped.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/WindowScoped.java
@@ -30,7 +30,7 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * Beans which use this scope are bound to a application window (or browser tab).
+ * Beans in this scope are bound to an application window (or browser tab).
*/
@Target( { METHOD,TYPE,FIELD } )
@Retention(RUNTIME)
[2/3] deltaspike git commit: DELTASPIKE-767 Comprehensive review of
javadoc: core/api
Posted by ra...@apache.org.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java
index 1e2cc0a..06a3e53 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java
@@ -36,64 +36,73 @@ import java.lang.annotation.Target;
* @Exclude(onExpression="[my custom expression syntax]", interpretedBy=CustomExpressionInterpreter.class)
* </pre>
*
- * <p/>
- * examples:
- * <p/>
- * <p>the following bean gets excluded in any case</p>
+ * <b>Examples:</b>
+ * <br/>
+ * <ul>
+ * <li>
+ * The following bean gets excluded in any case
* <pre>
* @Exclude
* public class NoBean {}
* </pre>
+ * </li>
*
- * <p/>
- * <p>the following bean gets excluded in case of project-stage development</p>
+ * <li>
+ * The following bean gets excluded when the ProjectStage is 'Development'
* <pre>
* @Exclude(ifProjectStage = ProjectStage.Development.class)
* public class ProductionBean {}
* </pre>
+ * </li>
*
- * <p/>
- * <p>the following bean gets excluded in every case except of project-stage development</p>
+ * <li>
+ * The following bean gets excluded in every case except when then ProjectStage is 'Development'
* <pre>
* @Exclude(exceptIfProjectStage = ProjectStage.Development.class)
* public class DevBean {}
* </pre>
+ * </li>
*
- * <p/>
- * <p>the following bean gets excluded if the expression evaluates to true.
- * that means there is a configured property called 'myProper' with the value 'myValue'</p>
+ * <li>
+ * The following bean gets excluded if the expression evaluates to true, which means there is a configured property
+ * called 'myProperty' with the value 'myValue'
* <pre>
* @Exclude(onExpression="myProperty==myValue")
* public class ProductionBean {}
* </pre>
+ * </li>
*
- * <p/>
- * <p>the following bean gets excluded if the expression evaluates to true</p>
+ * <li>The following bean gets excluded if the expression evaluates to true
+ * <pre>
* @Exclude(onExpression="[my custom expression syntax]", interpretedBy=CustomExpressionInterpreter.class)
* public class ProductionBean {}
+ * </pre>
+ * </li>
+ * </ul>
*/
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.TYPE })
public @interface Exclude
{
/**
- * The {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}s
- * which lead to deactivating this bean.
- * If the current ProjectStage is in this list, the bean will get vetoed.
+ * The {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}s which lead to deactivating this bean. If
+ * the current ProjectStage is in this list, the bean will get vetoed.
+ *
* @return 1-n project-stages which are not allowed for the annotated artifact
*/
Class<? extends ProjectStage>[] ifProjectStage() default { };
/**
- * The {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}s
- * which lead to activating this bean.
- * If the current ProjectStage is not in this list, the bean will get vetoed.
+ * The {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}s which lead to activating this bean. If the
+ * current ProjectStage is not in this list, the bean will get vetoed.
+ *
* @return 1-n project-stages which are allowed for the annotated artifact
*/
Class<? extends ProjectStage>[] exceptIfProjectStage() default { };
/**
- * Expression which signals if the annotated bean should be deactivated or not
+ * Expression which signals if the annotated bean should be deactivated or not.
+ *
* @return expression-string which will be interpreted
*/
String onExpression() default "";
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java
index 4c6935e..b102c1b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java
@@ -19,7 +19,7 @@
package org.apache.deltaspike.core.api.interpreter;
/**
- * Base implementation for simple (property) expressions
+ * Base implementation for simple (property) expressions.
*
* Supported operations:<p/>
* <ul>
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java
index a86bb6a..c19e26b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java
@@ -19,14 +19,19 @@
package org.apache.deltaspike.core.api.interpreter;
/**
- * Interface for interpreting an expression e.g. provided by
- * {@link org.apache.deltaspike.core.api.exclude.Exclude#onExpression()}
+ * Generic interface for evaluation of expressions, like the ones provided by
+ * {@link org.apache.deltaspike.core.api.exclude.Exclude#onExpression()}.
+ *
+ * @param <E> expression type
+ * @param <R> result type
*/
public interface ExpressionInterpreter<E, R>
{
/**
- * Evaluates the given expression and returns the result for it
- * @param expression expression which should be evaluated
+ * Evaluates the given expression and returns the result for it.
+ *
+ * @param expression expression to evaluate
+ *
* @return result of the evaluated expression
*/
R evaluate(E expression);
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java
index 29634d7..cceb2f1 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java
@@ -19,7 +19,7 @@
package org.apache.deltaspike.core.api.interpreter;
/**
- * Operations supported by {@link BasePropertyExpressionInterpreter}
+ * Operations supported by {@link BasePropertyExpressionInterpreter}.
*/
enum SimpleOperationEnum
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java
index 31c2aa6..d510d40 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java
@@ -21,9 +21,8 @@ package org.apache.deltaspike.core.api.jmx;
import javax.management.Notification;
/**
- * Interface used to send JMX message from "CDI MBeans".
- * It can only be used from CDI MBeans and should get injected
- * in other beans.
+ * Interface used to send JMX message from "CDI MBeans". It can only be used from CDI MBeans and should get injected in
+ * other beans.
*/
public interface JmxBroadcaster
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java
index 82a79aa..1b1001b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java
@@ -27,12 +27,12 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * This annotation can be used either on a field or a method.
+ * Describes a JMX operation or attribute, when used on a method or a field, respectively.
*
* Used on a method it describes a JMX operation with an optional description.
*
- * Used on a field it describes a JMX attribute. This attribute is readable
- * if a getter on this field is available and writable is a setter is found.
+ * Used on a field it describes a JMX attribute. This attribute is readable if a getter on this field is available and
+ * writable if a setter is found.
*/
@Retention(RUNTIME)
@Target({ FIELD, METHOD })
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java
index f96de28..0120ec8 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java
@@ -34,17 +34,17 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
public @interface MBean
{
/**
- * @return the category to use if no objectName was specified. Default is "org.apache.deltaspike"
- * and can be overriden either directly by the value or by a key used to resolve a value using
- * {@see org.apache.deltaspike.core.api.config.ConfigResolver}. It is a key if the value is
- * between bracket. Default key is "org.apache.deltaspike.mbean.category".
+ * @return the category to use if no objectName was specified. Default is "org.apache.deltaspike" and can be
+ * overriden either directly by the value or by a key used to resolve a value using
+ * {@link org.apache.deltaspike.core.api.config.ConfigResolver}. It is a key if the value is between
+ * brackets. Default key is "org.apache.deltaspike.mbean.category".
*/
String category() default "{org.apache.deltaspike.mbean.category}";
/**
- * @return the name of the bean used if no objectName was specified.
- * It is used with category value to create the MBean {@see javax.management.ObjectName}
- * using the following pattern: <category>:type=MBeans,name=<name>
+ * @return the name of the bean used if no objectName was specified. It is used with category value to create the
+ * MBean {@link javax.management.ObjectName} using the following pattern:
+ * <category>:type=MBeans,name=<name>
*/
String name() default "";
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java
index 21609ed..e2e6aec 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java
@@ -25,12 +25,13 @@ import java.util.Locale;
import org.apache.deltaspike.core.api.config.DeltaSpikeConfig;
/**
- * <p>Provides the current {@link java.util.Locale}.</p>
- * <p>DeltaSpike provides a default implementation which
- * returns the current system Locale.</p>
- * <p>An application can provide an own implementation as
- * @Alternative. This could e.g. examine a JSF View or the Locale
- * of any currently logged in User.</p>
+ * Provides the current {@link java.util.Locale}.
+ *
+ * <p>
+ * DeltaSpike provides a default implementation which returns the current system Locale.</p>
+ * <p>
+ * An application can provide custom implementation as an @Alternative. This could e.g. examine a JSF View or the
+ * Locale of any currently logged in User.</p>
*/
public interface LocaleResolver extends Serializable, DeltaSpikeConfig
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java
index 5184cb1..2e97d68 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java
@@ -22,46 +22,48 @@ import java.io.Serializable;
import java.util.Collection;
/**
- * <p>Basic interface for all messages.</p>
+ * Basic interface for all messages.
*
- * <p>A <code>Message</code> is not a simple String but all the
- * information needed to create those Strings for multiple situations.
- * The situation ist determined by the used {@link MessageContext}.</p>
+ * <p>
+ * A <code>Message</code> is not a simple String but all the information needed to create those Strings for multiple
+ * situations. The situation is determined by the used {@link MessageContext}.</p>
*/
public interface Message extends Serializable
{
/**
- * @param messageTemplate message key (or inline-text) for the current message
- * @return the current instance of the message builder to allow a fluent api
+ * @param messageTemplate message key (or plain text) for the current message
+ *
+ * @return the current instance of the message builder to allow a fluent API
*/
Message template(String messageTemplate);
/**
* @param arguments numbered and/or named argument(s) for the current message
- * @return the current instance of the message builder to allow a fluent api
+ *
+ * @return the current instance of the message builder to allow a fluent API
*/
Message argument(Serializable... arguments);
/**
- * Argument array. Similar to argument except it is meant to handle an array being passed in via a chain.
- *
- * @param arguments
- * the arguments
+ * Argument array. Similar to argument except it is meant to handle an array being passed in via a chain.
+ *
+ * @param arguments the arguments
+ *
* @return the message
*/
Message argumentArray(Serializable[] arguments);
/**
- * Argument. Similar to the other argument methods, exception it handles collections.
- *
- * @param arguments
- * the arguments
+ * Argument. Similar to the other argument methods, this one handles collections.
+ *
+ * @param arguments the arguments
+ *
* @return the message
*/
Message argument(Collection<Serializable> arguments);
/**
- * @return the message key (or inline-text) of the current message
+ * @return the message key (or plain text) of the current message
*/
String getTemplate();
@@ -71,38 +73,28 @@ public interface Message extends Serializable
Object[] getArguments();
/**
- * Renders the Message to a String, using the {@link MessageContext}
- * which created the Message.
+ * Renders the Message to a String, using the {@link MessageContext} which created the Message.
*/
String toString();
/**
- * Renders the Message to a String, using an
- * arbitrary {@link MessageContext}.
+ * Renders the Message to a String, using an arbitrary {@link MessageContext}.
*/
String toString(MessageContext messageContext);
/**
- * Renders the Message to a String, using the {@link MessageContext}
- * which created the Message.
- * While resolving the message we will
- * first search for a messageTemplate with the given category by
- * just adding a dot '_' and the category String to the
- * {@link #getTemplate()}.
- * If no such a template exists we will fallback to the version
- * without the category String
+ * Renders the Message to a String, using the {@link MessageContext} which created the Message. While resolving the
+ * message we will first search for a messageTemplate with the given category by just adding an underscore '_' and
+ * the category String to the {@link #getTemplate()}. If no such template exists we will fall back to the version
+ * without the category String.
*/
String toString(String category);
/**
- * Renders the Message to a String, using an
- * arbitrary {@link MessageContext}.
- * While resolving the message we will
- * first search for a messageTemplate with the given category by
- * just adding a dot '_' and the category String to the
- * {@link #getTemplate()}.
- * If no such a template exists we will fallback to the version
- * without the category String
+ * Renders the Message to a String, using an arbitrary {@link MessageContext}. While resolving the message we will
+ * first search for a messageTemplate with the given category by just adding an underscore '_' and the category
+ * String to the {@link #getTemplate()}. If no such template exists we will fall back to the version without the
+ * category String.
*/
String toString(MessageContext messageContext, String category);
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java
index 4804dd8..399a6c6 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java
@@ -26,42 +26,42 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * <p>Marker annotation for a message-bundle interface which provides type-safe messages.</p>
+ * Marker annotation for a message-bundle interface which provides type-safe messages.
*
- * <p>This annotation must only be used on interfaces.
- * If this annotation gets used on a concrete class, a deployment error results!</p>
+ * <p>
+ * This annotation must only be used on interfaces. If this annotation gets used on a concrete class, a deployment error
+ * results!</p>
*
* <h3>Type-safe Messages</h3>
- * <p>Each method on an interface annotated with <code>@MessageBundle</code>
- * will form a type-safe message. The message lookup key
- * (resource bundle key) can either be defined by annotating those methods
- * with @{@link MessageTemplate}) or by convention. if no @{@link MessageTemplate}
- * annotation is used on a method, the case sensitive method-name name
- * will be used as resource key.</p>
+ * <p>
+ * Each method on an interface annotated with <code>@MessageBundle</code> will form a type-safe message. The
+ * message lookup key (resource bundle key) can either be defined by annotating those methods with
+ * @{@link MessageTemplate}) or by convention. if no @{@link MessageTemplate} annotation is used on a method,
+ * the case sensitive method name name will be used as resource key.</p>
*
* <h3>Message Parameters</h3>
- * <p>The parameters of the declared methods will be automatically passed
- * as message parameters to the {@link org.apache.deltaspike.core.api.message.MessageResolver}.
- * Please note that all passed parameters should be {@link java.io.Serializable}.
- * If a parameter is not Serializable, we will instead store the <code>toString()</code>
+ * <p>
+ * The parameters of the declared methods will be automatically passed as message parameters to the
+ * {@link org.apache.deltaspike.core.api.message.MessageResolver}. Please note that all passed parameters should be
+ * {@link java.io.Serializable}. If a parameter is not Serializable, we will instead store the <code>toString()</code>
* of the passed parameter.</p>
*
*
* <h3>Message Sources</h3>
- * <p>The {@link java.util.ResourceBundle} or other resource lookup source which might be used is
- * determined by the {@link org.apache.deltaspike.core.api.message.MessageResolver}
- * in conjunction with
- * {@link org.apache.deltaspike.core.api.message.MessageContext#messageSource(String...)}.
- * The fully qualified class name of the interface annotated with
- * @MessageBundle will automatically be registered as additional
+ * <p>
+ * The {@link java.util.ResourceBundle} or other resource lookup source which might be used is determined by the
+ * {@link org.apache.deltaspike.core.api.message.MessageResolver} in conjunction with
+ * {@link org.apache.deltaspike.core.api.message.MessageContext#messageSource(String...)}. The fully qualified class
+ * name of the interface annotated with @MessageBundle will automatically be registered as additional
* <code>messageSource</code> for those messages.</p>
*
+ * <p>
+ * <code>@MessageBundle</code> can be combined with {@link MessageContextConfig} to further customize the
+ * message resolution and processing.</p>
*
- * <p><code>@MessageBundle</code> can be combined with {@link MessageContextConfig}
- * to further customize the message-resolution and processing process.</p>
- *
- * <p>Debug hint: Set a breakpoint in <code>MessageBundleInvocationHandler#invoke</code>.
- * This will get called for every message bundle invocation.</p>
+ * <p>
+ * Debug hint: Set a breakpoint in <code>MessageBundleInvocationHandler#invoke</code>. This will get called for every
+ * message bundle invocation.</p>
*/
@Target({ TYPE })
@Retention(RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java
index e765b10..17bb699 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java
@@ -23,24 +23,27 @@ import java.util.List;
/**
* Central context for handling dynamic messages.
- * Instances of this type are mutable but also {@link Cloneable}.
- * If you need a new instance, then use {@link Object#clone()}
+ * <br/>
+ * Instances of this type are mutable but also {@link Cloneable}. If you need a new instance, then use
+ * {@link Object#clone()}.
*/
public interface MessageContext extends LocaleResolver, Serializable, Cloneable
{
/**
- * Clones the current MessageContext
+ * Clones the current MessageContext.
*/
MessageContext clone();
/**
- * @return message based on the current context modifiable via a fluent api
+ * @return a message based on the current context modifiable via a fluent API
*/
Message message();
/**
- * Allows to add a message-source instance which can be used by a {@link MessageResolver}
- * @param messageSource message-source to add
+ * Configures a message source instance for use by a {@link MessageResolver}.
+ *
+ * @param messageSource message source to add
+ *
* @return the instance of the current message context builder
*/
MessageContext messageSource(String... messageSource);
@@ -79,7 +82,7 @@ public interface MessageContext extends LocaleResolver, Serializable, Cloneable
LocaleResolver getLocaleResolver();
/**
- * @return list of registered message-sources
+ * @return list of registered message sources
*/
List<String> getMessageSources();
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java
index 260bd72..b2a2d43 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java
@@ -26,8 +26,7 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * Allows to customize the message-resolution and processing
- * in combination with {@link MessageBundle}.
+ * Configures message resolution and processing of a {@link MessageBundle}.
*/
@Target({ TYPE })
@Retention(RUNTIME)
@@ -35,39 +34,42 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
public @interface MessageContextConfig
{
/**
- * <p>Additional message-source.</p>
+ * <p>Additional message source.</p>
*
- * <p>A message-source is a lookup hint for the {@link MessageResolver}.
- * For the default MessageResolver this is the name of the
- * {@link java.util.ResourceBundle}.</p>
+ * <p>A message source is a lookup hint for the {@link MessageResolver}. For the default MessageResolver this is the
+ * name of the {@link java.util.ResourceBundle}.</p>
*
- * <p>Example: For using 2 additional ResourceBundles for the lookup,
- * you can use the MessageContextConfig like that:
+ * <p>Example: To use 2 additional ResourceBundles for the lookup, you can configure the MessageContextConfig like
+ * this:
* <pre>
* @MessageBundle
* @MessageContextConfig(messageSource = {"mycomp.ErrorMessages","mycomp.BusinessMessages"})
* public interface MyCompanyMessages {...
- * </pre>.</p>
+ * </pre>.
+ * </p>
+ *
* @return classes of the message-sources
*/
String[] messageSource() default { };
/**
- * {@link MessageResolver} which should be used for resolving the message-template (= basic text)
- * @return class of the {@link MessageResolver}-bean or the default marker
+ * {@link MessageResolver} to use for resolution of message templates to message text.
+ *
+ * @return class of the {@link MessageResolver} bean or the default marker
*/
Class<? extends MessageResolver> messageResolver() default MessageResolver.class;
/**
- * {@link MessageInterpolator} which should be used for replacing the placeholders in the resolved text
- * @return class of the {@link MessageInterpolator}-bean or the default marker
+ * {@link MessageInterpolator} to use for interpolation of placeholders in the resolved text.
+ *
+ * @return class of the {@link MessageInterpolator} bean or the default marker
*/
Class<? extends MessageInterpolator> messageInterpolator() default MessageInterpolator.class;
/**
- * {@link LocaleResolver} which should be used for providing the locale for resolving
- * the message-template (= basic text)
- * @return class of the {@link LocaleResolver}-bean or the default marker
+ * {@link LocaleResolver} providing the locale for message template resolution.
+ *
+ * @return class of the {@link LocaleResolver} bean or the default marker
*/
Class<? extends LocaleResolver> localeResolver() default LocaleResolver.class;
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java
index 13d2d86..e0f3466 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java
@@ -24,28 +24,26 @@ import java.util.Locale;
import org.apache.deltaspike.core.api.config.DeltaSpikeConfig;
/**
- * <p>Implementations are responsible to replace placeholders
- * in a message with the final value.</p>
+ * Implementations are responsible to replace placeholders in a message with the final value.
*
- * <p>An application can provide an own implementation as
- * @Alternative.</p>
+ * <p>
+ * An application can provide a custom implementation as @Alternative.</p>
*
- * <p>A simple implementation which uses the
- * {@link String#format(java.util.Locale, String, Object...)}
- * will be used by default.</p>
+ * <p>
+ * A simple implementation which uses the {@link String#format(java.util.Locale, String, Object...)} will be used by
+ * default.</p>
*/
public interface MessageInterpolator extends Serializable, DeltaSpikeConfig
{
/**
- * replaces the arguments of the given message with the given arguments
+ * Replaces the arguments of the given message with the given arguments.
*
- * instead of a MessageContextAware interface. we need it to avoid expensive operations like locking or deep cloning
* @param messageText the message text which has to be interpolated
- * @param arguments a list of numbered and/or named arguments for the current message
- * @param locale to use for the formatting
- * @return the final (interpolated) message text
- * if it was possible to replace the parameters with the given arguments
- * the unmodified messageText otherwise
+ * @param arguments a list of numbered and/or named arguments for the current message
+ * @param locale to use for the formatting
+ *
+ * @return the final (interpolated) message text if it was possible to replace the parameters with the given
+ * arguments, or the unmodified messageText otherwise
*/
String interpolate(String messageText, Serializable[] arguments, Locale locale);
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java
index f269e50..6fb71ee 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java
@@ -21,7 +21,7 @@ package org.apache.deltaspike.core.api.message;
import java.io.Serializable;
/**
- * Implementations have to resolve the text stored for a given key in the message-source they are aware of.
+ * Implementations have to resolve the text stored for a given key in the message source they are aware of.
* Implementations should always be @Dependent scoped!
*/
public interface MessageResolver extends Serializable
@@ -30,11 +30,12 @@ public interface MessageResolver extends Serializable
/**
*
- * @param messageContext messageContext which should be used
- * @param messageTemplate the message key (or in-lined text) of the current message
- * @param category the sub-category of the message, e.g. 'longText'. Can be <code>null</code>
- * @return the final but not interpolated message text
- * or <code>null</code> if an error happened or the resource could not be resolved.
+ * @param messageContext messageContext which should be used
+ * @param messageTemplate the message key (or inline text) of the current message
+ * @param category the category of the message, e.g. 'longText'. Can be <code>null</code>
+ *
+ * @return the final but not interpolated message text or <code>null</code> if an error happened or the resource
+ * could not be resolved.
*/
String getMessage(MessageContext messageContext, String messageTemplate, String category);
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java
index d6f1c3f..09d5764 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java
@@ -26,29 +26,26 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * <p>Provides the message(-template) for type-safe messages.</p>
+ * Provides the message (template) for type-safe messages.
*
- * <p>This only works on interfaces which are annotated with
- * {@link MessageBundle}.</p>
+ * <p>
+ * This only works on interfaces which are annotated with {@link MessageBundle}.</p>
*
- * <p>Depending on the {@link org.apache.deltaspike.core.api.message.MessageResolver}
- * this message-template value might be used as key to lookup internationalized values
- * from a {@link java.util.ResourceBundle}.</p>
+ * <p>
+ * Depending on the {@link org.apache.deltaspike.core.api.message.MessageResolver} this message template value might be
+ * used as key to lookup internationalized values from a {@link java.util.ResourceBundle}.</p>
*
- * <p>A MessageTemplate value which starts and ends with bracelets '{', '}' will
- * be interpreted as key for resolving from a ResourceBundle or any other lookup mechanism
- * determined by the {@link org.apache.deltaspike.core.api.message.MessageResolver}.
- * A small example:
+ * <p>
+ * A MessageTemplate value which starts and ends with brackets '{', '}' will be interpreted as key for resolving from a
+ * ResourceBundle or any other lookup mechanism determined by the
+ * {@link org.apache.deltaspike.core.api.message.MessageResolver}. A small example:
* <pre>
* @MessageTemplate("{welcome_to}")
- * </pre>
- * This will lookup a <code>welcome_to = Hello to Aruba</code> from the configured
- * resource bundle.
+ * </pre> This will lookup a <code>welcome_to = Hello to Aruba</code> from the configured resource bundle.
* </p>
*
- *
- * <p>MessageTemplate values without '{', '}' bracelets will be directly used
- * without resource lookup</p>
+ * <p>
+ * MessageTemplate values without '{', '}' bracelets will be directly used without resource lookup.</p>
*/
@Target(METHOD)
@Retention(RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java
index 4a837cb..5ee9098 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java
@@ -29,41 +29,42 @@ import java.util.Map;
import java.util.logging.Logger;
/**
- * <p>This class is the base of all ProjectStages. A ProjectStage
- * identifies the environment the application currently runs in.
- * It provides the same functionality as the JSF-2 ProjectStage
- * but has a few additional benefits:
+ * This class is the base of all ProjectStages. A ProjectStage identifies the environment the application currently runs
+ * in. It provides the same functionality as the JSF2 ProjectStage but has a few additional benefits:
* <ul>
- * <li>it also works for JSF-1.0, JSF-1.1 and JSF-1.2 applications</li>
- * <li>it also works in pure backends and unit tests without any faces-api</li>
- * <li>it is dynamic. Everyone can add their own ProjectStages!</p>
+ * <li>it works for JSF 1.0, JSF 1.1 and JSF 1.2 applications</li>
+ * <li>it works in pure backends and unit tests without any JSF API</li>
+ * <li>it is dynamic. Everyone can add their own ProjectStages!</li>
* </ul>
- * </p>
*
- * <p>Technically this is kind of a 'dynamic enum'.</p>
- * <p>The following ProjectStages are provided by default</p>
+ * <p>
+ * Technically this is kind of a 'dynamic enum'.</p>
+ *
+ * <p>
+ * The following ProjectStages are provided by default:</p>
* <ul>
- * <li>UnitTest</li>
- * <li>Development</li>
- * <li>SystemTest</li>
- * <li>IntegrationTest</li>
- * <li>Staging</li>
- * <li>Production</li>
+ * <li>UnitTest</li>
+ * <li>Development</li>
+ * <li>SystemTest</li>
+ * <li>IntegrationTest</li>
+ * <li>Staging</li>
+ * <li>Production</li>
* </ul>
*
- * <p>The following resolution mechanism is used to determine the current ProjectStage:
+ * <p>
+ * The following resolution mechanism is used to determine the current ProjectStage:</p>
* <ul>
- * <li>TODO specify!</li>
+ * <li>TODO specify!</li>
* </ul>
- * </p>
*
- * <p>Adding a new ProjectStage is done via the
- * {@link java.util.ServiceLoader} mechanism. A class deriving from {@link ProjectStage}
- * must be provided and used for creating a single static instance of it.
+ * <p>
+ * New ProjectStages can be added via the {@link java.util.ServiceLoader} mechanism. A class deriving from
+ * {@link ProjectStage} must be provided and used for creating a single static instance of it.</p>
+ *
+ * <p>
+ * Custom ProjectStages can be implemented by writing anonymous ProjectStage members into a registered
+ * {@link ProjectStageHolder} as shown in the following example:</p>
*
- * <p>Custom ProjectStages can be implemented by writing anonymous ProjectStage
- * members into a registered {@link ProjectStageHolder} as shown in the following
- * sample:</p>
* <pre>
* package org.apache.deltaspike.test.core.api.projectstage;
* public class TestProjectStages implements ProjectStageHolder {
@@ -74,28 +75,31 @@ import java.util.logging.Logger;
* public static final MyOtherProjectStage MyOtherProjectStage = new MyOtherProjectStage();
* }
* </pre>
- * <p>For activating those ProjectStages, you have to register this ProjectStageHolder class
- * to get picked up via the java.util.ServiceLoader mechanism. Simply create a file
+ *
+ * <p>
+ * To activate those ProjectStages, you have to register the ProjectStageHolder class to get picked up via the
+ * ServiceLoader mechanism. Simply create a file
* <pre>
* META-INF/services/org.apache.deltaspike.core.api.projectstage.ProjectStageHolder
- * </pre>
- * which contains the fully qualified class name of custom ProjectStageHolder implementation:
+ * </pre> which contains the fully qualified class name of custom ProjectStageHolder implementation:
* <pre>
* # this class now gets picked up by java.util.ServiceLoader
* org.apache.deltaspike.test.core.api.projectstage.TestProjectStages
* </pre>
* </p>
- * <p>You can use your own ProjectStages exactly the same way as all the ones provided
- * by the system:
+ *
+ * <p>
+ * You can use your own ProjectStages exactly the same way as all the ones provided by the system:
* <pre>
* ProjectStage myOwnPs = ProjectStage.valueOf("MyOwnProjectStage");
- if (myOwnPs.equals(MyOwnProjectStage.MyOwnProjectStage)) ...
+ * if (myOwnPs.equals(MyOwnProjectStage.MyOwnProjectStage)) ...
* </pre>
+ * </p>
*
- * <p><b>Note:</b> Please note that DeltaSpike will only find {@link ProjectStageHolder}s
- * which are accessible by this very class. If you deploy the deltaspike-core jar to a
- * shared EAR classloader, it will e.g. <i>not</i> be able to register ProjectStages defined
- * in a web applications WEB-INF/classes directory!
+ * <p>
+ * <b>Note:</b> DeltaSpike will only find {@link ProjectStageHolder}s which are accessible by this very class. If you
+ * deploy the deltaspike-core jar to a shared EAR classloader, it will e.g. <i>not</i> be able to register ProjectStages
+ * defined in a web application's WEB-INF/classes directory!
* </p>
*
*/
@@ -159,7 +163,7 @@ public abstract class ProjectStage implements Serializable
}
/**
- * This function exists to prevent findbugs to complain about
+ * This function exists to prevent findbugs from complaining about
* setting a static member from a non-static function.
*
* @param projectStageClassName name of the project-stage
@@ -191,8 +195,9 @@ public abstract class ProjectStage implements Serializable
}
/**
- * Exposes all registered {@link ProjectStage} implementations
- * @return provided and custom project-stage implementations
+ * Exposes all registered {@link ProjectStage} implementations.
+ *
+ * @return provided and custom ProjectStage implementations
*/
public static ProjectStage[] values()
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java
index 5e8b0ff..79a7095 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java
@@ -19,16 +19,15 @@
package org.apache.deltaspike.core.api.projectstage;
/**
- * <p>This is a marker interface for custom project
- * stage holders. A project stage holder is a class which
- * contains 1 or more {@link ProjectStage}s.</p>
+ * A marker interface for custom ProjectStage holders. A ProjectStage holder is a class which contains one or more
+ * {@link ProjectStage}s.
*
- * <p>Any custom ProjectStageHolder must get registered via the
- * {@link java.util.ServiceLoader} mechanism. Simply create a file
+ * <p>
+ * Any custom ProjectStageHolder must get registered via the {@link java.util.ServiceLoader} mechanism. Simply create a
+ * file
* <pre>
* META-INF/services/org.apache.deltaspike.core.api.projectstage.ProjectStageHolder
- * </pre>
- * and write the fully qualified class name of your ProjectStageHolder into it.
+ * </pre> and write the fully qualified class name of your ProjectStageHolder into it.
* </p>
*/
public interface ProjectStageHolder
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java
index 9fc17a1..bdf13a1 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java
@@ -19,8 +19,8 @@
package org.apache.deltaspike.core.api.projectstage;
/**
- * Marker interface for {@link ProjectStage} implementations which are used for tests.
- * E.g. used to enable logging in all 'testing' ProjectStages.
+ * Marker interface for {@link ProjectStage} implementations which are used for tests. E.g. used to enable logging in
+ * all 'testing' ProjectStages.
*/
public interface TestStage
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java
index b977e08..a72bcf3 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java
@@ -37,27 +37,26 @@ import org.apache.deltaspike.core.util.ClassUtils;
/**
- * <p>This class provides access to the {@link BeanManager}
- * by registering the current {@link BeanManager} in an extension and
- * making it available via a singleton factory for the current application.</p>
- * <p>This is really handy if you like to access CDI functionality
- * from places where no injection is available.</p>
- * <p>If a simple but manual bean-lookup is needed, it's easier to use the {@link BeanProvider}.</p>
- * <p/>
- * <p>As soon as an application shuts down, the reference to the {@link BeanManager} will be removed.<p>
- * <p/>
- * <p>Usage:<p/>
- * <pre>
- * BeanManager bm = BeanManagerProvider.getInstance().getBeanManager();
- *
- * </pre>
+ * This class provides access to the {@link BeanManager} by registering the current {@link BeanManager} in an extension
+ * and making it available via a singleton factory for the current application.
+ *
+ * <p>This is really handy when you need to access CDI functionality from places where no injection is available.</p>
*
- * <p><b>Attention:</b> This method is intended for being used in user code at runtime.
- * If this method gets used during Container boot (in an Extension), non-portable
- * behaviour results. During bootstrapping an Extension shall @Inject BeanManager to get
- * access to the underlying BeanManager (see e.g. {@link #cleanupFinalBeanManagers} ).
- * This is the only way to guarantee to get the right
- * BeanManager in more complex Container scenarios.</p>
+ * <p>If a simple but manual bean lookup is needed, it's easier to use the {@link BeanProvider}.</p>
+ *
+ * <p>As soon as an application shuts down, the reference to the {@link BeanManager} is removed.</p>
+ *
+ * <p>
+ * Usage:
+
+ * <pre>
+ * BeanManager bm = BeanManagerProvider.getInstance().getBeanManager();</pre>
+ * </p>
+ * <p>
+ * <b>Attention:</b> This approach is intended for use in user code at runtime. If BeanManagerProvider is used during
+ * Container boot (in an Extension), non-portable behaviour results. During bootstrapping, an Extension shall
+ * @Inject BeanManager to get access to the underlying BeanManager (see e.g. {@link #cleanupFinalBeanManagers}).
+ * This is the only way to guarantee that the right BeanManager is obtained in more complex Container scenarios.</p>
*/
public class BeanManagerProvider implements Extension
{
@@ -98,44 +97,42 @@ public class BeanManagerProvider implements Extension
}
/**
- * This data container is used for storing the BeanManager for each
- * WebApplication. This is needed in EAR or other multi-webapp scenarios
- * if the DeltaSpike classes (jars) are provided in a shared ClassLoader.
+ * This data container is used for storing the BeanManager for each web application. This is needed in EAR or other
+ * multi-webapp scenarios when the DeltaSpike classes (jars) are provided in a shared ClassLoader.
*/
private static class BeanManagerInfo
{
/**
- * The BeanManager picked up via Extension loading
+ * The BeanManager picked up via Extension loading.
*/
private BeanManager loadTimeBm;
/**
- * The final BeanManagers.
- * After the container did finally boot, we first try to resolve them from JNDI,
- * and only if we don't find any BM there we take the ones picked up at startup.
+ * The final BeanManager. After the container did finally boot, we first try to resolve them from JNDI, and only
+ * if we don't find any BM there we take the ones picked up at startup.
*/
private BeanManager finalBm;
/**
- * Whether the CDI Application has finally booted.
- * Please note that this is only a nearby value
- * as there is no reliable event for this status in EE6.
+ * Whether the CDI Application has finally booted. Please note that this is only a nearby value as there is no
+ * reliable event for this status in EE6.
*/
private boolean booted;
}
/**
- * <p>The BeanManagerInfo for the current ClassLoader.</p>
+ * The BeanManagerInfo for the current ClassLoader.
+ *
* <p><b>Attention:</b> This instance must only be used through the {@link #bmpSingleton} singleton!</p>
*/
private volatile Map<ClassLoader, BeanManagerInfo> bmInfos = new ConcurrentHashMap<ClassLoader, BeanManagerInfo>();
/**
- * Returns if the {@link BeanManagerProvider} has been initialized.
- * Usually it isn't needed to call this method in application code.
- * It's e.g. useful for other frameworks to check if DeltaSpike and the CDI container in general have been started.
+ * Indicates whether the {@link BeanManagerProvider} has been initialized. Usually it's not necessary to call this
+ * method in application code. It's useful e.g. for other frameworks to check if DeltaSpike and the CDI container in
+ * general have been started.
*
- * @return true if the bean-manager-provider is ready to be used
+ * @return true if the BeanManagerProvider is ready to be used
*/
public static boolean isActive()
{
@@ -143,11 +140,11 @@ public class BeanManagerProvider implements Extension
}
/**
- * Allows to get the current provider instance which provides access to the current {@link BeanManager}
+ * Returns the current provider instance which provides access to the current {@link BeanManager}.
*
- * @throws IllegalStateException if the {@link BeanManagerProvider} isn't ready to be used.
- * That's the case if the environment isn't configured properly and therefore the {@link AfterBeanDiscovery}
- * hasn't be called before this method gets called.
+ * @throws IllegalStateException if the {@link BeanManagerProvider} isn't ready to be used. That's the case if the
+ * environment isn't configured properly and therefore the {@link AfterBeanDiscovery}
+ * hasn't been called before this method gets called.
* @return the singleton BeanManagerProvider
*/
public static BeanManagerProvider getInstance()
@@ -173,9 +170,9 @@ public class BeanManagerProvider implements Extension
}
/**
- * It basically doesn't matter which of the system events we use,
- * but basically we use the {@link AfterBeanDiscovery} event since it allows to use the
- * {@link BeanManagerProvider} for all events which occur after the {@link AfterBeanDiscovery} event.
+ * It doesn't really matter which of the system events is used to obtain the BeanManager, but
+ * {@link AfterBeanDiscovery} has been chosen since it allows all events which occur after the
+ * {@link AfterBeanDiscovery} to use the {@link BeanManagerProvider}.
*
* @param afterBeanDiscovery event which we don't actually use ;)
* @param beanManager the BeanManager we store and make available.
@@ -189,10 +186,11 @@ public class BeanManagerProvider implements Extension
}
/**
- * The active {@link BeanManager} for the current application (/{@link ClassLoader}). This method will throw an
- * {@link IllegalStateException} if the BeanManager cannot be found.
+ * The active {@link BeanManager} for the current application (current {@link ClassLoader}). This method will throw
+ * an {@link IllegalStateException} if the BeanManager cannot be found.
+ *
+ * @return the current BeanManager, never <code>null</code>
*
- * @return the current bean-manager, never <code>null</code>
* @throws IllegalStateException if the BeanManager cannot be found
*/
public BeanManager getBeanManager()
@@ -256,18 +254,13 @@ public class BeanManagerProvider implements Extension
}
/**
- * By cleaning the final BeanManager map after the Deployment got Validated,
- * we prevent premature loading of information from JNDI in cases where the
- * container might not be fully setup yet.
+ * By cleaning the final BeanManager map after the deployment gets validated, premature loading of information from
+ * JNDI is prevented in cases where the container might not be fully setup yet.
*
- * This might happen if someone uses the BeanManagerProvider during Extension
- * startup. This should generally avoided but instead you should just use
- * an injected BeanManager in your Extension and propagate the BeanManager
- * via setters.
+ * This might happen if the BeanManagerProvider is used in an extension during CDI bootstrap. This should be
+ * generally avoided. Instead, an injected BeanManager should be used in Extensions and propagated using setters.
*
- * In EARs with multiple webapps you might get different Extensions per WAR.
- * This depends on the container you use. By resetting <i>all</i> known
- * BeanManagerInfos we try to
+ * In EARs with multiple webapps, each WAR might get a different Extension. This depends on the container used.
*/
public void cleanupFinalBeanManagers(@Observes AfterDeploymentValidation adv)
{
@@ -284,9 +277,9 @@ public class BeanManagerProvider implements Extension
}
/**
- * Cleanup on container shutdown
+ * Cleanup on container shutdown.
*
- * @param beforeShutdown cdi shutdown event
+ * @param beforeShutdown CDI shutdown event
*/
public void cleanupStoredBeanManagerOnShutdown(@Observes BeforeShutdown beforeShutdown)
{
@@ -337,7 +330,7 @@ public class BeanManagerProvider implements Extension
}
/**
- * Get or create the BeanManagerInfo for the given ClassLoader
+ * Get or create the BeanManagerInfo for the given ClassLoader.
*/
private BeanManagerInfo getBeanManagerInfo(ClassLoader cl)
{
@@ -364,10 +357,11 @@ public class BeanManagerProvider implements Extension
}
/**
- * This function exists to prevent findbugs to complain about
- * setting a static member from a non-static function.
+ * This function exists to prevent findbugs from complaining about setting a static member from a non-static
+ * function.
*
* @param beanManagerProvider the bean-manager-provider which should be used if there isn't an existing provider
+ *
* @return the first BeanManagerProvider
*/
private static BeanManagerProvider setBeanManagerProvider(BeanManagerProvider beanManagerProvider)
@@ -381,7 +375,7 @@ public class BeanManagerProvider implements Extension
}
/**
- * @return whether a BeanManagerInfo for a parent classloader is available and has the booted flag set.
+ * @return whether a BeanManagerInfo for a parent ClassLoader is available and has the booted flag set.
*/
private boolean isParentBeanManagerBooted()
{
@@ -391,10 +385,10 @@ public class BeanManagerProvider implements Extension
}
/**
- * This method recurses into the parent ClassLoaders and will check if a
- * BeanManagerInfo for it exists.
- * @return the BeanManagerInfo of the parent ClassLoader hierarchy if any exists,
- * or <code>null</code> if there is no {@link BeanManagerInfo} for the ClassLoaders in the hierarchy.
+ * This method recurses into the parent ClassLoaders and checks whether a BeanManagerInfo for it exists.
+ *
+ * @return the BeanManagerInfo of the parent ClassLoader hierarchy if any exists, or <code>null</code> if there is
+ * no {@link BeanManagerInfo} for the ClassLoaders in the hierarchy.
*/
private BeanManagerInfo getParentBeanManagerInfo(ClassLoader classLoader)
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java
index b2ce5ab..bcf2b8d 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java
@@ -41,17 +41,16 @@ import java.util.logging.Level;
import java.util.logging.Logger;
/**
- * <p>This class contains utility methods to resolve contextual references
- * in situations where no injection is available because the
- * current class is not managed by the CDI Container. This can happen
- * in e.g. a JPA-2.0 EntityListener, a ServletFilter, a Spring managed
- * Bean, etc.</p>
+ * This class contains utility methods for resolution of contextual references in situations where no injection is
+ * available because the current class is not managed by the CDI Container. This can happen in e.g. a JPA 2.0
+ * EntityListener, a ServletFilter, a Spring managed Bean, etc.
*
- * <p><b>Attention:</b> This method is intended for being used in user code at runtime.
- * If this method gets used during Container boot (in an Extension), non-portable
- * behaviour results. The CDI specification only allows injection of the
- * BeanManager during CDI-Container boot time.</p>
+ * <p>
+ * <b>Attention:</b> This approach is intended for use in user code at runtime. If BeanProvider is used during Container
+ * boot (in an Extension), non-portable behaviour results. The CDI specification only allows injection of the
+ * BeanManager during CDI container boot time.</p>
*
+ * @see DependentProvider
* @see BeanManagerProvider
*/
@Typed()
@@ -73,26 +72,26 @@ public final class BeanProvider
}
/**
- * <p>Get a Contextual Reference by its type and qualifiers.
- * You can use this method to get contextual references of a given type.
- * A 'Contextual Reference' is a proxy which will automatically resolve
- * the correct contextual instance when you access any method.</p>
- *
- * <p><b>Attention:</b> You shall not use this method to manually resolve a
- * @Dependent bean! The reason is that this contextual instances do usually
- * live in the well-defined lifecycle of their injection point (the bean they got
- * injected into). But if we manually resolve a @Dependent bean, then it does <b>not</b>
- * belong to such a well defined lifecycle (because @Dependent it is not
- * @NormalScoped) and thus will not automatically be
+ * Get a Contextual Reference by its type and qualifiers. You can use this method to get contextual references of a
+ * given type. A "Contextual Reference" is a proxy which will automatically resolve the correct contextual instance
+ * when you access any method.
+ *
+ * <p>
+ * <b>Attention:</b> You shall not use this method to manually resolve a @Dependent bean! The reason is that
+ * contextual instances usually live in the well-defined lifecycle of their injection point (the bean they got
+ * injected into). But if we manually resolve a @Dependent bean, then it does <b>not</b> belong to such well
+ * defined lifecycle (because @Dependent is not @NormalScoped) and thus will not be automatically
* destroyed at the end of the lifecycle. You need to manually destroy this contextual instance via
* {@link javax.enterprise.context.spi.Contextual#destroy(Object, javax.enterprise.context.spi.CreationalContext)}.
- * Thus you also need to manually store the CreationalContext and the Bean you
- * used to create the contextual instance which this method will not provide.</p>
+ * Thus you also need to manually store the CreationalContext and the Bean you used to create the contextual
+ * instance.</p>
*
- * @param type the type of the bean in question
+ * @param type the type of the bean in question
* @param qualifiers additional qualifiers which further distinct the resolved bean
- * @param <T> target type
+ * @param <T> target type
+ *
* @return the resolved Contextual Reference
+ *
* @throws IllegalStateException if the bean could not be found.
* @see #getContextualReference(Class, boolean, Annotation...)
*/
@@ -102,15 +101,17 @@ public final class BeanProvider
}
/**
- * {@link #getContextualReference(Class, Annotation...)} which returns <code>null</code> if the
- * 'optional' parameter is set to <code>true</code>.
+ * {@link #getContextualReference(Class, Annotation...)} which returns <code>null</code> if the 'optional' parameter
+ * is set to <code>true</code>.
+ *
+ * @param type the type of the bean in question
+ * @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
+ * Otherwise it will throw an {@code IllegalStateException}
+ * @param qualifiers additional qualifiers which distinguish the resolved bean
+ * @param <T> target type
*
- * @param type the type of the bean in question
- * @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
- * Otherwise it will throw an {@code IllegalStateException}
- * @param qualifiers additional qualifiers which further distinguish the resolved bean
- * @param <T> target type
* @return the resolved Contextual Reference
+ *
* @see #getContextualReference(Class, Annotation...)
*/
public static <T> T getContextualReference(Class<T> type, boolean optional, Annotation... qualifiers)
@@ -121,17 +122,18 @@ public final class BeanProvider
}
/**
- * {@link #getContextualReference(Class, Annotation...)} which returns <code>null</code> if the
- * 'optional' parameter is set to <code>true</code>.
- * This method is intended for usage where the BeanManager is known, e.g. in Extensions.
+ * {@link #getContextualReference(Class, Annotation...)} which returns <code>null</code> if the 'optional' parameter
+ * is set to <code>true</code>. This method is intended for usage where the BeanManger is known, e.g. in Extensions.
*
* @param beanManager the BeanManager to use
- * @param type the type of the bean in question
- * @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
- * Otherwise it will throw an {@code IllegalStateException}
- * @param qualifiers additional qualifiers which further distinguish the resolved bean
- * @param <T> target type
+ * @param type the type of the bean in question
+ * @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
+ * Otherwise it will throw an {@code IllegalStateException}
+ * @param qualifiers additional qualifiers which further distinct the resolved bean
+ * @param <T> target type
+ *
* @return the resolved Contextual Reference
+ *
* @see #getContextualReference(Class, Annotation...)
*/
public static <T> T getContextualReference(BeanManager beanManager,
@@ -156,14 +158,16 @@ public final class BeanProvider
}
/**
- * <p>Get a Contextual Reference by its EL Name.
- * This only works for beans with the @Named annotation.</p>
+ * Get a Contextual Reference by its EL Name. This only works for beans with the @Named annotation.
*
- * <p><b>Attention:</b> please see the notes on manually resolving @Dependent bean
- * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
+ * <p>
+ * <b>Attention:</b> please see the notes on manually resolving @Dependent beans in
+ * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
+ *
+ * @param name the EL name of the bean
*
- * @param name the EL name of the bean
* @return the resolved Contextual Reference
+ *
* @throws IllegalStateException if the bean could not be found.
* @see #getContextualReference(String, boolean)
*/
@@ -173,15 +177,16 @@ public final class BeanProvider
}
/**
- * <p>Get a Contextual Reference by its EL Name.
- * This only works for beans with the @Named annotation.</p>
+ * Get a Contextual Reference by its EL Name. This only works for beans with the @Named annotation.
*
- * <p><b>Attention:</b> please see the notes on manually resolving @Dependent bean
- * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
+ * <p>
+ * <b>Attention:</b> please see the notes on manually resolving @Dependent beans in
+ * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
*
* @param name the EL name of the bean
* @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
* Otherwise it will throw an {@code IllegalStateException}
+ *
* @return the resolved Contextual Reference
*/
public static Object getContextualReference(String name, boolean optional)
@@ -190,19 +195,19 @@ public final class BeanProvider
}
/**
- * <p>Get a Contextual Reference by its EL Name.
- * This only works for beans with the @Named annotation.</p>
+ * Get a Contextual Reference by its EL Name. This only works for beans with the @Named annotation.
*
- * <p><b>Attention:</b> please see the notes on manually resolving @Dependent bean
- * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
+ * <p>
+ * <b>Attention:</b> please see the notes on manually resolving @Dependent beans in
+ * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
*
- *
- * @param name the EL name of the bean
+ * @param name the EL name of the bean
* @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
* Otherwise it will throw an {@code IllegalStateException}
- * @param type the type of the bean in question - use {@link #getContextualReference(String, boolean)}
- * if the type is unknown e.g. in dyn. use-cases
- * @param <T> target type
+ * @param type the type of the bean in question - use {@link #getContextualReference(String, boolean)} if the
+ * type is unknown e.g. in dyn. use-cases
+ * @param <T> target type
+ *
* @return the resolved Contextual Reference
*/
public static <T> T getContextualReference(String name, boolean optional, Class<T> type)
@@ -248,9 +253,14 @@ public final class BeanProvider
/**
* Get the Contextual Reference for the given bean.
*
+ * <p>
+ * <b>Attention:</b> please see the notes on manually resolving @Dependent beans in
+ * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
+ *
* @param type the type of the bean in question
- * @param bean bean-definition for the contextual-reference
- * @param <T> target type
+ * @param bean bean definition for the contextual reference
+ * @param <T> target type
+ *
* @return the resolved Contextual Reference
*/
public static <T> T getContextualReference(Class<T> type, Bean<T> bean)
@@ -265,23 +275,23 @@ public final class BeanProvider
}
/**
- * <p>Get a list of Contextual References by type independent of the qualifier
- * (including dependent scoped beans).
+ * Get a list of Contextual References by type, regardless of qualifiers (including dependent scoped beans).
*
- * You can use this method to get all contextual references of a given type.
- * A 'Contextual Reference' is a proxy which will automatically resolve
- * the correct contextual instance when you access any method.</p>
+ * You can use this method to get all contextual references of a given type. A 'Contextual Reference' is a proxy
+ * which will automatically resolve the correct contextual instance when you access any method.
*
- * <p><b>Attention:</b> please see the notes on manually resolving @Dependent bean
- * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
- * <p><b>Attention:</b> This will also return instances of beans for which an Alternative
- * exists! The @Alternative resolving is only done via {@link BeanManager#resolve(java.util.Set)}
- * which we cannot use in this case!</p>
+ * <p>
+ * <b>Attention:</b> please see the notes on manually resolving @Dependent beans in
+ * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
+ * <p>
+ * <b>Attention:</b> This will also return instances of beans for which an Alternative exists! The @Alternative
+ * resolving is only done via {@link BeanManager#resolve(java.util.Set)} which we cannot use in this case!</p>
+ *
+ * @param type the type of the bean in question
+ * @param optional if <code>true</code> it will return an empty list if no bean could be found or created. Otherwise
+ * it will throw an {@code IllegalStateException}
+ * @param <T> target type
*
- * @param type the type of the bean in question
- * @param optional if <code>true</code> it will return an empty list if no bean could be found or created.
- * Otherwise it will throw an {@code IllegalStateException}
- * @param <T> target type
* @return the resolved list of Contextual Reference or an empty-list if optional is true
*/
public static <T> List<T> getContextualReferences(Class<T> type, boolean optional)
@@ -290,20 +300,22 @@ public final class BeanProvider
}
/**
- * <p>Get a list of Contextual References by type independent of the qualifier.
+ * Get a list of Contextual References by type, regardless of the qualifier.
*
- * Further details are available at {@link #getContextualReferences(Class, boolean)}
- * <p><b>Attention:</b> please see the notes on manually resolving @Dependent bean
- * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
- * <p><b>Attention:</b> This will also return instances of beans for which an Alternative
- * exists! The @Alternative resolving is only done via {@link BeanManager#resolve(java.util.Set)}
- * which we cannot use in this case!</p>
+ * Further details are available at {@link #getContextualReferences(Class, boolean)}.
+ * <p>
+ * <b>Attention:</b> please see the notes on manually resolving @Dependent bean in
+ * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
+ * <p>
+ * <b>Attention:</b> This will also return instances of beans for which an Alternative exists! The @Alternative
+ * resolving is only done via {@link BeanManager#resolve(java.util.Set)} which we cannot use in this case!</p>
*
- * @param type the type of the bean in question
- * @param optional if <code>true</code> it will return an empty list if no bean could be found or created.
- * Otherwise it will throw an {@code IllegalStateException}
+ * @param type the type of the bean in question
+ * @param optional if <code>true</code> it will return an empty list if no bean could be found or
+ * created. Otherwise it will throw an {@code IllegalStateException}
* @param includeDefaultScopedBeans specifies if dependent scoped beans should be included in the result
- * @param <T> target type
+ * @param <T> target type
+ *
* @return the resolved list of Contextual Reference or an empty-list if optional is true
*/
public static <T> List<T> getContextualReferences(Class<T> type,
@@ -356,14 +368,15 @@ public final class BeanProvider
}
/**
- * Get a set of {@link Bean} definitions by type independent of the qualifier.
+ * Get a set of {@link Bean} definitions by type, regardless of qualifiers.
*
- * @param type the type of the bean in question
- * @param optional if <code>true</code> it will return an empty set if no bean could be found.
- * Otherwise it will throw an {@code IllegalStateException}
- * @param includeDefaultScopedBeans specifies if dependent scoped beans should be included in the result
- * @param <T> target type
- * @return the resolved set of {@link Bean} definitions or an empty-set if optional is true
+ * @param type the type of the bean in question
+ * @param optional if <code>true</code> it will return an empty set if no bean could be found.
+ * Otherwise it will throw an {@code IllegalStateException}
+ * @param includeDefaultScopedBeans specifies whether dependent scoped beans should be included in the result
+ * @param <T> target type
+ *
+ * @return the resolved set of {@link Bean} definitions or an empty set if optional is true
*/
public static <T> Set<Bean<T>> getBeanDefinitions(Class<T> type,
boolean optional,
@@ -410,13 +423,14 @@ public final class BeanProvider
}
/**
- * Allows to perform dependency injection for instances which aren't managed by CDI.
+ * Performs dependency injection on an instance. Useful for instances which aren't managed by CDI.
* <p/>
- * Attention:<br/>
+ * <b>Attention:</b><br/>
* The resulting instance isn't managed by CDI; only fields annotated with @Inject get initialized.
*
* @param instance current instance
- * @param <T> current type
+ * @param <T> current type
+ *
* @return instance with injected fields (if possible - or null if the given instance is null)
*/
@SuppressWarnings("unchecked")
@@ -474,9 +488,8 @@ public final class BeanProvider
}
/**
- * Log a warning if the produced creational instance is of
- * Scope @Dependent as we cannot properly cleanup
- * the contextual instance afterwards.
+ * Log a warning if the given bean is of @Dependent scope as we cannot properly clean up the contextual
+ * instance afterwards.
*/
private static void logWarningIfDependent(Bean<?> bean)
{
@@ -488,8 +501,9 @@ public final class BeanProvider
}
/**
- * Internal method to resolve the BeanManager via the {@link BeanManagerProvider}
- * @return current bean-manager
+ * Internal method to resolve the BeanManager via the {@link BeanManagerProvider}.
+ *
+ * @return current BeanManager
*/
private static BeanManager getBeanManager()
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java
index 8e72653..2c89808 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java
@@ -30,14 +30,14 @@ import java.io.ObjectOutputStream;
import java.io.Serializable;
/**
- * A {@link Provider} for @Dependent scoped contextual instances.
- * We need this to be apble to properly clean them up when they are not
- * needed anymore via the {@link #destroy()} method.
+ * A {@link Provider} for @Dependent scoped contextual instances. We need this to be able to properly clean them up
+ * when they are not needed anymore via the {@link #destroy()} method.
*
* Instances of this class can be retrieved using the {@link BeanProvider}.
*
- * Instances of this class are Serializable if the wrapped contextual instance
- * is Serializable.
+ * Instances of this class are Serializable if the wrapped contextual instance is Serializable.
+ *
+ * @see BeanProvider#getDependent(java.lang.Class, java.lang.annotation.Annotation...)
*/
public class DependentProvider<T> implements Provider<T>, Serializable
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java
index f1ff1db..618ae62 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java
@@ -31,7 +31,7 @@ import java.util.logging.Level;
import java.util.logging.Logger;
/**
- * A classpath based resource provider
+ * A classpath-based resource provider.
*/
@ApplicationScoped
public class ClasspathResourceProvider extends AbstractResourceProvider
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java
index 8d5f5a0..72fd1f6 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java
@@ -27,7 +27,7 @@ import java.util.logging.Level;
import java.util.logging.Logger;
/**
- * A file based resource provider, looking for a file based on the name.
+ * A file-based resource provider, looking for a file based on the name.
*/
@ApplicationScoped
public class FileResourceProvider extends AbstractResourceProvider
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java
index 281f59b..aaffc27 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java
@@ -30,6 +30,27 @@ import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.ElementType.METHOD;
+/**
+ * Qualifier which enables simple injection of resources into beans, eliminating the need to deal with their loading.
+ *
+ * <p>
+ * <b>Example:</b>
+ * <pre>
+ * @Inject
+ * @InjectableResource("myfile.properties")
+ * private Properties props;
+ *
+ * @Inject
+ * @InjectableResource("config.xml")
+ * private InputStream inputStream;
+ * </pre>
+ *
+ * This can be used to read files, from classpath or the file system, using two default implementations:
+ * ClasspathResourceProvider and FileResourceProvider. They can be extended as well by implementing the
+ * InjectableResourceProvider interface to allow reading from alternate sources, if needed (e.g. database LOBs, NoSQL
+ * storage areas).
+ * </p>
+ */
@Target( { TYPE, METHOD, PARAMETER, FIELD })
@Retention(value = RetentionPolicy.RUNTIME)
@Documented
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java
index 1274392..5d5d102 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java
@@ -30,6 +30,11 @@ import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.PARAMETER;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
+/**
+ *
+ * @see GroupedConversationScoped
+ * @see ConversationSubGroup
+ */
@Target( { PARAMETER, FIELD, METHOD, CONSTRUCTOR, TYPE } )
@Retention(RUNTIME)
@Documented
@@ -38,7 +43,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
public @interface ConversationGroup
{
/**
- * Class or interface which should be used as type-safe key for identifying the conversation-group.
+ * Class or interface which should be used as type-safe key for identification of the conversation group.
*
* @return class or interface which should be used as key
*/
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java
index 1d4ba13..30fc91d 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java
@@ -26,45 +26,53 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * Allows to close a part of a group e.g.:
+ * Represents a subgroup of a conversation group. Useful for closing a subset of {@code @GroupConversationScoped} beans
+ * in a {@code ConversationGroup}.
*
+ * <pre>
* public class MyGroup{}
- * @ConversationScoped
- * @ConversationGroup(MyGroup.class)
+ *
+ * @ConversationScoped
+ * @ConversationGroup(MyGroup.class)
* public class BeanA {}
- * <p/>
- * @ConversationScoped
- * @ConversationGroup(MyGroup.class)
+ *
+ * @ConversationScoped
+ * @ConversationGroup(MyGroup.class)
* public class BeanB {}
- * <p/>
- * @ConversationScoped
- * @ConversationGroup(MyGroup.class)
+ *
+ * @ConversationScoped
+ * @ConversationGroup(MyGroup.class)
* public class BeanC {}
- * <p/>
- * @ConversationSubGroup(of = MyGroup.class, subGroup = {BeanA.class, BeanB.class})
+ *
+ * @ConversationSubGroup(of = MyGroup.class, subGroup = {BeanA.class, BeanB.class})
* public class MySubGroup {}
- * <br/>or</br>
- * @ConversationSubGroup(subGroup = {BeanA.class, BeanB.class})
+ * </pre> or
+ * <pre>
+ * @ConversationSubGroup(subGroup = {BeanA.class, BeanB.class})
* public class MySubGroup extends MyGroup {}
- * <p/>
+ *
* //...
* this.groupedConversationManager.closeConversation(MySubGroup.class)
- *
- * OR it's possible to use implicit sub-groups (point to the interface(s) instead of the bean-class itself):
+ * </pre> or it's possible to use implicit subgroups (point to the interface instead of the bean class itself):
+ * <pre>
* public interface MyUseCase {}
*
- * @ConversationSubGroup(of = MyGroup.class, subGroup = MyUseCase.class)
+ * @ConversationSubGroup(of = MyGroup.class, subGroup = MyUseCase.class)
* public class ImplicitSubGroup {}
*
- * @Named("myController")
- * @ConversationScoped
- * @ConversationGroup(MyGroup.class)
+ * @Named("myController")
+ * @ConversationScoped
+ * @ConversationGroup(MyGroup.class)
* public class MyController implements Serializable, MyUseCase
* {
* //...
* }
* //...
* this.groupedConversationManager.closeConversation(ImplicitSubGroup.class)
+ * </pre>
+ *
+ * @see ConversationGroup
+ * @see GroupedConversationScoped
*/
@Target(TYPE)
@Retention(RUNTIME)
@@ -72,14 +80,16 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
public @interface ConversationSubGroup
{
/**
- * Optionally defines the base conversation group
+ * Optionally defines the base conversation group.
+ *
* @return base conversation group or ConversationSubGroup if the subgroup inherits from the base conversation group
*/
Class<?> of() default ConversationSubGroup.class;
/**
- * Beans of the group which should be closed
- * @return beans of the group which should be closed
+ * Members of the subgroup.
+ *
+ * @return beans to include in the subgroup
*/
Class<?>[] subGroup();
}
[3/3] deltaspike git commit: DELTASPIKE-767 Comprehensive review of
javadoc: core/api
Posted by ra...@apache.org.
DELTASPIKE-767 Comprehensive review of javadoc: core/api
A non-comprehensive overview of changes (some may be from other commits):
* the term page-bean is rarely used, not used in doc at all, use view-controllers instead
* meta-data -> metadata
* English doesn't use that many dash-separated word compounds, rephrased/undashed/split as necessary
* replace occurrences of vague "the entry" or "current entry" with more descriptive ones like "this view-config"
* replace occ. of PageBean.class with ViewControllerRef.class
* make clear what's an example, e.g. SomePage.class instead of PageConfig.class which sounds like an API class
* page -> view
* "X allows to [infinitive verb]" is a non-existent construct in English syntax. Corrected all occurrences. It's meaningless in an API documentation (javadoc), since every single method "allows" the user to do something.
* Moved TODOs from javadocs to comments
* formatting (120 char line length)
* reorganized ConfigProperty
* less of "we", more passive forms
* refactored BeanProvider's javadoc, warnings about dependent, etc.
* ConversationSubGroup shouldn't only mention conversation closing
* added some links (@see) to enable discovery of features in javadoc
* removed some defensive-sounding design decision arguments ("this class exists because..."), reformulated to convey purpose
* configuration.ordinal -> deltaspike_ordinal
* (Solder) Catch -> Exception Control
Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/34b713b4
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/34b713b4
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/34b713b4
Branch: refs/heads/master
Commit: 34b713b41cc1a237cb128ac24207b76a6bb81d0c
Parents: 8138f1b
Author: Ron Smeral <rs...@redhat.com>
Authored: Sat Oct 25 03:09:34 2014 +0200
Committer: Rafael Benevides <ra...@gmail.com>
Committed: Tue Nov 11 17:31:21 2014 -0200
----------------------------------------------------------------------
.../deltaspike/core/api/common/DeltaSpike.java | 2 +-
.../core/api/config/ConfigProperty.java | 74 +++----
.../core/api/config/ConfigResolver.java | 163 ++++++++------
.../core/api/config/DeltaSpikeConfig.java | 17 +-
.../core/api/config/PropertyFileConfig.java | 31 ++-
.../core/api/config/PropertyLoader.java | 42 ++--
.../core/api/config/view/DefaultErrorView.java | 8 +-
.../core/api/config/view/ViewConfig.java | 4 +-
.../core/api/config/view/ViewRef.java | 9 +-
.../api/config/view/controller/InitView.java | 4 +-
.../config/view/controller/PostRenderView.java | 4 +-
.../config/view/controller/PreRenderView.java | 4 +-
.../config/view/controller/PreViewAction.java | 5 +-
.../view/controller/ViewControllerRef.java | 21 +-
.../api/config/view/metadata/Aggregated.java | 19 +-
.../view/metadata/CallbackDescriptor.java | 4 +-
.../config/view/metadata/ConfigDescriptor.java | 58 +++--
.../config/view/metadata/DefaultCallback.java | 46 ++--
.../metadata/ExecutableCallbackDescriptor.java | 6 +-
.../view/metadata/InlineViewMetaData.java | 11 +
.../view/metadata/SimpleCallbackDescriptor.java | 4 +-
.../config/view/metadata/SkipMetaDataMerge.java | 8 +-
.../view/metadata/ViewConfigDescriptor.java | 9 +-
.../view/metadata/ViewConfigResolver.java | 39 ++--
.../api/config/view/metadata/ViewMetaData.java | 8 +-
.../view/navigation/NavigationParameter.java | 13 +-
.../navigation/NavigationParameterContext.java | 2 +-
.../view/navigation/ViewNavigationHandler.java | 4 +-
.../event/PreViewConfigNavigateEvent.java | 8 +-
.../api/exception/control/BeforeHandles.java | 16 +-
.../api/exception/control/ExceptionHandler.java | 3 +
.../control/ExceptionHandlingFlow.java | 2 +-
.../api/exception/control/HandlerMethod.java | 5 +-
.../core/api/exception/control/Handles.java | 15 +-
.../exception/control/event/ExceptionEvent.java | 4 +-
.../control/event/ExceptionToCatchEvent.java | 7 +-
.../deltaspike/core/api/exclude/Exclude.java | 49 +++--
.../BasePropertyExpressionInterpreter.java | 2 +-
.../api/interpreter/ExpressionInterpreter.java | 13 +-
.../api/interpreter/SimpleOperationEnum.java | 2 +-
.../deltaspike/core/api/jmx/JmxBroadcaster.java | 5 +-
.../deltaspike/core/api/jmx/JmxManaged.java | 6 +-
.../apache/deltaspike/core/api/jmx/MBean.java | 14 +-
.../core/api/message/LocaleResolver.java | 13 +-
.../deltaspike/core/api/message/Message.java | 64 +++---
.../core/api/message/MessageBundle.java | 48 ++---
.../core/api/message/MessageContext.java | 17 +-
.../core/api/message/MessageContextConfig.java | 34 +--
.../core/api/message/MessageInterpolator.java | 26 ++-
.../core/api/message/MessageResolver.java | 13 +-
.../core/api/message/MessageTemplate.java | 29 ++-
.../core/api/projectstage/ProjectStage.java | 83 ++++----
.../api/projectstage/ProjectStageHolder.java | 13 +-
.../core/api/projectstage/TestStage.java | 4 +-
.../core/api/provider/BeanManagerProvider.java | 124 ++++++-----
.../core/api/provider/BeanProvider.java | 212 ++++++++++---------
.../core/api/provider/DependentProvider.java | 10 +-
.../ClasspathResourceProvider.java | 2 +-
.../resourceloader/FileResourceProvider.java | 2 +-
.../api/resourceloader/InjectableResource.java | 21 ++
.../core/api/scope/ConversationGroup.java | 7 +-
.../core/api/scope/ConversationSubGroup.java | 56 +++--
.../core/api/scope/ViewAccessScoped.java | 6 +-
.../deltaspike/core/api/scope/WindowScoped.java | 2 +-
64 files changed, 840 insertions(+), 716 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java
index 5811fa1..4f1d106 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java
@@ -29,7 +29,7 @@ import java.lang.annotation.Target;
import javax.inject.Qualifier;
/**
- * Common qualifier to manage co-existence of DeltaSpike features and JavaEE features.
+ * Common qualifier to manage co-existence of DeltaSpike features and Java EE features.
*/
@Target( { TYPE, METHOD, PARAMETER, FIELD })
@Retention(value = RetentionPolicy.RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java
index f1f44f5..e32fbda 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java
@@ -32,88 +32,75 @@ import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * <p>This Qualifier allows to use the DeltaSpike configuration mechanism
- * via simple injection.</p>
- *
- * <p>Example 1:
+ * This Qualifier allows simple injection of configuration properties through the DeltaSpike configuration
+ * mechanism.
+ * <p>
+ * A default implementation is provided in DeltaSpike for basic String injection points:
* <pre>
* @Inject @ConfigProperty(name="locationId")
* private String locationId;
* </pre>
* </p>
- *
- * <p>Example 2 (the type-safe alternative):
+ * <p>
+ * It's possible to use config properties in a type-safe manner, which requires a custom producer:
*
* <pre>
- * @Target({ FIELD, METHOD })
+ * @Target({FIELD, METHOD})
* @Retention(RUNTIME)
* @ConfigProperty(name = "locationId")
- * // alternative to null check in the producer:
- * // @ConfigProperty(name = "locationId", defaultValue = "LOCATION_X")
* @Qualifier
- * public @interface Location
- * {
+ * public @interface Location {
* }
* </pre>
- * </p>
*
- * Depending on the producer it's possible to use a String or a custom type like an enum at the injection point.
- * <p/>
- * With a String:
* <pre>
* @Location
* private String locationId;
* </pre>
*
- * With a custom type:
- * <pre>
- * @Inject
- * @Location
- * private LocationId locationId;
- * </pre>
- * <p>In any case a custom producer is needed.
- * {@link org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer} can be used as an base for custom
- * producers.
- * Producer for the configured String:
- * <pre>
+ * <pre>
* @ApplicationScoped
- * public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer
- * {
+ * public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer {
* @Produces
* @Dependent
* @Location
- * public String produceLocationId(InjectionPoint injectionPoint)
- * {
+ * public String produceLocationId(InjectionPoint injectionPoint) {
* String configuredValue = getStringPropertyValue(injectionPoint);
- * if (configuredValue == null)
- * {
+ * if (configuredValue == null) {
* return null;
* }
* return configuredValue;
* }
* }
* </pre>
+ * </p>
+ * <p>
+ * Producers can be implemented to support other types of injection points:
+ * <pre>
+ * @Inject
+ * @Location
+ * private LocationId locationId;
+ * </pre>
*
- * Producer for a custom type:
* <pre>
* @ApplicationScoped
- * public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer
- * {
+ * public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer {
* @Produces
* @Dependent
* @Location
- * public LocationId produceLocationId(InjectionPoint injectionPoint)
- * {
+ * public LocationId produceLocationId(InjectionPoint injectionPoint) {
* String configuredValue = getStringPropertyValue(injectionPoint);
- * if (configuredValue == null)
- * {
+ * if (configuredValue == null) {
* return null;
* }
* return LocationId.valueOf(configuredValue.trim().toUpperCase());
* }
* }
* </pre>
- *
+ * </p>
+ * For custom producer implementations, {@link org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer} can
+ * be used as the base class.
+ *
* @see org.apache.deltaspike.core.api.config.ConfigResolver
* @see org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer
*/
@@ -124,13 +111,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
public @interface ConfigProperty
{
/**
- * This constant is a workaround for the java restriction that Annotation values
- * cannot be set to null. Do not use this String in your configuration...
+ * This constant is a workaround for the java restriction that Annotation values cannot be set to null. Do not use
+ * this String in your configuration.
*/
String NULL = "org.apache.deltaspike.NullValueMarker";
/**
- * Name/key of the property
+ * Name/key of the property.
* @return name of the property
*/
@Nonbinding
@@ -138,6 +125,7 @@ public @interface ConfigProperty
/**
* <b>Optional</b> default value.
+ *
* @return the default value which should be used if no config value could be found
*/
@Nonbinding
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
index ae37147..c70557b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
@@ -39,11 +39,20 @@ import org.apache.deltaspike.core.util.ProjectStageProducer;
import org.apache.deltaspike.core.util.ServiceUtils;
/**
- * <p>Resolve the configuration via their well defined ordinals.</p>
+ * The main entry point to the DeltaSpike configuration mechanism.
*
- * <p>You can provide your own lookup paths by implementing
- * and registering additional {@link PropertyFileConfig} or
+ * <p>
+ * Resolves configured values of properties by going through the list of configured {@link ConfigSource}s and using the
+ * one with the highest ordinal. If multiple {@link ConfigSource}s have the same ordinal, their order is undefined.</p>
+ *
+ * <p>
+ * You can provide your own lookup paths by implementing and registering additional {@link PropertyFileConfig} or
* {@link ConfigSource} or {@link ConfigSourceProvider} implementations.</p>
+ *
+ * <p>
+ * The resolved configuration is also accessible by simple injection using the {@link ConfigProperty} qualifier.</p>
+ *
+ * @see <a href="http://deltaspike.apache.org/documentation/configuration.html">DeltaSpike Configuration Mechanism</a>
*/
@Typed()
public final class ConfigResolver
@@ -96,7 +105,7 @@ public final class ConfigResolver
}
/**
- * Clear all ConfigSources for the current ClassLoader
+ * Clear all ConfigSources for the current ClassLoader.
*/
public static synchronized void freeConfigSources()
{
@@ -104,9 +113,9 @@ public final class ConfigResolver
}
/**
- * Add a {@link ConfigFilter} to the ConfigResolver.
- * This will only affect the current WebApp
- * (or more precisely the current ClassLoader and it's children).
+ * Add a {@link ConfigFilter} to the ConfigResolver. This will only affect the current WebApp (or more precisely the
+ * current ClassLoader and it's children).
+ *
* @param configFilter
*/
public static void addConfigFilter(ConfigFilter configFilter)
@@ -132,14 +141,14 @@ public final class ConfigResolver
}
/**
- * Resolve the property value by going through the list of configured {@link ConfigSource}s
- * and use the one with the highest priority. If no configured value has been found that
- * way we will use the defaultValue.
+ * {@link #getPropertyValue(java.lang.String)} which returns the provided default value if no configured value can
+ * be found (<code>null</code> or empty).
*
- * @param key the property key.
- * @param defaultValue will be used if no configured value for the key could be found.
- * @return the configured property value from the {@link ConfigSource} with the highest ordinal or
- * the defaultValue if there is no value explicitly configured.
+ * @param key the property key
+ * @param defaultValue fallback value
+ *
+ * @return the configured property value from the {@link ConfigSource} with the highest ordinal or the defaultValue
+ * if there is no value explicitly configured
*/
public static String getPropertyValue(String key, String defaultValue)
{
@@ -149,12 +158,12 @@ public final class ConfigResolver
}
/**
- * Resolve the property value by going through the list of configured {@link ConfigSource}s
- * and use the one with the highest priority.
+ * Resolves the value configured for the given key.
+ *
+ * @param key the property key
*
- * @param key the property key.
- * @return the configured property value from the {@link ConfigSource} with the highest ordinal or
- * null if there is no configured value for it.
+ * @return the configured property value from the {@link ConfigSource} with the highest ordinal or null if there is
+ * no configured value for it
*/
public static String getPropertyValue(String key)
{
@@ -180,18 +189,22 @@ public final class ConfigResolver
}
/**
- * <p>Search for the configured value in all {@link ConfigSource}s and take the
- * current {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}
- * into account.</p>
+ * Resolves the value configured for the given key in the current
+ * {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}.
+ *
+ * <p>
+ * First, it will search for a value configured for the given key suffixed with the current ProjectStage (e.g.
+ * 'myproject.myconfig.Production'), and in case this value is not found (null or empty), it will look up the given
+ * key without any suffix.</p>
*
- * <p>It first will search if there is a configured value of the given key prefixed
- * with the current ProjectStage (e.g. 'myproject.myconfig.Production') and if this didn't
- * find anything it will lookup the given key without any prefix.</p>
+ * <p>
+ * <b>Attention</b> This method must only be used after all ConfigSources got registered and it also must not be
+ * used to determine the ProjectStage itself.</p>
*
- * <p><b>Attention</b> This method must only be used after all ConfigSources
- * got registered and it also must not be used to determine the ProjectStage itself.</p>
* @param key
- * @return the configured value or if non found the defaultValue
+ *
+ * @return the value configured for {@code <given key>.<current project stage>}, or just the configured value of
+ * {@code <given key>} if the project-stage-specific value is not found (null or empty)
*
*/
public static String getProjectStageAwarePropertyValue(String key)
@@ -207,10 +220,12 @@ public final class ConfigResolver
return value;
}
/**
- * {@link #getProjectStageAwarePropertyValue(String)} which returns the defaultValue
- * if the property is <code>null</code> or empty.
+ * {@link #getProjectStageAwarePropertyValue(String)} which returns the provided default value if no configured
+ * value can be found (<code>null</code> or empty).
+ *
* @param key
- * @param defaultValue
+ * @param defaultValue fallback value
+ *
* @return the configured value or if non found the defaultValue
*
*/
@@ -222,37 +237,42 @@ public final class ConfigResolver
}
/**
- * <p>Search for the configured value in all {@link ConfigSource}s and take the
- * current {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}
- * and the value configured for the given property into account.</p>
- *
- * <p>The first step is to resolve the value of the given property. This will
- * take the current ProjectStage into account. E.g. given the property is 'dbvendor'
- * and the ProjectStage is 'UnitTest', the first lookup is
- * <ul><li>'dbvendor.UnitTest'</li></ul>.
- * If this value is not found then we will do a 2nd lookup for
- * <ul><li>'dbvendor'</li></ul></p>
+ * Resolves the value configured for the given key, parameterized by the current
+ * {@link org.apache.deltaspike.core.api.projectstage.ProjectStage} and by the value of a second property.
*
- * <p>If a value was found for the given property (e.g. dbvendor = 'mysql'
- * then we will use this value to lookup in the following order until we
- * found a non-null value. If there was no value found for the property
- * we will only do the key+ProjectStage and key lookup.
- * In the following sample 'dataSource' is used as key parameter:
+ * <p>
+ * <b>Example:</b><br/>
+ * Suppose the current ProjectStage is {@code UnitTest} and we are looking for the value of {@code datasource}
+ * parameterized by the configured {@code dbvendor}.
+ * </p>
+ * <p>
+ * The first step is to resolve the value of the second property, {@code dbvendor}. This will also take the current
+ * ProjectStage into account. The following lookup is performed:
+ * <ul><li>dbvendor.UnitTest</li></ul>
+ * and if this value is not found then we will do a 2nd lookup for
+ * <ul><li>dbvendor</li></ul></p>
*
+ * <p>
+ * If a value was found for the second property (e.g. dbvendor = 'mysql') then we will use its value for the main
+ * lookup. If no value is found for the parameterized key {@code <key>.<second property value>.<project stage>}, we
+ * will do the {@code <key>.<second property value>}, then {@code <key>.<project stage>} and finally a {@code <key>}
+ * lookup:
* <ul>
- * <li>'datasource.mysql.UnitTest'</li>
- * <li>'datasource.mysql'</li>
- * <li>'datasource.UnitTest'</li>
- * <li>'datasource'</li>
+ * <li>datasource.mysql.UnitTest</li>
+ * <li>datasource.mysql</li>
+ * <li>datasource.UnitTest</li>
+ * <li>datasource</li>
* </ul>
* </p>
*
+ * <p>
+ * <b>Attention</b> This method must only be used after all ConfigSources got registered and it also must not be
+ * used to determine the ProjectStage itself.</p>
*
- * <p><b>Attention</b> This method must only be used after all ConfigSources
- * got registered and it also must not be used to determine the ProjectStage itself.</p>
* @param key
- * @param property the property to look up first
- * @return the configured value or if non found the defaultValue
+ * @param property the property to look up first and use as the parameter for the main lookup
+ *
+ * @return the configured value or null if no value is found for any of the key variants
*
*/
public static String getPropertyAwarePropertyValue(String key, String property)
@@ -274,15 +294,21 @@ public final class ConfigResolver
return value;
}
- /*
- * <p><b>Attention</b> This method must only be used after all ConfigSources
- * got registered and it also must not be used to determine the ProjectStage itself.</p>
+ /**
+ * {@link #getPropertyAwarePropertyValue(java.lang.String, java.lang.String)} which returns the provided default
+ * value if no configured value can be found (<code>null</code> or empty).
+ *
+ * <p>
+ * <b>Attention</b> This method must only be used after all ConfigSources got registered and it also must not be
+ * used to determine the ProjectStage itself.</p>
+ *
* @param key
- * @param property the property to look up first
- * @param defaultValue
+ * @param property the property to look up first and use as the parameter for the main lookup
+ * @param defaultValue fallback value
+ *
* @return the configured value or if non found the defaultValue
*
- */
+ */
public static String getPropertyAwarePropertyValue(String key, String property, String defaultValue)
{
String value = getPropertyAwarePropertyValue(key, property);
@@ -291,12 +317,12 @@ public final class ConfigResolver
}
/**
- * Resolve all values for the given key, from all registered ConfigSources ordered by their
- * ordinal value in ascending ways. If more {@link ConfigSource}s have the same ordinal, their
- * order is undefined.
+ * Resolve all values for the given key.
+ *
+ * @param key
+ *
+ * @return a List of all found property values, sorted by their ordinal in ascending order
*
- * @param key under which configuration is stored
- * @return List with all found property values, sorted in ascending order of their ordinal.
* @see org.apache.deltaspike.core.spi.config.ConfigSource#getOrdinal()
*/
public static List<String> getAllPropertyValues(String key)
@@ -323,6 +349,13 @@ public final class ConfigResolver
return result;
}
+ /**
+ * Returns a Map of all properties from all scannable config sources. The values of the properties reflect the
+ * values that would be obtained by a call to {@link #getPropertyValue(java.lang.String)}, that is, the value of the
+ * property from the ConfigSource with the highest ordinal.
+ *
+ * @see ConfigSource#isScannable()
+ */
public static Map<String, String> getAllProperties()
{
// must use a new list because Arrays.asList() is resistant to sorting on some JVMs:
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java
index 87ca2ce..3b51992 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java
@@ -21,18 +21,17 @@ package org.apache.deltaspike.core.api.config;
import java.io.Serializable;
/**
- * <p>Marker interface for all type-safe framework configs.</p>
+ * Marker interface for all classes used for configuration of DeltaSpike itself.
*
- * <p>All DeltaSpike Configuration objects implement this interface
- * so they can be found more easily. There is no other
+ * <p>
+ * All DeltaSpike configuration objects implement this interface so they can be found more easily. There is no other
* functionality implied with this interface.</p>
*
- * <p>DeltaSpike uses a <i>Typesafe Configuration</i> approach.
- * Instead of writing a properties file or XML, you just implement
- * one of the configuration interfaces which will then be picked up as
- * CDI bean. If there is already a default configuration for
- * some functionality in DeltaSpike, you can use @Specializes or
- * @Alternative to change those.</p>
+ * <p>
+ * DeltaSpike uses a <i>type-safe configuration</i> approach. Instead of writing a properties file or XML, you just
+ * implement one of the configuration interfaces which will then be picked up as a CDI bean. If there is already a
+ * default configuration for some functionality in DeltaSpike, you can use @Specializes or @Alternative to
+ * change those.</p>
*/
public interface DeltaSpikeConfig extends Serializable
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java
index 0d0a883..216ebe7 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java
@@ -19,29 +19,26 @@
package org.apache.deltaspike.core.api.config;
/**
- * <p>If you implement this interface inside a Bean Archive
- * (a JAR or ClassPath entry with a META-INF/beans.xml file),
- * the property files with the given file name
- * will be registered as {@link org.apache.deltaspike.core.spi.config.ConfigSource}s.</p>
+ * <p>
+ * If you implement this interface inside a Bean Archive (a JAR or ClassPath entry with a META-INF/beans.xml file), the
+ * property files with the given file name will be registered as
+ * {@link org.apache.deltaspike.core.spi.config.ConfigSource}s.</p>
*
- * <p>DeltaSpike will automatically pickup all the implementations
- * during the {@link javax.enterprise.inject.spi.ProcessAnnotatedType}
- * phase and create a new instance via reflection. Thus the
- * implementations will need a non-private default constructor.
- * There is <b>no</b> CDI injection being performed in those instances!
- * The scope of the implementations will also be ignored as they will
- * not get picked up as CDI beans.</p>
+ * <p>
+ * DeltaSpike will automatically pick up all the implementations during the
+ * {@link javax.enterprise.inject.spi.ProcessAnnotatedType} phase and create a new instance via reflection. Thus the
+ * implementations will need a non-private default constructor. There is <b>no</b> CDI injection being performed in
+ * those instances! The scope of the implementations will also be ignored as they will not get picked up as CDI
+ * beans.</p>
*
- * <p>Please note that the configuration will only be available
- * after the boot is finished. This means that you cannot use
- * this configuration inside a CDI Extension before the boot
- * is finished!</p>
+ * <p>
+ * Please note that the configuration will only be available after the boot is finished. This means that you cannot use
+ * this configuration inside a CDI Extension before the boot is finished!</p>
*/
public interface PropertyFileConfig extends DeltaSpikeConfig
{
/**
- * All the property files on the classpath which have this
- * name will get picked up and registered as
+ * All the property files on the classpath which have this name will get picked up and registered as
* {@link org.apache.deltaspike.core.spi.config.ConfigSource}s.
*
* @return the full file name (including path) of the property files to pick up.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java
index ecd7291..eb777da 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java
@@ -35,13 +35,14 @@ import java.util.logging.Level;
import java.util.logging.Logger;
/**
- * <p>Utility class to load configuration properties via a list of
- * artibrary property files by a well defined order.</p>
+ * Utility class to load configuration properties via arbitrary property files in a well defined order.
*
- * <p>This will also pick up property files which are post-fixed with
- * a -$projectStage.properties </p>
- * <p>User configurations should start with 'configuration.ordinal'
- * greater than 100.</p>
+ * <p>
+ * This will also pick up property files with names suffixed with {@code -<project stage>}, e.g.
+ * myconfig-Production.properties.</p>
+ * <p>
+ * User configurations should have {@code deltaspike_ordinal} as the first property, with a value greater than
+ * 100.</p>
*
*/
public class PropertyLoader
@@ -61,24 +62,25 @@ public class PropertyLoader
}
/**
- * <p>Look for all property files with the given name (e.g. 'myconfig.properties') in
- * the classpath. Then load all properties files and sort them by their ascending
- * configuration order and apply them in this order.</p>
+ * Looks for all properties files with the given name in the classpath, loads them in ascending order determined by
+ * their ordinal and merges them.
*
- * <p>The idea is to be able to 'override' properties by just providing
- * a new properties file with the same name but a higher 'deltaspike_ordinal'
- * than the old one.</p>
+ * <p>
+ * The idea is to be able to override properties by just providing a new properties file with the same name but a
+ * higher 'deltaspike_ordinal' than the old one.</p>
*
- * <p>If a property file defines no 'configuration.ordinal' property than a default
- * value of {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} is assumed. Any sensitive
- * default which is provided by the system parsing for the configuration should
- * have a 'configuration.ordinal' value lower than 10. In most cases a value of 1</p>
+ * <p>
+ * If a property file defines no 'deltaspike_ordinal' property than a default value of
+ * {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} is assumed. Any sensitive default which is provided by the system
+ * parsing for the configuration should have a 'deltaspike_ordinal' value lower than 10. In most cases a value of
+ * 1.</p>
*
- * <p>If 2 property files have the same ordinal 'configuraiton.order' the outcome
- * is not really defined. The Properties file which got found first will be
- * processed first and thus get overwritten by the one found later.</p>
+ * <p>
+ * If two property files have the same 'deltaspike_ordinal', their order is undefined. The Properties file which
+ * gets found first will be processed first and thus gets overwritten by the one found later.</p>
*
* @param propertyFileName the name of the properties file, without the extension '.properties'
+ *
* @return the final property values
*/
public static synchronized Properties getProperties(String propertyFileName)
@@ -205,7 +207,7 @@ public class PropertyLoader
}
/**
- * Determine the 'configuration.ordinal' of the given properties.
+ * Determine the 'deltaspike_ordinal' of the given properties.
* {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} if
* {@link ConfigSource#DELTASPIKE_ORDINAL} is not set in the
* Properties file.
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java
index 5305907..9bdf5c6 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java
@@ -20,11 +20,9 @@ package org.apache.deltaspike.core.api.config.view;
/**
* Abstract class which marks an error view.
- * <p/>
- * It's an abstract class instead of an interface,
- * because you can use it for navigation (which is restricted to classes).
- * (Since only the final page should be a class and for the rest it's recommended to use interfaces,
- * it isn't a problem/restriction.)
+ *
+ * It's an abstract class instead of an interface, because it can be used for navigation (which is restricted to
+ * classes).
*/
public abstract class DefaultErrorView implements ViewConfig
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java
index 66db48a..ab8a017 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java
@@ -19,8 +19,8 @@
package org.apache.deltaspike.core.api.config.view;
/**
- * Marker interface for type-safe view-config classes.
- * Required for view-configs which represent a (logical) page and optional for the rest (e.g. folder-configs).
+ * Marker interface for type-safe view-config classes. Required for view-configs which represent a (logical) page and
+ * optional for the rest (e.g. folder-configs).
*/
public interface ViewConfig
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java
index 8c4a786..4634631 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java
@@ -35,7 +35,10 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * Allows to reference a view-config
+ * A reference to a view-config, applied on a view-controller. The opposite direction of {@link ViewControllerRef}.
+ *
+ * ViewRef annotation instances are not present at runtime as metadata, they are instead transformed to
+ * ViewControllerRef instances during deployment.
*/
@Target({ TYPE, METHOD })
@@ -52,9 +55,9 @@ public @interface ViewRef
}
/**
- * Specifies the pages via type-safe {@link ViewConfig}.
+ * Specifies the views to bind to the view-controller.
*
- * @return views which should be aware of the bean or observer
+ * @return {@link ViewConfig}s of views bound to the view-controller
*/
@Nonbinding Class<? extends ViewConfig>[] config();
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java
index 4bb4e44..7764c1e 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java
@@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * View-controller annotation for page-beans.
- * Methods annotated with this annotation will be invoked as soon as a view has been initialized.
+ * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked as soon as a view
+ * has been initialized.
*/
@Target(METHOD)
@Retention(RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java
index 6148759..a6b4f23 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java
@@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * View-controller annotation for page-beans.
- * Methods annotated with this annotation will be invoked after the view gets rendered.
+ * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked after the view gets
+ * rendered.
*/
@Target(METHOD)
@Retention(RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java
index 0bde410..baf8e68 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java
@@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * View-controller annotation for page-beans.
- * Methods annotated with this annotation will be invoked before the view gets rendered.
+ * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked before the view gets
+ * rendered.
*/
@Target(METHOD)
@Retention(RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java
index 0d835cb..8ced102 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java
@@ -26,9 +26,8 @@ import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * View-controller annotation for page-beans.
- * Methods annotated with this annotation will be invoked before the method binding gets invoked.
- * Usually only used for using a callback in the page-bean in parallel with 3rd party flow-engines
+ * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked before the method
+ * binding gets invoked. Can be used as a callback in a view-controller in parallel with 3rd party flow-engines.
*/
@Target(METHOD)
@Retention(RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java
index e107db1..a767e84 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java
@@ -18,11 +18,6 @@
*/
package org.apache.deltaspike.core.api.config.view.controller;
-/**
- * Specifies one or more page-beans via the type-safe view-config.
- * Such page beans support e.g. the view-controller annotations.
- */
-
import org.apache.deltaspike.core.api.config.view.metadata.SimpleCallbackDescriptor;
import org.apache.deltaspike.core.api.config.view.metadata.ViewMetaData;
import org.apache.deltaspike.core.spi.config.view.ConfigPreProcessor;
@@ -36,6 +31,10 @@ import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
+/**
+ * Specifies one or more view-controllers for the view-config which has this annotation applied. View-controllers can
+ * handle callbacks like {@link InitView}, {@link PreRenderView}, etc.
+ */
//don't use @Inherited
@Target(TYPE)
@Retention(RUNTIME)
@@ -45,19 +44,17 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
public @interface ViewControllerRef
{
/**
- * Class of the page-bean
+ * Class of the view-controller.
*
- * @return class of the page-bean
+ * @return class of the view-controller
*/
Class<?> value();
/**
- * Currently not implemented
- *
- *
- * Optional name of the page-bean
+ * Currently not implemented.
+ * Optional name of the view-controller.
*
- * @return name of the page-bean
+ * @return name of the view-controller
*/
//TODO
String name() default "";
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java
index c163219..a0c6aca 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java
@@ -26,20 +26,23 @@ import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * This annotation can be used to mark annotations as aggregated meta-data.
- * Core just provides this annotation, but the concrete behaviour is defined by a concrete ConfigNodeConverter.
- * E.g. DefaultConfigNodeConverter uses the result stored in ViewConfigNode#getInheritedMetaData to replace
- * default- (/ null-) values of "higher" levels with custom values of "lower" levels,
- * if #value is 'true'.
+ * Marks view-metadata annotations or their fields as aggregated metadata. That results in retention of multiple
+ * instances of such annotation per view instead of the metadata getting overriden by lower levels.
+ *
+ * Core just provides this annotation, but the concrete behaviour is defined by a concrete ConfigNodeConverter. E.g.
+ * DefaultConfigNodeConverter uses the result stored in
+ * {@link org.apache.deltaspike.core.spi.config.view.ViewConfigNode#getInheritedMetaData} to replace default- (/ null-)
+ * values of "higher" levels with custom values of "lower" levels, if #value is 'true'.
*/
-@Target({ ANNOTATION_TYPE }) //TODO re-visit and discuss method-level (for annotation-attributes)
+//TODO re-visit and discuss method-level (for annotation-attributes)
+@Target({ ANNOTATION_TYPE })
@Retention(RUNTIME)
@Documented
public @interface Aggregated
{
/**
- * @return false to override the same meta-data type of the parent view-config and
- * true to allow multiple instances of a meta-data per view
+ * @return false to override the same metadata type of the parent view-config, and true to allow multiple instances
+ * of a metadata per view
*/
boolean value();
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java
index cb7e1c8..848c5aa 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java
@@ -31,8 +31,8 @@ import java.util.List;
import java.util.Map;
/**
- * Basic descriptor for a given class and callback-type.
- * It finds and caches the method/s of the given class which are annotated with the given callback-type.
+ * Basic descriptor for a given class and callback type. It finds and caches the method(s) of the given class which are
+ * annotated with the given callback-type.
*/
public abstract class CallbackDescriptor
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java
index df4383b..401dfe5 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java
@@ -22,51 +22,60 @@ import java.lang.annotation.Annotation;
import java.util.List;
/**
- * Base descriptor for all type-safe view-configs which represents the
- * config-class and meta-data, callbacks,... provided by/bound to this class.
+ * Base descriptor for all type-safe view-configs which describes the config class, metadata, callbacks and other
+ * properties of a view-config.
+ *
+ * @param <CT> class of the view-config
*/
-public interface ConfigDescriptor<CT /*config type*/>
+public interface ConfigDescriptor<CT>
{
Class<? extends CT> getConfigClass();
/**
- * Meta-data which is configured for the entry. It allows to provide and resolve meta-data annotated
- * with {@link ViewMetaData}
+ * Metadata configured for this view-config. Resolves {@link ViewMetaData}-annotated annotations which are inherited
+ * or directly present on the view-config class.
*
- * @return meta-data of the current entry
+ * @return metadata of this view-config
*/
List<Annotation> getMetaData();
/**
- * Meta-data which is configured for the entry. It allows to provide and resolve meta-data annotated
- * with {@link ViewMetaData}
+ * Metadata which is configured for this view-config. Resolves {@link ViewMetaData}-annotated annotations which are
+ * inherited or directly present on the view-config class.
*
* @param target target type
- * @return custom meta-data for the given type of the current entry
+ *
+ * @return custom metadata for the given type of this view-config
*/
<T extends Annotation> List<T> getMetaData(Class<T> target);
/**
- * Callbacks which are configured for the entry and bound to the given meta-data type.
- * @param metaDataType type of the meta-data (e.g. PageBean.class)
- * @return descriptor for the callback or null if there is no callback-method
+ * Callbacks which are configured for this view-config and bound to the given metadata type.
+ *
+ * @param metaDataType type of the metadata (e.g. ViewControllerRef.class)
+ *
+ * @return descriptor for the callback or null if there is no callback method
*/
CallbackDescriptor getCallbackDescriptor(Class<? extends Annotation> metaDataType);
/**
- * Callbacks which are configured for the entry and bound to the given meta-data type.
- * @param metaDataType type of the meta-data (e.g. PageBean.class)
+ * Callbacks which are configured for this view-config and bound to the given metadata type.
+ *
+ * @param metaDataType type of the metadata (e.g. ViewControllerRef.class)
* @param callbackType type of the callback (e.g. PreRenderView.class)
+ *
* @return descriptor for the callback null if there is no callback-method
*/
CallbackDescriptor getCallbackDescriptor(Class<? extends Annotation> metaDataType,
Class<? extends Annotation> callbackType);
/**
- * Callbacks which are configured for the entry and bound to the given meta-data type.
- * @param metaDataType type of the meta-data (e.g. PageBean.class)
- * @param executorType type of the executor which allows to get a typed result (e.g. Secured.Descriptor)
- * @return descriptor for the callback which also allows to invoke it or null if there is no callback-method
+ * Callbacks which are configured for this view-config and bound to the given metadata type.
+ *
+ * @param metaDataType type of the metadata (e.g. ViewControllerRef.class)
+ * @param executorType type of the executor which returns a typed result (e.g. Secured.Descriptor)
+ *
+ * @return executable descriptor for the callback or null if there is no callback method
*/
@SuppressWarnings("rawtypes")
//TODO <T extends ExecutableCallbackDescriptor<?>> when major version is incremented
@@ -74,11 +83,13 @@ public interface ConfigDescriptor<CT /*config type*/>
Class<? extends T> executorType);
/**
- * Callbacks which are configured for the entry and bound to the given meta-data type.
- * @param metaDataType type of the meta-data (e.g. PageBean.class)
+ * Callbacks which are configured for this view-config and bound to the given metadata type.
+ *
+ * @param metaDataType type of the metadata (e.g. ViewControllerRef.class)
* @param callbackType type of the callback (e.g. PreRenderView.class)
- * @param executorType type of the executor which allows to get a typed result (e.g. Secured.Descriptor)
- * @return descriptor for the callback which also allows to invoke it or null if there is no callback-method
+ * @param executorType type of the executor which returns a typed result (e.g. Secured.Descriptor)
+ *
+ * @return executable descriptor for the callback or null if there is no callback method
*/
@SuppressWarnings("rawtypes")
//TODO <T extends ExecutableCallbackDescriptor<?>> when major version is incremented
@@ -87,7 +98,8 @@ public interface ConfigDescriptor<CT /*config type*/>
Class<? extends T> executorType);
/**
- * Returns the string representation of the resource represented by #getConfigClass
+ * Returns the string representation of the resource (page, folder) represented by this view-config.
+ *
* @return relative path to the folder or page
*/
String getPath();
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java
index b4acf5a..34b794a 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java
@@ -25,38 +25,44 @@ import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
-@Target( METHOD )
-@Retention(RUNTIME)
-@Documented
-
/**
- * A ConfigDescriptor can contain CallbackDescriptors in general as well as ExecutableCallbackDescriptors.
- * An ExecutableCallbackDescriptor can reference one or multiple callback-method/s. If there is only one callback type,
- * it's possible to annotate it with @DefaultCallback.
- * That allows to handle it in an easier fashion
- * (= without providing a special marker (-annotation) for the target method).
+ * A ConfigDescriptor can contain CallbackDescriptors or ExecutableCallbackDescriptors. An ExecutableCallbackDescriptor
+ * can reference one or more callback method(s). If there is only one callback type, it's possible to annotate it with
+ * {@code @DefaultCallback}. That eliminates the need for a special marker annotation for the target method.
+ *
+ * If there are multiple callback types, it's necessary to use custom annotations as marker for the target method (e.g.
+ * see {@code @Secured} vs. {@code @ViewControllerRef}).
*
- * If there are multiple callback types, it's needed to use custom annotations as marker for the target method.
- * (e.g. see @Secured vs. @ViewControllerBean)
+ * <pre>
+ * {@code
+ * ViewConfigDescriptor viewConfigDescriptor = viewConfigResolver.getViewConfigDescriptor(SomePage.class);
*
- * ViewConfigDescriptor viewConfigDescriptor = viewConfigResolver.getViewConfigDescriptor(PageConfig.class);
* viewConfigDescriptor.getExecutableCallbackDescriptor(
* Secured.class, Secured.Descriptor.class).execute(accessDecisionVoterContext);
- * is short for
+ * }</pre> is short for
+ * <pre>
+ * {@code
* viewConfigDescriptor.getExecutableCallbackDescriptor(
* Secured.class, DefaultCallback.class, Secured.Descriptor.class).execute(accessDecisionVoterContext);
+ * }</pre>
*
* whereas e.g.
+ * <pre>
+ * {@code
* viewConfigDescriptor.getExecutableCallbackDescriptor(
- * ViewControllerBean.class, PreRenderView.class, ViewControllerBean.ViewControllerDescriptor.class).execute();
- * or just
+ * ViewControllerRef.class, PreRenderView.class, ViewControllerRef.Descriptor.class).execute();
+ * }</pre> or just
+ * <pre>
+ * {@code
* viewConfigDescriptor.getExecutableCallbackDescriptor(
- * ViewControllerBean.class, PreRenderView.class, SimpleCallbackDescriptor.class).execute();
- *
- * are needed to call only @PreRenderView callbacks
- * (and not the others like @InitView which are also bound to @ViewControllerBean)
+ * ViewControllerRef.class, PreRenderView.class, SimpleCallbackDescriptor.class).execute();
+ * }</pre> are needed to call @PreRenderView callbacks specifically (instead of the others like @InitView which are also
+ * bound to @ViewControllerRef).
*/
//TODO find a better name
-public @interface DefaultCallback
+@Target( METHOD )
+@Retention(RUNTIME)
+@Documented
+public @interface DefaultCallback
{
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java
index 16c80b5..afa3bb5 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java
@@ -26,9 +26,9 @@ import java.util.ArrayList;
import java.util.List;
/**
- * Specialized {@link CallbackDescriptor}
- * which provides {@link #execute} only for concrete descriptors, but doesn't expose it (-> can't get used by accident).
- * Concrete implementations can provide type-safe versions of it, but delegate the final execution to {@link #execute}.
+ * Specialized {@link CallbackDescriptor} which provides {@link #execute} only for concrete descriptors, but doesn't
+ * expose it (and can't get used by accident). Concrete implementations can provide type-safe versions of it, but
+ * delegate the final execution to {@link #execute}.
*
* @param <R> return type
*/
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java
index 15e07ba..a157e5a 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java
@@ -28,6 +28,17 @@ import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
+/**
+ * Provides the ability to apply metadata to a view-config "remotely" – from a
+ * different place than the view-config itself (and with different syntax and a different annotation).
+ *
+ * <p>
+ * <b>For example</b>, the @ViewControllerRef (main) vs. @ViewRef (inline) – the @ViewControllerRef is applied
+ * directly on a view-config and references a view-controller, but there's also @ViewRef, which has the same purpose,
+ * but is applied in reverse – on a view-controller, referencing a view-config.
+ * </p>
+ */
+
@Target({ ANNOTATION_TYPE })
@Retention(RUNTIME)
@Documented
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java
index 81b828e..5d7ff6b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java
@@ -22,8 +22,8 @@ import java.lang.annotation.Annotation;
import java.util.List;
/**
- * {@link ExecutableCallbackDescriptor} for simple callback-methods without (supported) parameters,
- * which exposes #execute without parameters.
+ * {@link ExecutableCallbackDescriptor} for simple callback methods without (supported) parameters, which exposes
+ * #execute without parameters.
*
* @param <R> return type
*/
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java
index acbf094..9e37d14 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java
@@ -25,13 +25,13 @@ import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
+/**
+ * Disables metadata merging on attributes of @ViewMetaData annotations. Used in cases (e.g. @Folder#name) where it
+ * doesn't make sense to merge that part with inherited information.
+ */
@Target( METHOD )
@Retention(RUNTIME)
@Documented
-
-/**
- * In some cases (e.g. @Folder#name) it doesn't make sense to merge that part with inherited information.
- */
public @interface SkipMetaDataMerge
{
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java
index 7a937f8..0a2fe9f 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java
@@ -21,17 +21,16 @@ package org.apache.deltaspike.core.api.config.view.metadata;
import org.apache.deltaspike.core.api.config.view.ViewConfig;
/**
- * Descriptor which represents a concrete view (/page).
+ * Descriptor which represents a concrete view (page).
*/
public interface ViewConfigDescriptor extends ConfigDescriptor<ViewConfig>
{
/**
- * View-ID of the current descriptor
- * The default implementation returns the same as ConfigDescriptor#getPath.
- * For the default implementation (and default integration with JSF) it's in place to provide a straightforward API.
+ * View ID of the current descriptor. The default implementation returns the same as ConfigDescriptor#getPath. For
+ * the default implementation (and default integration with JSF) it's in place to provide a straightforward API.
* However, e.g. an integration for a different view technology can use it e.g. for a logical id.
*
- * @return current view-id
+ * @return current view ID
*/
String getViewId();
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java
index 82d2de7..514205c 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java
@@ -23,13 +23,13 @@ import org.apache.deltaspike.core.api.config.view.ViewConfig;
import java.util.List;
/**
- * Resolver for view-configs
+ * Resolver of view-configs.
*
- * A {@link ConfigDescriptor} can be bound to any config-class (without required base-type).
- * That's needed e.g. for folder-configs. Whereas {@link ViewConfigDescriptor}s only represent config-classes which
- * inherit from {@link ViewConfig} which is required for all page-configs.
+ * A {@link ConfigDescriptor} can be bound to any config class (without required base type). That's needed e.g. for
+ * folder-configs. Whereas {@link ViewConfigDescriptor}s only represent classes which inherit from {@link ViewConfig}
+ * which is required for all view-configs.
*
- * Use {@link org.apache.deltaspike.core.spi.config.view.ViewConfigRoot} to configure a custom resolver.
+ * Use {@link org.apache.deltaspike.core.spi.config.view.ViewConfigRoot} to register a custom resolver.
*/
//TODO re-visit name since we also need ConfigDescriptor
public interface ViewConfigResolver
@@ -37,48 +37,51 @@ public interface ViewConfigResolver
ConfigDescriptor<?> getConfigDescriptor(String path);
/**
- * Resolves the {@link ConfigDescriptor} for the given config-class
+ * Resolves the {@link ConfigDescriptor} for the given class.
*
- * @param configClass config-class (which usually represents a folder node)
- * @return config-descriptor which represents the given config-class
+ * @param configClass config class which usually represents a folder node
+ *
+ * @return config descriptor which represents the given config class
*/
ConfigDescriptor<?> getConfigDescriptor(Class<?> configClass);
//TODO re-visit name (depends on other discussions)
/**
- * Resolves all descriptors for folders
+ * Resolves all descriptors for folders.
*
- * @return all descriptors for the known view-configs
+ * @return all descriptors for the known folder-configs
*/
List<ConfigDescriptor<?>> getConfigDescriptors();
/**
- * Resolves the {@link ViewConfigDescriptor} for the given view-id
+ * Resolves the {@link ViewConfigDescriptor} for the given view-id.
*
* @param viewId view-id of the page
- * @return view-config-descriptor which represents the given view-id, null otherwise
+ *
+ * @return view-config descriptor which represents the given view-id, null otherwise
*/
ViewConfigDescriptor getViewConfigDescriptor(String viewId);
/**
- * Resolves the {@link ViewConfigDescriptor} for the given view-config-class
+ * Resolves the {@link ViewConfigDescriptor} for the given view-config class.
+ *
+ * @param viewDefinitionClass view-config class of the page
*
- * @param viewDefinitionClass view-config-class of the page
- * @return view-config-descriptor which represents the given view-config-class
+ * @return view-config descriptor which represents the given view-config class
*/
ViewConfigDescriptor getViewConfigDescriptor(Class<? extends ViewConfig> viewDefinitionClass);
/**
- * Resolves all descriptors for the known {@link ViewConfig}s
+ * Resolves all descriptors for the known {@link ViewConfig}s.
*
* @return all descriptors for the known view-configs
*/
List<ViewConfigDescriptor> getViewConfigDescriptors();
/**
- * Resolves the descriptor for the default-error page
+ * Resolves the descriptor for the default error page.
*
- * @return descriptor for the default-error page
+ * @return descriptor for the default error page
*/
ViewConfigDescriptor getDefaultErrorViewConfigDescriptor();
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java
index 095d5f8..a1f16c9 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java
@@ -28,9 +28,11 @@ import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * This meta-annotation allows to create custom meta-data which can be used for view-configs.
- * Per default meta-data of a lower level overrides meta-data on a higher level which has the same type.
- * Can be customized via annotating the final annotation as a whole via @Aggregated(true) or only special fields of it.
+ * Meta-annotation for custom metadata which can be applied to view-configs.
+ *
+ * By default, metadata of a lower level overrides metadata of the same type from a higher level (cascading behaviour).
+ * This behaviour can be changed by annotating the target annotation (or only chosen fields of it) with
+ * {@code @Aggregated(true)}.
*/
@Target({ ANNOTATION_TYPE })
@Retention(RUNTIME)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java
index 9b84ddf..fdecffc 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java
@@ -32,8 +32,9 @@ import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
- * This annotation can be used as interceptor for JSF action methods as an alternative for
- * {@link org.apache.deltaspike.core.api.config.view.navigation.NavigationParameterContext}.
+ * Used on JSF action methods, this adds navigation parameters (key-value pairs) to the resulting navigation string.
+ * Alternatively, {@link org.apache.deltaspike.core.api.config.view.navigation.NavigationParameterContext} can be used
+ * to add the parameters.
*/
@Target({ METHOD, TYPE })
@Retention(RUNTIME)
@@ -45,14 +46,14 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
public @interface NavigationParameter
{
/**
- * Key of the parameter
+ * Key of the parameter.
*
* @return name of the key
*/
@Nonbinding String key();
/**
- * Value or EL-Expression of the parameter
+ * Value of the parameter, a plain String or an EL expression.
*
* @return ref or expression
*/
@@ -64,7 +65,7 @@ public @interface NavigationParameter
//TODO add special support for list-annotations (add value automatically)
/**
- * Allows to specify multiple parameters (@see ViewParameter)
+ * A container for multiple NavigationParameters.
*/
@ViewMetaData
@Aggregated(true)
@@ -72,7 +73,7 @@ public @interface NavigationParameter
public static @interface List
{
/**
- * 1-n parameters
+ * One or more navigation parameters.
*
* @return parameters
*/
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java
index 207ad02..5efa3d0 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java
@@ -22,7 +22,7 @@ import java.io.Serializable;
import java.util.Map;
/**
- * Can be used to add parameters dynamically to the final navigation string
+ * Can be used to add parameters dynamically to the final navigation string.
*/
public interface NavigationParameterContext extends Serializable
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java
index 80b8fd3..4c60eda 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java
@@ -21,14 +21,14 @@ package org.apache.deltaspike.core.api.config.view.navigation;
import org.apache.deltaspike.core.api.config.view.ViewConfig;
/**
- * Allows to trigger manual navigation via the type-safe {@link ViewConfig} approach.
+ * A type-safe {@link ViewConfig}-based NavigationHandler wrapper.
*/
public interface ViewNavigationHandler
{
/**
* Triggers navigation to the given view.
*
- * @param targetView the view which is the navigation target
+ * @param targetView the navigation target
*/
void navigateTo(Class<? extends ViewConfig> targetView);
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java
index 110cf61..c98af03 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java
@@ -21,8 +21,8 @@ package org.apache.deltaspike.core.api.config.view.navigation.event;
import org.apache.deltaspike.core.api.config.view.ViewConfig;
/**
- * Event will be fired before the navigation (from and to a view-config based page) occurs.
- * With {@link #navigateTo(Class)} it's possible to change the navigation target.
+ * This event is fired before a navigation from/to a view-config-based page occurs. With {@link #navigateTo(Class)} it's
+ * possible to change the navigation target.
*/
public class PreViewConfigNavigateEvent
{
@@ -30,7 +30,7 @@ public class PreViewConfigNavigateEvent
private Class<? extends ViewConfig> toView;
/**
- * Constructor for creating the event for the given source and target view
+ * Constructor for creating the event for the given source and target view.
*
* @param fromView source-view
* @param toView target-view
@@ -62,7 +62,7 @@ public class PreViewConfigNavigateEvent
}
/**
- * Allows to change the navigation target.
+ * Changes the navigation target.
*
* @param toView new navigation target
*/
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java
index 8e7078a..707d457 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java
@@ -27,10 +27,15 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marker annotation for a method to be considered an Exception Handler, handles the exception in the BEFORE
- * traversal of the exception chain. Handlers are typically in the form of
- * <code>public void ... (@BeforeHandles ... CaughtException<...> ...)</code> methods.
- * If a method has a return type, it is ignored.
+ * Marker annotation for a method to be considered an Exception Handler, handles the exception in the BEFORE traversal
+ * of the exception chain.
+ * <p>
+ * Handlers methods typically have this form:<br />
+ * <pre>public void handle(@BeforeHandles <i>@OptionalQualifier</i> ExceptionEvent<<i>TypeOfTheException</i>> evt)
+ * </pre>.
+ * </p>
+ *
+ * If a handler method has a return type, it is ignored.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
@@ -38,7 +43,8 @@ import java.lang.annotation.Target;
public @interface BeforeHandles
{
/**
- * Precedence relative to callbacks for the same type
+ * Precedence relative to callbacks for the same type. Handler with a higher ordinal is invoked before a handler
+ * with a lower ordinal.
*/
int ordinal() default 0;
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java
index d706909..83a3e2f 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java
@@ -27,6 +27,9 @@ import java.lang.annotation.Target;
/**
* Marker for types containing Exception Handler methods.
+ *
+ * @see BeforeHandles
+ * @see Handles
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java
index e454e86..eef759d 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java
@@ -20,7 +20,7 @@
package org.apache.deltaspike.core.api.exception.control;
/**
- * Flow control enum. Used in the dispatcher to determine how to markHandled.
+ * Enum of exception handling states. Used in the dispatcher to determine how to markHandled.
*/
public enum ExceptionHandlingFlow
{
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java
index d875b05..22d7c14 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java
@@ -27,7 +27,7 @@ import java.lang.reflect.Type;
import java.util.Set;
/**
- * Meta data interface about an exception handler. It is the responsibility of the
+ * Metadata interface for an exception handler method. It is the responsibility of the
* implementation to support {@link javax.enterprise.inject.spi.InjectionPoint}s and to
* validate those {@link javax.enterprise.inject.spi.InjectionPoint}s.
*
@@ -59,7 +59,8 @@ public interface HandlerMethod<T extends Throwable>
void notify(ExceptionEvent<T> event, BeanManager beanManager) throws Exception;
/**
- * Obtains the precedence of the handler, relative to other handlers for the same type.
+ * Obtains the precedence of the handler, relative to other handlers for the same type. Handler with a higher
+ * ordinal is invoked before a handler with a lower ordinal.
*/
int getOrdinal();
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java
index 8d86160..d915bfc 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java
@@ -26,9 +26,15 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marker annotation for a method to be considered an Exception Handler. Handlers are typically in the form of
- * <code>public void ... (@Handles ... CaughtException<...> ...)</code> methods. If a method has a return type, it is
- * ignored.
+ * Marker annotation for a method to be considered an Exception Handler.
+ *
+ * <p>
+ * Handlers typically have this form:
+ * <pre>
+ * public void handle(@Handles <i>@OptionalQualifier</i> ExceptionEvent<<i>TypeOfTheException</i>> evt)</pre>
+ * </p>
+ *
+ * If a handler method has a return type, it is ignored.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
@@ -36,7 +42,8 @@ import java.lang.annotation.Target;
public @interface Handles
{
/**
- * Precedence relative to handlers for the same type
+ * Precedence relative to handlers for the same type. Handler with a higher ordinal is invoked before a handler with
+ * a lower ordinal.
*/
int ordinal() default 0; //TODO discuss Precedence
}
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java
index c4a2402..42a6b60 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java
@@ -20,8 +20,8 @@
package org.apache.deltaspike.core.api.exception.control.event;
/**
- * Payload for an exception to be handled. Implementations of this interface should not expose internals and remain
- * immutable for this contract.
+ * Payload for an exception to be handled. Implementations of this interface should not expose internals and should
+ * remain immutable.
*
* @param <T> Exception type this event represents
*/
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java
index c134645..18b8fe6 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java
@@ -27,7 +27,7 @@ import java.util.HashSet;
import java.util.Set;
/**
- * Entry point event into the Catch system. This object is nearly immutable, the only mutable portion
+ * Entry point event into the Exception Control system. This object is nearly immutable, the only mutable portion
* is the handled flag.
*/
@SuppressWarnings("CdiManagedBeanInconsistencyInspection")
@@ -84,9 +84,10 @@ public class ExceptionToCatchEvent implements Serializable
}
/**
- * Test to see if the exception has been handled via Solder Catch.
+ * Test to see if the exception has already been processed by an
+ * {@link org.apache.deltaspike.core.api.exception.control.ExceptionHandler}.
*
- * @return test if the exception has been through Solder Catch handling.
+ * @return true if the exception has already been processed by a handler; false otherwise
*/
public boolean isHandled()
{