commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scolebou...@apache.org
Subject svn commit: r1143746 - in /commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception: ContextedException.java ContextedRuntimeException.java DefaultExceptionContext.java ExceptionContext.java
Date Thu, 07 Jul 2011 10:07:06 GMT
Author: scolebourne
Date: Thu Jul  7 10:07:06 2011
New Revision: 1143746

URL: http://svn.apache.org/viewvc?rev=1143746&view=rev
Log:
Javdoc and minor tweaks to contexted exception

Modified:
    commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedException.java
    commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedRuntimeException.java
    commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/DefaultExceptionContext.java
    commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ExceptionContext.java

Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedException.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedException.java?rev=1143746&r1=1143745&r2=1143746&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedException.java
(original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedException.java
Thu Jul  7 10:07:06 2011
@@ -23,8 +23,7 @@ import org.apache.commons.lang3.tuple.Pa
 
 /**
  * <p>
- * An exception that provides an easy and safe way to add contextual
- * information.
+ * An exception that provides an easy and safe way to add contextual information.
  * </p><p>
  * An exception trace itself is often insufficient to provide rapid diagnosis of the issue.
  * Frequently what is needed is a select few pieces of local contextual data.
@@ -138,19 +137,18 @@ public class ContextedException extends 
     }
 
     //-----------------------------------------------------------------------
-
     /**
-     * Adds information helpful to a developer in diagnosing and correcting
-     * the problem.  For the information to be meaningful, the value passed
-     * should have a reasonable toString() implementation.  Different values
-     * can be added with the same label multiple times. 
+     * Adds information helpful to a developer in diagnosing and correcting the problem.
+     * For the information to be meaningful, the value passed should have a reasonable
+     * toString() implementation.
+     * Different values can be added with the same label multiple times.
      * <p>
      * Note: This exception is only serializable if the object added is serializable.
      * </p>
      * 
      * @param label  a textual label associated with information, {@code null} not recommended
      * @param value  information needed to understand exception, may be {@code null}
-     * @return this, for method chaining
+     * @return {@code this}, for method chaining, not {@code null}
      */
     public ContextedException addContextValue(String label, Object value) {        
         exceptionContext.addContextValue(label, value);
@@ -158,17 +156,17 @@ public class ContextedException extends 
     }
 
     /**
-     * Adds information helpful to a developer in diagnosing and correcting
-     * the problem.  For the information to be meaningful, the value passed
-     * should have a reasonable toString() implementation.  Different values
-     * can be added with the same label multiple times. 
+     * Adds information helpful to a developer in diagnosing and correcting the problem.
+     * For the information to be meaningful, the value passed should have a reasonable
+     * toString() implementation.
+     * Different values can be added with the same label multiple times.
      * <p>
      * Note: This exception is only serializable if the object added as value is serializable.
      * </p>
      * 
-     * @param pair a pair of textual label and information
+     * @param pair  a pair of textual label and information, not {@code null}
+     * @return {@code this}, for method chaining, not {@code null}
      * @throws NullPointerException if {@code pair} is {@code null}
-     * @return this, for method chaining
      */
     public ContextedException addContextValue(Pair<String, Object> pair) {
         this.exceptionContext.addContextValue(pair);
@@ -176,35 +174,35 @@ public class ContextedException extends 
     }
 
     /**
-     * Set information helpful to a developer in diagnosing and correcting
-     * the problem.  For the information to be meaningful, the value passed
-     * should have a reasonable toString() implementation.  Existing values
-     * with the same labels are removed before the new one is added.
+     * Sets information helpful to a developer in diagnosing and correcting the problem.
+     * For the information to be meaningful, the value passed should have a reasonable
+     * toString() implementation.
+     * Any existing values with the same labels are removed before the new one is added.
      * <p>
      * Note: This exception is only serializable if the object added as value is serializable.
      * </p>
      * 
      * @param label  a textual label associated with information, {@code null} not recommended
      * @param value  information needed to understand exception, may be {@code null}
-     * @return this, for method chaining
+     * @return {@code this}, for method chaining, not {@code null}
      */
     public ContextedException setContextValue(String label, Object value) {        
         exceptionContext.setContextValue(label, value);
         return this;
     }
-    
+
     /**
-     * Set information helpful to a developer in diagnosing and correcting
-     * the problem.  For the information to be meaningful, the value passed
-     * should have a reasonable toString() implementation.  Existing values
-     * with the same labels are removed before the new one is added.
+     * Sets information helpful to a developer in diagnosing and correcting the problem.
+     * For the information to be meaningful, the value passed should have a reasonable
+     * toString() implementation.
+     * Any existing values with the same labels are removed before the new one is added.
      * <p>
      * Note: This exception is only serializable if the object added as value is serializable.
      * </p>
      * 
-     * @param pair a pair of textual label and information
+     * @param pair  a pair of textual label and information, not {@code null}
+     * @return {@code this}, for method chaining, not {@code null}
      * @throws NullPointerException if {@code pair} is {@code null}
-     * @return this, for method chaining
      */
     public ContextedException setContextValue(Pair<String, Object> pair) {
         this.exceptionContext.setContextValue(pair);
@@ -256,4 +254,5 @@ public class ContextedException extends 
     public String getFormattedExceptionMessage(String baseMessage) {
         return exceptionContext.getFormattedExceptionMessage(baseMessage);
     }
+
 }

Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedRuntimeException.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedRuntimeException.java?rev=1143746&r1=1143745&r2=1143746&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedRuntimeException.java
(original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ContextedRuntimeException.java
Thu Jul  7 10:07:06 2011
@@ -33,7 +33,7 @@ import org.apache.commons.lang3.tuple.Pa
  * list of context label-value pairs. This additional information is automatically included
in
  * the message and printed stack trace.
  * </p><p>
- * An checked version of this exception is provided by ContextedException.
+ * A checked version of this exception is provided by ContextedException.
  * </p>
  * <p>
  * To use this class write code as follows:
@@ -123,9 +123,6 @@ public class ContextedRuntimeException e
 
     /**
      * Instantiates ContextedRuntimeException with cause, message, and ExceptionContext.
-     * <p>
-     * Note: This exception is only serializable if the object added is serializable.
-     * </p>
      * 
      * @param message  the exception message, may be null
      * @param cause  the underlying cause of the exception, may be null
@@ -140,19 +137,18 @@ public class ContextedRuntimeException e
     }
 
     //-----------------------------------------------------------------------
-
     /**
-     * Adds information helpful to a developer in diagnosing and correcting
-     * the problem.  For the information to be meaningful, the value passed
-     * should have a reasonable toString() implementation.  Different values
-     * can be added with the same label multiple times. 
+     * Adds information helpful to a developer in diagnosing and correcting the problem.
+     * For the information to be meaningful, the value passed should have a reasonable
+     * toString() implementation.
+     * Different values can be added with the same label multiple times.
      * <p>
      * Note: This exception is only serializable if the object added is serializable.
      * </p>
      * 
      * @param label  a textual label associated with information, {@code null} not recommended
      * @param value  information needed to understand exception, may be {@code null}
-     * @return this, for method chaining
+     * @return {@code this}, for method chaining, not {@code null}
      */
     public ContextedRuntimeException addContextValue(String label, Object value) {      
 
         exceptionContext.addContextValue(label, value);
@@ -160,17 +156,17 @@ public class ContextedRuntimeException e
     }
 
     /**
-     * Adds information helpful to a developer in diagnosing and correcting
-     * the problem.  For the information to be meaningful, the value passed
-     * should have a reasonable toString() implementation.  Different values
-     * can be added with the same label multiple times. 
+     * Adds information helpful to a developer in diagnosing and correcting the problem.
+     * For the information to be meaningful, the value passed should have a reasonable
+     * toString() implementation.
+     * Different values can be added with the same label multiple times.
      * <p>
      * Note: This exception is only serializable if the object added as value is serializable.
      * </p>
      * 
-     * @param pair a pair of textual label and information
+     * @param pair  a pair of textual label and information, not {@code null}
+     * @return {@code this}, for method chaining, not {@code null}
      * @throws NullPointerException if {@code pair} is {@code null}
-     * @return this, for method chaining
      */
     public ContextedRuntimeException addContextValue(Pair<String, Object> pair) {
         this.exceptionContext.addContextValue(pair);
@@ -178,35 +174,35 @@ public class ContextedRuntimeException e
     }
 
     /**
-     * Set information helpful to a developer in diagnosing and correcting
-     * the problem.  For the information to be meaningful, the value passed
-     * should have a reasonable toString() implementation.  Existing values
-     * with the same labels are removed before the new one is added.
+     * Sets information helpful to a developer in diagnosing and correcting the problem.
+     * For the information to be meaningful, the value passed should have a reasonable
+     * toString() implementation.
+     * Any existing values with the same labels are removed before the new one is added.
      * <p>
      * Note: This exception is only serializable if the object added as value is serializable.
      * </p>
      * 
      * @param label  a textual label associated with information, {@code null} not recommended
      * @param value  information needed to understand exception, may be {@code null}
-     * @return this, for method chaining
+     * @return {@code this}, for method chaining, not {@code null}
      */
     public ContextedRuntimeException setContextValue(String label, Object value) {      
 
         exceptionContext.setContextValue(label, value);
         return this;
     }
-    
+
     /**
-     * Set information helpful to a developer in diagnosing and correcting
-     * the problem.  For the information to be meaningful, the value passed
-     * should have a reasonable toString() implementation.  Existing values
-     * with the same labels are removed before the new one is added.
+     * Sets information helpful to a developer in diagnosing and correcting the problem.
+     * For the information to be meaningful, the value passed should have a reasonable
+     * toString() implementation.
+     * Any existing values with the same labels are removed before the new one is added.
      * <p>
      * Note: This exception is only serializable if the object added as value is serializable.
      * </p>
      * 
-     * @param pair a pair of textual label and information
+     * @param pair  a pair of textual label and information, not {@code null}
+     * @return {@code this}, for method chaining, not {@code null}
      * @throws NullPointerException if {@code pair} is {@code null}
-     * @return this, for method chaining
      */
     public ContextedRuntimeException setContextValue(Pair<String, Object> pair) {
         this.exceptionContext.setContextValue(pair);
@@ -258,4 +254,5 @@ public class ContextedRuntimeException e
     public String getFormattedExceptionMessage(String baseMessage) {
         return exceptionContext.getFormattedExceptionMessage(baseMessage);
     }
+
 }

Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/DefaultExceptionContext.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/DefaultExceptionContext.java?rev=1143746&r1=1143745&r2=1143746&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/DefaultExceptionContext.java
(original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/DefaultExceptionContext.java
Thu Jul  7 10:07:06 2011
@@ -39,6 +39,7 @@ public class DefaultExceptionContext imp
 
     /** The serialization version. */
     private static final long serialVersionUID = 20110706L;
+
     /** The list storing the label-data pairs. */
     private List<Pair<String, Object>> contextValues = new ArrayList<Pair<String,Object>>();
 
@@ -165,4 +166,5 @@ public class DefaultExceptionContext imp
         }
         return buffer.toString();
     }
+
 }

