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}