001/* 002 * Copyright 2017-2018 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2017-2018 Ping Identity Corporation 007 * 008 * This program is free software; you can redistribute it and/or modify 009 * it under the terms of the GNU General Public License (GPLv2 only) 010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 011 * as published by the Free Software Foundation. 012 * 013 * This program is distributed in the hope that it will be useful, 014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 016 * GNU General Public License for more details. 017 * 018 * You should have received a copy of the GNU General Public License 019 * along with this program; if not, see <http://www.gnu.org/licenses>. 020 */ 021package com.unboundid.ldap.sdk.unboundidds.tools; 022 023 024 025import java.io.File; 026import java.io.PrintStream; 027import java.util.Collections; 028import java.util.Iterator; 029import java.util.Set; 030import java.util.UUID; 031 032import com.unboundid.util.NotMutable; 033import com.unboundid.util.NullOutputStream; 034import com.unboundid.util.ThreadSafety; 035import com.unboundid.util.ThreadSafetyLevel; 036 037 038 039/** 040 * This class represents a data structure that contains information that should 041 * be used when logging launch and completion messages for a tool invocation. 042 * <BR> 043 * <BLOCKQUOTE> 044 * <B>NOTE:</B> This class, and other classes within the 045 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 046 * supported for use against Ping Identity, UnboundID, and Alcatel-Lucent 8661 047 * server products. These classes provide support for proprietary 048 * functionality or for external specifications that are not considered stable 049 * or mature enough to be guaranteed to work in an interoperable way with 050 * other types of LDAP servers. 051 * </BLOCKQUOTE> 052 */ 053@NotMutable() 054@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 055public final class ToolInvocationLogDetails 056{ 057 // Indicates whether to log launch and completion messages for the associated 058 // tool. 059 private final boolean logInvocation; 060 061 // A print stream that may be used to report information about any problems 062 // encountered while attempting to perform invocation logging. 063 private final PrintStream toolErrorStream; 064 065 // The set of log files in which invocation logging should be performed. 066 private final Set<File> logFiles; 067 068 // The name of the command used to invoke the tool. 069 private final String commandName; 070 071 // An identifier that will appear in launch and completion messages for the 072 // tool so that those messages can be correlated for the same invocation of 073 // the tool. 074 private final String invocationID; 075 076 077 078 /** 079 * Creates a new tool invocation log details object with the provided 080 * information. 081 * 082 * @param logInvocation Indicates whether to perform launch and completion 083 * logging for the associated tool. 084 * @param commandName The name (without any path information) for the 085 * provided tool. It must not be {@code null}. 086 * @param invocationID A unique identifier that will be used to correlate 087 * launch and completion messages for the same 088 * invocation of the tool. If this is {@code null}, 089 * then an identifier will be generated. 090 * @param logFiles The set of log files in which launch and 091 * completion messages should be recorded. It may be 092 * {@code null} or empty if no invocation logging 093 * should be performed for this tool. It must not be 094 * {@code null} or empty if invocation logging should 095 * be performed. 096 * @param toolErrorStream A print stream that may be used to report 097 * information about any problems encountered while 098 * attempting to perform invocation logging. It 099 * must not be {@code null}. 100 */ 101 private ToolInvocationLogDetails(final boolean logInvocation, 102 final String commandName, 103 final String invocationID, 104 final Set<File> logFiles, 105 final PrintStream toolErrorStream) 106 { 107 this.logInvocation = logInvocation; 108 this.commandName = commandName; 109 this.toolErrorStream = toolErrorStream; 110 111 if (invocationID == null) 112 { 113 this.invocationID = UUID.randomUUID().toString(); 114 } 115 else 116 { 117 this.invocationID = invocationID; 118 } 119 120 if (logFiles == null) 121 { 122 this.logFiles = Collections.emptySet(); 123 } 124 else 125 { 126 this.logFiles = Collections.unmodifiableSet(logFiles); 127 } 128 } 129 130 131 132 /** 133 * Creates a new {@code ToolInvocationLogDetails} instance that indicates that 134 * no logging should be performed for the specified tool. 135 * 136 * @param commandName The name of the command (without any path information) 137 * for the associated tool. It must not be {@code null}. 138 * 139 * @return The {@code ToolInvocationLogDetails} object that was created. 140 */ 141 static ToolInvocationLogDetails createDoNotLogDetails( 142 final String commandName) 143 { 144 return new ToolInvocationLogDetails(false, commandName, "", 145 Collections.<File>emptySet(), NullOutputStream.getPrintStream()); 146 } 147 148 149 150 /** 151 * Creates a new {@code ToolInvocationLogDetails} instance that indicates that 152 * launch and completion messages should be logged for the specified tool. 153 * 154 * @param commandName The name (without any path information) for the 155 * provided tool. It must not be {@code null}. 156 * @param invocationID A unique identifier that will be used to correlate 157 * launch and completion messages for the same 158 * invocation of the tool. If this is {@code null}, 159 * then an identifier will be generated. 160 * @param logFiles The set of log files in which launch and 161 * completion messages should be recorded. It may be 162 * {@code null} or empty if no invocation logging 163 * should be performed for this tool. It must not be 164 * {@code null} or empty if invocation logging should 165 * be performed. 166 * @param toolErrorStream A print stream that should be used to report 167 * information about any problems encountered while 168 * attempting to perform invocation logging. It 169 * must not be {@code null}. 170 * 171 * @return The {@code ToolInvocationLogDetails} object that was created. 172 */ 173 static ToolInvocationLogDetails createLogDetails(final String commandName, 174 final String invocationID, 175 final Set<File> logFiles, 176 final PrintStream toolErrorStream) 177 { 178 return new ToolInvocationLogDetails(true, commandName, invocationID, 179 logFiles, toolErrorStream); 180 } 181 182 183 184 /** 185 * Retrieves the name of the command (without any path information) for the 186 * associated tool. 187 * 188 * @return The name of the command for the associated tool. 189 */ 190 public String getCommandName() 191 { 192 return commandName; 193 } 194 195 196 197 /** 198 * Indicates whether launch and completion messages should be logged for the 199 * tool. 200 * 201 * @return {@code true} if the messages should be logged, or {@code false} if 202 * not. 203 */ 204 public boolean logInvocation() 205 { 206 return logInvocation; 207 } 208 209 210 211 /** 212 * Retrieves the unique identifier to use to correlate the launch and 213 * completion messages for the tool invocation, if available. 214 * 215 * @return The unique identifier to use to correlate the launch and 216 * completion messages for the tool invocation, or an empty string if 217 * no invocation logging should be performed for the tool. 218 */ 219 public String getInvocationID() 220 { 221 return invocationID; 222 } 223 224 225 226 /** 227 * Retrieves an unmodifiable set of the files in which launch and completion 228 * log messages should be recorded for the tool invocation. 229 * 230 * @return An unmodifiable set of the files in which launch and completion 231 * log messages should be recorded for the tool invocation. It may 232 * be empty if no invocation logging should be performed. 233 */ 234 public Set<File> getLogFiles() 235 { 236 return logFiles; 237 } 238 239 240 241 /** 242 * Retrieves a print stream that may be used to report information about any 243 * problems encountered while attempting to perform invocation logging. 244 * 245 * @return A print stream that may be used to report information about any 246 * problems encountered while attempting to perform invocation 247 * logging. 248 */ 249 public PrintStream getToolErrorStream() 250 { 251 return toolErrorStream; 252 } 253 254 255 /** 256 * Retrieves a string representation of this tool invocation log details 257 * object. 258 * 259 * @return A string representation of this tool invocation log details 260 * object. 261 */ 262 @Override() 263 public String toString() 264 { 265 final StringBuilder buffer = new StringBuilder(); 266 toString(buffer); 267 return buffer.toString(); 268 } 269 270 271 272 /** 273 * Appends a string representation of this tool invocation log details 274 * object to the provided buffer. 275 * 276 * @param buffer The buffer to which the string representation should be 277 * appended. 278 */ 279 public void toString(final StringBuilder buffer) 280 { 281 buffer.append("ToolInvocationLogDetails(commandName='"); 282 buffer.append(commandName); 283 buffer.append("', logInvocation="); 284 buffer.append(logInvocation); 285 286 if (logInvocation) 287 { 288 buffer.append(", invocationID='"); 289 buffer.append(invocationID); 290 buffer.append("', logFiles={"); 291 292 final Iterator<File> fileIterator = logFiles.iterator(); 293 while (fileIterator.hasNext()) 294 { 295 buffer.append('\''); 296 buffer.append(fileIterator.next().getAbsolutePath()); 297 buffer.append('\''); 298 299 if (fileIterator.hasNext()) 300 { 301 buffer.append(", "); 302 } 303 } 304 305 buffer.append('}'); 306 } 307 308 buffer.append(')'); 309 } 310}