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