001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Portions Copyright 2011-2015 ForgeRock AS
025 */
026package org.opends.server.types;
027
028import org.forgerock.util.Reject;
029
030
031
032/**
033 * An additional log item for an operation which may be processed in the access
034 * log.
035 * <p>
036 * Log items comprise of a source class, a key, and an optional value. If no
037 * value is present then only the key will be displayed in the log, otherwise
038 * both the key and value will usually be displayed using the format
039 * {@code key=value}. Log item values are {@code Object} instances whose string
040 * representation will be derived using the object's {@code toString()} method.
041 * <p>
042 * Log implementations may use the source class and/or key in order to filter
043 * out unwanted log items.
044 */
045public final class AdditionalLogItem
046{
047  /**
048   * Creates a new additional log item using the provided source and key, but no
049   * value.
050   *
051   * @param source
052   *          The class which generated the additional log item.
053   * @param key
054   *          The log item key.
055   * @return The new additional log item.
056   */
057  public static AdditionalLogItem keyOnly(final Class<?> source,
058      final String key)
059  {
060    Reject.ifNull(source, key);
061    return new AdditionalLogItem(source, key, null, false);
062  }
063
064
065
066  /**
067   * Creates a new additional log item using the provided source, key, and
068   * value. The value will be surrounded by quotes when serialized as a string.
069   *
070   * @param source
071   *          The class which generated the additional log item.
072   * @param key
073   *          The log item key.
074   * @param value
075   *          The log item value.
076   * @return The new additional log item.
077   */
078  public static AdditionalLogItem quotedKeyValue(final Class<?> source,
079      final String key, final Object value)
080  {
081    Reject.ifNull(source, key, value);
082    return new AdditionalLogItem(source, key, value, true);
083  }
084
085
086
087  /**
088   * Creates a new additional log item using the provided source, key, and
089   * value. The value will not be surrounded by quotes when serialized as a
090   * string.
091   *
092   * @param source
093   *          The class which generated the additional log item.
094   * @param key
095   *          The log item key.
096   * @param value
097   *          The log item value.
098   * @return The new additional log item.
099   */
100  public static AdditionalLogItem unquotedKeyValue(final Class<?> source,
101      final String key, final Object value)
102  {
103    Reject.ifNull(source, key, value);
104    return new AdditionalLogItem(source, key, value, false);
105  }
106
107
108
109  private final Class<?> source;
110
111  private final String key;
112
113  private final Object value;
114
115  private final boolean isQuoted;
116
117
118
119  /**
120   * Creates a new additional log item.
121   *
122   * @param source
123   *          The class which generated the additional log item.
124   * @param key
125   *          The log item key.
126   * @param value
127   *          The log item value.
128   * @param isQuoted
129   *          {@code true} if this item's value should be surrounded by quotes
130   *          during serialization.
131   */
132  private AdditionalLogItem(final Class<?> source, final String key,
133      final Object value, final boolean isQuoted)
134  {
135    this.source = source;
136    this.key = key;
137    this.value = value;
138    this.isQuoted = isQuoted;
139  }
140
141
142
143  /**
144   * Returns the log item key.
145   *
146   * @return The log item key.
147   */
148  public String getKey()
149  {
150    return key;
151  }
152
153
154
155  /**
156   * Returns the class which generated the additional log item.
157   *
158   * @return The class which generated the additional log item.
159   */
160  public Class<?> getSource()
161  {
162    return source;
163  }
164
165
166
167  /**
168   * Returns the log item value, or {@code null} if this log item does not have
169   * a value.
170   *
171   * @return The log item value, or {@code null} if this log item does not have
172   *         a value.
173   */
174  public Object getValue()
175  {
176    return value;
177  }
178
179
180
181  /**
182   * Returns {@code true} if this item's value should be surrounded by quotes
183   * during serialization.
184   *
185   * @return {@code true} if this item's value should be surrounded by quotes
186   *         during serialization.
187   */
188  public boolean isQuoted()
189  {
190    return isQuoted;
191  }
192
193
194
195  /** {@inheritDoc} */
196  @Override
197  public String toString()
198  {
199    if (value == null)
200    {
201      return key;
202    }
203    final StringBuilder builder = new StringBuilder(key.length() + 16);
204    toString(builder);
205    return builder.toString();
206  }
207
208
209
210  /**
211   * Appends the string representation of this additional log item to the
212   * provided string builder.
213   *
214   * @param builder
215   *          The string builder.
216   * @return A reference to the updated string builder.
217   */
218  public StringBuilder toString(final StringBuilder builder)
219  {
220    builder.append(key);
221    if (value != null)
222    {
223      builder.append('=');
224      if (isQuoted)
225      {
226        builder.append('\'');
227      }
228      builder.append(value);
229      if (isQuoted)
230      {
231        builder.append('\'');
232      }
233    }
234    return builder;
235  }
236
237}