git commit: DELTASPIKE-232 document Serializable behaviour

[st...@apache.org]

Updated Branches:
  refs/heads/master bf6f4f079 -> 66127d9ac


DELTASPIKE-232 document Serializable behaviour


Project: http://git-wip-us.apache.org/repos/asf/incubator-deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-deltaspike/commit/66127d9a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-deltaspike/tree/66127d9a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-deltaspike/diff/66127d9a

Branch: refs/heads/master
Commit: 66127d9ac593cd037d867466e7fc5970efa28b49
Parents: bf6f4f0
Author: Mark Struberg <st...@apache.org>
Authored: Sun Jul 8 13:33:09 2012 +0200
Committer: Mark Struberg <st...@apache.org>
Committed: Sun Jul 8 13:33:09 2012 +0200

----------------------------------------------------------------------
 .../deltaspike/core/api/message/Message.java       |    6 ++-
 .../core/api/message/annotation/MessageBundle.java |   33 +++++++++++----
 2 files changed, 29 insertions(+), 10 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-deltaspike/blob/66127d9a/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 885b53a..0478573 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
@@ -21,7 +21,11 @@ package org.apache.deltaspike.core.api.message;
 import java.io.Serializable;
 
 /**
- * Basic interface for all message-types
+ * <p>Basic interface for all messages.</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 ist determined by the used {@link MessageContext}.</p>
  */
 public interface Message extends Serializable
 {

http://git-wip-us.apache.org/repos/asf/incubator-deltaspike/blob/66127d9a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/annotation/MessageBundle.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/annotation/MessageBundle.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/annotation/MessageBundle.java
index d4c86ef..080de6b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/annotation/MessageBundle.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/annotation/MessageBundle.java
@@ -26,24 +26,39 @@ 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.
- * Each method on such an interface will form a type-safe message. The message lookup key
- * (resource bundle key) can either be defined by annotating those methods
- * with &#064;{@link MessageTemplate}) or by convention. if no &#064;{@link MessageTemplate}
- * annotation is used on a method, it's name will be used as resource key.</p>
+ * <p>Marker annotation for a message-bundle interface which provides type-safe messages.</p>
  *
  * <p>This annotation must only be used on interfaces.
  * If this annotation gets used on a concrete class, a deployment error results!</p>
  *
- * <p>The {@link java.util.ResourceBundle} or other resource lookup source is
+ * <h3>Type-safe Messages</h3>
+ * <p>Each method on an interface annotated with <code>&#064;MessageBundle</code>
+ * will form a type-safe message. The message lookup key
+ * (resource bundle key) can either be defined by annotating those methods
+ * with &#064;{@link MessageTemplate}) or by convention. if no &#064;{@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>
+ * 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
- * &#064;MessageBundle will automatically be registered as additional <code>messageSource</code>!</p>
+ * &#064;MessageBundle will automatically be registered as additional
+ * <code>messageSource</code> for those messages.</p>
+ *
  *
- * <p>Can be combined with {@link MessageContextConfig} to customize the
- * message-resolution and processing.</p>
+ * <p><code>&#064;MessageBundle</code> can be combined with {@link MessageContextConfig}
+ * to further customize the message-resolution and processing process.</p>
  */
 @Target({ TYPE })
 @Retention(RUNTIME)