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/master Commit: c14ac214d37a2f60f304a2429002a919dcf06679 Parents: b0e96b7 Author: Matt Sicker <[email protected]> Authored: Fri Aug 29 22:41:38 2014 -0500 Committer: Matt Sicker <[email protected]> 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) {
