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:27 UTC
[2/3] deltaspike git commit: DELTASPIKE-767 Comprehensive review of
javadoc: core/api
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();
}