You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ma...@apache.org on 2014/08/31 00:20:09 UTC
[42/50] [abbrv] git commit: Fix javadoc markup and typos.
Fix javadoc markup and typos.
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/c14ac214
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/c14ac214
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/c14ac214
Branch: refs/heads/messaging-module
Commit: c14ac214d37a2f60f304a2429002a919dcf06679
Parents: b0e96b7
Author: Matt Sicker <ma...@apache.org>
Authored: Fri Aug 29 22:41:38 2014 -0500
Committer: Matt Sicker <ma...@apache.org>
Committed: Fri Aug 29 22:41:38 2014 -0500
----------------------------------------------------------------------
.../log4j/core/lookup/StrSubstitutor.java | 63 +++++++++++++++++---
.../log4j/core/lookup/StructuredDataLookup.java | 6 +-
2 files changed, 57 insertions(+), 12 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c14ac214/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StrSubstitutor.java
----------------------------------------------------------------------
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StrSubstitutor.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StrSubstitutor.java
index 6055ebb..1c6289a 100644
--- a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StrSubstitutor.java
+++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StrSubstitutor.java
@@ -33,11 +33,14 @@ import org.apache.logging.log4j.util.Strings;
* This class takes a piece of text and substitutes all the variables within it.
* The default definition of a variable is <code>${variableName}</code>.
* The prefix and suffix can be changed via constructors and set methods.
+ * </p>
* <p>
* Variable values are typically resolved from a map, but could also be resolved
* from system properties, or by supplying a custom variable resolver.
+ * </p>
* <p>
* The simplest example is to use this class to replace Java System properties. For example:
+ * </p>
* <pre>
* StrSubstitutor.replaceSystemProperties(
* "You are running with java.version = ${java.version} and os.name = ${os.name}.");
@@ -50,6 +53,7 @@ import org.apache.logging.log4j.util.Strings;
* method can be called passing in the source text for interpolation. In the returned
* text all variable references (as long as their values are known) will be resolved.
* The following example demonstrates this:
+ * </p>
* <pre>
* Map valuesMap = HashMap();
* valuesMap.put("animal", "quick brown fox");
@@ -58,7 +62,7 @@ import org.apache.logging.log4j.util.Strings;
* StrSubstitutor sub = new StrSubstitutor(valuesMap);
* String resolvedString = sub.replace(templateString);
* </pre>
- * yielding:
+ * <p>yielding:</p>
* <pre>
* The quick brown fox jumped over the lazy dog.
* </pre>
@@ -69,7 +73,8 @@ import org.apache.logging.log4j.util.Strings;
* as in bash and other *nix shells, as those are arguably where the default ${} delimiter set originated.
* The variable default value delimiter can be manually set by calling {@link #setValueDelimiterMatcher(StrMatcher)},
* {@link #setValueDelimiter(char)} or {@link #setValueDelimiter(String)}.
- * The following shows an example with varialbe default value settings:
+ * The following shows an example with variable default value settings:
+ * </p>
* <pre>
* Map valuesMap = HashMap();
* valuesMap.put("animal", "quick brown fox");
@@ -78,7 +83,7 @@ import org.apache.logging.log4j.util.Strings;
* StrSubstitutor sub = new StrSubstitutor(valuesMap);
* String resolvedString = sub.replace(templateString);
* </pre>
- * yielding:
+ * <p>yielding:</p>
* <pre>
* The quick brown fox jumped over the lazy dog. 1234567890.
* </pre>
@@ -87,40 +92,49 @@ import org.apache.logging.log4j.util.Strings;
* cover the most common use cases. These methods can be used without the need of
* manually creating an instance. However if multiple replace operations are to be
* performed, creating and reusing an instance of this class will be more efficient.
+ * </p>
* <p>
* Variable replacement works in a recursive way. Thus, if a variable value contains
* a variable then that variable will also be replaced. Cyclic replacements are
* detected and will cause an exception to be thrown.
+ * </p>
* <p>
* Sometimes the interpolation's result must contain a variable prefix. As an example
* take the following source text:
+ * </p>
* <pre>
* The variable ${${name}} must be used.
* </pre>
+ * <p>
* Here only the variable's name referred to in the text should be replaced resulting
* in the text (assuming that the value of the <code>name</code> variable is <code>x</code>):
+ * </p>
* <pre>
* The variable ${x} must be used.
* </pre>
+ * <p>
* To achieve this effect there are two possibilities: Either set a different prefix
* and suffix for variables which do not conflict with the result text you want to
* produce. The other possibility is to use the escape character, by default '$'.
* If this character is placed before a variable reference, this reference is ignored
* and won't be replaced. For example:
+ * </p>
* <pre>
* The variable $${${name}} must be used.
* </pre>
* <p>
* In some complex scenarios you might even want to perform substitution in the
* names of variables, for instance
+ * </p>
* <pre>
* ${jre-${java.specification.version}}
* </pre>
+ * <p>
* <code>StrSubstitutor</code> supports this recursive substitution in variable
* names, but it has to be enabled explicitly by setting the
* {@link #setEnableSubstitutionInVariables(boolean) enableSubstitutionInVariables}
* property to <b>true</b>.
- *
+ * </p>
*/
public class StrSubstitutor {
@@ -222,7 +236,7 @@ public class StrSubstitutor {
* @param valueDelimiter the variable default value delimiter, may be null
* @throws IllegalArgumentException if the prefix or suffix is null
*/
- public StrSubstitutor(final Map<String, String> valueMap, final String prefix, final String suffix,
+ public StrSubstitutor(final Map<String, String> valueMap, final String prefix, final String suffix,
final char escape, final String valueDelimiter) {
this(new MapLookup(valueMap), prefix, suffix, escape, valueDelimiter);
}
@@ -394,6 +408,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the string will be processed.
* The rest of the string is not processed, and is not returned.
+ * </p>
*
* @param source the string to replace in, null returns null
* @param offset the start offset within the array, must be valid
@@ -410,6 +425,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the string will be processed.
* The rest of the string is not processed, and is not returned.
+ * </p>
*
* @param event the current LogEvent, if one exists.
* @param source the string to replace in, null returns null
@@ -467,6 +483,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the array will be processed.
* The rest of the array is not processed, and is not returned.
+ * </p>
*
* @param source the character array to replace in, not altered, null returns null
* @param offset the start offset within the array, must be valid
@@ -484,6 +501,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the array will be processed.
* The rest of the array is not processed, and is not returned.
+ * </p>
*
* @param event the current LogEvent, if one exists.
* @param source the character array to replace in, not altered, null returns null
@@ -539,6 +557,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the buffer will be processed.
* The rest of the buffer is not processed, and is not returned.
+ * </p>
*
* @param source the buffer to use as a template, not changed, null returns null
* @param offset the start offset within the array, must be valid
@@ -556,6 +575,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the buffer will be processed.
* The rest of the buffer is not processed, and is not returned.
+ * </p>
*
* @param event the current LogEvent, if one exists.
* @param source the buffer to use as a template, not changed, null returns null
@@ -610,6 +630,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the builder will be processed.
* The rest of the builder is not processed, and is not returned.
+ * </p>
*
* @param source the builder to use as a template, not changed, null returns null
* @param offset the start offset within the array, must be valid
@@ -627,6 +648,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the builder will be processed.
* The rest of the builder is not processed, and is not returned.
+ * </p>
*
* @param event the current LogEvent, if one exists.
* @param source the builder to use as a template, not changed, null returns null
@@ -697,6 +719,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the buffer will be processed.
* The rest of the buffer is not processed, but it is not deleted.
+ * </p>
*
* @param source the buffer to replace in, updated, null returns zero
* @param offset the start offset within the array, must be valid
@@ -714,6 +737,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the buffer will be processed.
* The rest of the buffer is not processed, but it is not deleted.
+ * </p>
*
* @param event the current LogEvent, if one exists.
* @param source the buffer to replace in, updated, null returns zero
@@ -766,6 +790,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the builder will be processed.
* The rest of the builder is not processed, but it is not deleted.
+ * </p>
*
* @param source the builder to replace in, null returns zero
* @param offset the start offset within the array, must be valid
@@ -782,6 +807,7 @@ public class StrSubstitutor {
* <p>
* Only the specified portion of the builder will be processed.
* The rest of the builder is not processed, but it is not deleted.
+ * </p>
*
* @param event the current LogEvent, if one is present.
* @param source the builder to replace in, null returns zero
@@ -802,9 +828,11 @@ public class StrSubstitutor {
* <p>
* Most users of this class do not need to call this method. This method will
* be called automatically by another (public) method.
+ * </p>
* <p>
* Writers of subclasses can override this method if they need access to
* the substitution process at the start or end.
+ * </p>
*
* @param event The current LogEvent, if there is one.
* @param buf the string builder to substitute into, not null
@@ -986,11 +1014,13 @@ public class StrSubstitutor {
* <p>
* Most users of this class do not need to call this method. This method is
* called automatically by the substitution process.
+ * </p>
* <p>
* Writers of subclasses can override this method if they need to alter
* how each substitution occurs. The method is passed the variable's name
* and must return the corresponding value. This implementation uses the
* {@link #getVariableResolver()} with the variable's name as the key.
+ * </p>
*
* @param event The LogEvent, if there is one.
* @param variableName the name of the variable, not null
@@ -1038,6 +1068,7 @@ public class StrSubstitutor {
* The variable prefix is the character or characters that identify the
* start of a variable. This prefix is expressed in terms of a matcher
* allowing advanced prefix matches.
+ * </p>
*
* @return the prefix matcher in use
*/
@@ -1051,6 +1082,7 @@ public class StrSubstitutor {
* The variable prefix is the character or characters that identify the
* start of a variable. This prefix is expressed in terms of a matcher
* allowing advanced prefix matches.
+ * </p>
*
* @param prefixMatcher the prefix matcher to use, null ignored
* @return this, to enable chaining
@@ -1070,6 +1102,7 @@ public class StrSubstitutor {
* The variable prefix is the character or characters that identify the
* start of a variable. This method allows a single character prefix to
* be easily set.
+ * </p>
*
* @param prefix the prefix character to use
* @return this, to enable chaining
@@ -1083,6 +1116,7 @@ public class StrSubstitutor {
* <p>
* The variable prefix is the character or characters that identify the
* start of a variable. This method allows a string prefix to be easily set.
+ * </p>
*
* @param prefix the prefix for variables, not null
* @return this, to enable chaining
@@ -1103,6 +1137,7 @@ public class StrSubstitutor {
* The variable suffix is the character or characters that identify the
* end of a variable. This suffix is expressed in terms of a matcher
* allowing advanced suffix matches.
+ * </p>
*
* @return the suffix matcher in use
*/
@@ -1116,6 +1151,7 @@ public class StrSubstitutor {
* The variable suffix is the character or characters that identify the
* end of a variable. This suffix is expressed in terms of a matcher
* allowing advanced suffix matches.
+ * </p>
*
* @param suffixMatcher the suffix matcher to use, null ignored
* @return this, to enable chaining
@@ -1135,6 +1171,7 @@ public class StrSubstitutor {
* The variable suffix is the character or characters that identify the
* end of a variable. This method allows a single character suffix to
* be easily set.
+ * </p>
*
* @param suffix the suffix character to use
* @return this, to enable chaining
@@ -1148,6 +1185,7 @@ public class StrSubstitutor {
* <p>
* The variable suffix is the character or characters that identify the
* end of a variable. This method allows a string suffix to be easily set.
+ * </p>
*
* @param suffix the suffix for variables, not null
* @return this, to enable chaining
@@ -1165,11 +1203,13 @@ public class StrSubstitutor {
/**
* Gets the variable default value delimiter matcher currently in use.
* <p>
- * The variable default value delimiter is the characer or characters that delimite the
+ * The variable default value delimiter is the character or characters that delimit the
* variable name and the variable default value. This delimiter is expressed in terms of a matcher
* allowing advanced variable default value delimiter matches.
+ * </p>
* <p>
* If it returns null, then the variable default value resolution is disabled.
+ * </p>
*
* @return the variable default value delimiter matcher in use, may be null
*/
@@ -1180,12 +1220,14 @@ public class StrSubstitutor {
/**
* Sets the variable default value delimiter matcher to use.
* <p>
- * The variable default value delimiter is the characer or characters that delimite the
+ * The variable default value delimiter is the character or characters that delimit the
* variable name and the variable default value. This delimiter is expressed in terms of a matcher
* allowing advanced variable default value delimiter matches.
+ * </p>
* <p>
* If the <code>valueDelimiterMatcher</code> is null, then the variable default value resolution
* becomes disabled.
+ * </p>
*
* @param valueDelimiterMatcher variable default value delimiter matcher to use, may be null
* @return this, to enable chaining
@@ -1198,9 +1240,10 @@ public class StrSubstitutor {
/**
* Sets the variable default value delimiter to use.
* <p>
- * The variable default value delimiter is the characer or characters that delimite the
+ * The variable default value delimiter is the character or characters that delimit the
* variable name and the variable default value. This method allows a single character
* variable default value delimiter to be easily set.
+ * </p>
*
* @param valueDelimiter the variable default value delimiter character to use
* @return this, to enable chaining
@@ -1212,12 +1255,14 @@ public class StrSubstitutor {
/**
* Sets the variable default value delimiter to use.
* <p>
- * The variable default value delimiter is the characer or characters that delimite the
+ * The variable default value delimiter is the character or characters that delimit the
* variable name and the variable default value. This method allows a string
* variable default value delimiter to be easily set.
+ * </p>
* <p>
* If the <code>valueDelimiter</code> is null or empty string, then the variable default
* value resolution becomes disabled.
+ * </p>
*
* @param valueDelimiter the variable default value delimiter string to use, may be null or empty
* @return this, to enable chaining
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/c14ac214/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StructuredDataLookup.java
----------------------------------------------------------------------
diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StructuredDataLookup.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StructuredDataLookup.java
index 987ff3d..68441cb 100644
--- a/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StructuredDataLookup.java
+++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/lookup/StructuredDataLookup.java
@@ -21,15 +21,15 @@ import org.apache.logging.log4j.core.config.plugins.Plugin;
import org.apache.logging.log4j.message.StructuredDataMessage;
/**
- * Looks up keys from system properties.
+ * Looks up keys from {@link org.apache.logging.log4j.message.StructuredDataMessage} log messages.
*/
@Plugin(name = "sd", category = "Lookup")
public class StructuredDataLookup implements StrLookup {
/**
- * Looks up the value for the key.
+ * Returns {@code null}. This Lookup plugin does not make sense outside the context of a LogEvent.
* @param key the key to be looked up, may be null
- * @return The value for the key.
+ * @return {@code null}
*/
@Override
public String lookup(final String key) {