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);
