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
047 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
048 *   for proprietary functionality or for external specifications that are not
049 *   considered stable or mature enough to be guaranteed to work in an
050 *   interoperable way with 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}