Modified: commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ExceptionContext.java
URL: http://svn.apache.org/viewvc/commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ExceptionContext.java?rev=1143746&r1=1143745&r2=1143746&view=diff
==============================================================================
--- commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ExceptionContext.java
(original)
+++ commons/proper/lang/trunk/src/main/java/org/apache/commons/lang3/exception/ExceptionContext.java
Thu Jul  7 10:07:06 2011
@@ -44,7 +44,7 @@ public interface ExceptionContext {
      * 
      * @param label  the label of the item to add, {@code null} not recommended
      * @param value  the value of item to add, may be {@code null}
-     * @return context itself to allow method chaining
+     * @return {@code this}, for method chaining, not {@code null}
      */
     public ExceptionContext addContextValue(String label, Object value);
 
@@ -55,14 +55,14 @@ public interface ExceptionContext {
      * existing pair with the same label.
      * </p>
      * 
-     * @param pair  the label-value pair to add
-     * @return context itself to allow method chaining
+     * @param pair  the label-value pair to add, not {@code null}
+     * @return {@code this}, for method chaining, not {@code null}
      * @throws NullPointerException if pair is {@code null}
      */
     public ExceptionContext addContextValue(Pair<String, Object> pair);
 
     /**
-     * Sets a contextual label-value pair of this context.
+     * Sets a contextual label-value pair into this context.
      * <p>
      * The pair will be added normally, but any existing label-value pair with
      * the same label is removed from the context.
@@ -70,25 +70,25 @@ public interface ExceptionContext {
      * 
      * @param label  the label of the item to add, {@code null} not recommended
      * @param value  the value of item to add, may be {@code null}
-     * @return context itself to allow method chaining
+     * @return {@code this}, for method chaining, not {@code null}
      */
     public ExceptionContext setContextValue(String label, Object value);
 
     /**
-     * Sets a contextual label-value pair of this context.
+     * Sets a contextual label-value pair into this context.
      * <p>
      * The pair will be added normally, but any existing label-value pair with
      * the same label is removed from the context.
      * </p>
      * 
-     * @param pair  the label-value pair to add
-     * @return context itself to allow method chaining
+     * @param pair  the label-value pair to add, not {@code null}
+     * @return {@code this}, for method chaining, not {@code null}
      * @throws NullPointerException if pair is {@code null}
      */
     public ExceptionContext setContextValue(Pair<String, Object> pair);
 
     /**
-     * Retrieves contextual data values associated with the label.
+     * Retrieves all the contextual data values associated with the label.
      * 
      * @param label  the label to get the contextual values for, may be {@code null}
      * @return the contextual values associated with the label, never {@code null}
@@ -104,25 +104,25 @@ public interface ExceptionContext {
     public Object getFirstContextValue(String label);
 
     /**
-     * Retrieves the labels defined in the contextual data.
+     * Retrieves the full set of labels defined in the contextual data.
      * 
-     * @return the set of labels, never {@code null}
+     * @return the set of labels, not {@code null}
      */
     public Set<String> getContextLabels();
 
     /**
-     * Retrieves the label-value pairs defined in the contextual data.
+     * Retrieves the full list of label-value pairs defined in the contextual data.
      * 
-     * @return the list of pairs, never {@code null}
+     * @return the list of pairs, not {@code null}
      */
     public List<Pair<String, Object>> getContextEntries();
 
     /**
-     * Implementors provide the given base message with context label/value item 
-     * information appended.
+     * Gets the contextualized error message based on a base message.
+     * This will add the context label-value pairs to the message.
      * 
      * @param baseMessage  the base exception message <b>without</b> context
information appended
-     * @return the exception message <b>with</b> context information appended,
never {@code null}
+     * @return the exception message <b>with</b> context information appended,
not {@code null}
      */
     public String getFormattedExceptionMessage(String baseMessage);
 



Mime
View raw message