org.safs.tools.logs

Class MultiLogResults

java.lang.Object

org.safs.tools.logs.MultiLogResults

public class MultiLogResults
extends java.lang.Object

Processes a user-specified directory for SAFS XML Log files. Creates a new single XML List file consolidating the file hrefs for all SAFS XML Log files in the directory. Then, optionally, the class creates a summary XML file and/or a summary JAXP Document Node containing:

• For each XML file that proves to be a SAFS XML Log the class will:
  1. Record the log file href information uniquely identifying the log
  2. Record the date/time the log was opened
  3. Record the final status report information for that log
  4. Maintain a cumulative summary of all status report information for all files
  5. Record the date/time the log was closed

• Record the cumulative summary of all status report information from all files

JVM Arguments:

• "C:\\SAFS\\Project\\Datapool\\Logs"
  Full path to the directory containing the SAFS XML log(s) to consolidate and/or summarize.
  This must be specified unless the -log argument contains a full path to a single log to be processed.
  Same as JVM Option: >-Dsafs.multilog.dir="<path/to/xmllogs/directory>"
  Ex: -Dsafs.multilog.dir="C:\\SAFS\\Project\\Datapool\\Logs"

• -out "C:\\SAFS\\Project\\Reports"
  Full path to the directory where any generated files will be written.
  By default all generated files will be written to the same directory where input files are found.
  Same as JVM Option: -Dsafs.multilog.out="<path/to/output/directory>"
  Ex: -Dsafs.multilog.out="C:\\SAFS\\Project\\Reports"

• -list "MultiLogResultsList.xml"
  Full or relative path to an existing XML Logs List file to process for summarization. This allows the user to pre-specify a set of log files to process instead of letting the program process ALL log files present in a logs directory. A relative path is relative to the specified -dir logs directory.
  Same as JVM Option: -Dsafs.multilog.list="<path/to/safsxmllogslist.xml>"
  Ex: -Dsafs.multilog.list="MultiLogResultsList.xml"
  Ex: -Dsafs.multilog.list="C:\\SAFS\\Project\\Datapool\\Logs\\MultiLogResultsList.xml"

• -xsl "XSLMultiLogResults.xsl"
  Full or relative path to an existing XSL file to use for summarization. A relative file specification assumes the XSL file is in the same directory as the XML List file to be processed.
  Same as JVM Option: -Dsafs.multilog.xsl="<path/to/safsxmllogsxsl.xsl>"
  Ex: -Dsafs.multilog.xsl="C:\\SAFS\\Project\\Datapool\\Logs\\XSLMultiLogResults.xsl"
  Ex: -Dsafs.multilog.xsl="XSLMultiLogResults.xsl"

• -log "TestComposerLog.xml"
  Full or relative path to a single SAFS XML log to summarize.
  Same as JVM Option: -Dsafs.multilog.log="<path/to/single/safsxmllog.xml>"
  Ex: -Dsafs.multilog.log="TestComposerLog.xml"
  Ex: -Dsafs.multilog.log="C:\\SAFS\\Project\\Datapool\\Logs\\TestComposerLog.xml"

• -nosummary
  If present, only the initial XML list file containing the file hrefs for all SAFS XML log files will be created. All subsequent processing will be aborted.
  Same as JVM Option: -Dsafs.multilog.nosummary

• -summary "EMinerSummary.xml"
  Full or relative path for the summary XML file to be created. If a relative path is provided then we will:
  • look first to write to the specified log -out directory,
  • else, look to write to the specified logs -dir directory,
  • else, attempt to write to the directory where a single -log was processed,
  • else, an error in arguments has occurred.

  Same as JVM Option: -Dsafs.multilog.summary="<path/to/xml/summary.xml>"
  Ex: -Dsafs.multilog.summary="EMinerSummary.xml"
  Ex: -Dsafs.multilog.summary="C:\\SAFS\\Project\\Reports\\EMinerSummary.xml"

  This class requires a "registered" JAXP XSLT Processor to be in the runtime CLASSPATH.
  A registered JAXP XSLT Processor generally contains TransformerFactory services information in the META-INF\services directory of its JAR file library. This class was tested using the SAXON 9.4 JAR files be in the runtime CLASSPATH:

  • saxon9he.jar
  • saxon9-unpack.jar

  Other XSLT Processors conforming to the JAXP standards and XSLT 2.0 specification should also work.

  The processor must support XSLT 2.0 or higher. Specifically, that result tree fragments can be internally converted to and be treated as valid node-sets. MSXML, the MSXSL.EXE program, and older (sometimes default) versions of XALAN do not support such tree fragment conversions when they strictly adhere to XSLT 1.0 specifications.

Author:

Carl Nagle
FEB 20, 2013 Carl Nagle Added support for the default XSL file to use.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	absoluteList
protected boolean	absoluteLog
protected boolean	absoluteLogs
protected boolean	absoluteOut
protected boolean	absoluteSummary
protected boolean	absoluteXSL
static java.lang.String	ARG_DIR "-dir"
static java.lang.String	ARG_LIST "-list"
static java.lang.String	ARG_LOG "-log"
static java.lang.String	ARG_NOSUMMARY "-nosummary"
static java.lang.String	ARG_OUT "-out"
static java.lang.String	ARG_SUMMARY "-summary"
static java.lang.String	ARG_XSL "-xsl"
static java.lang.String	DEFAULT_LIST_FILENAME "MultiLogResultsList.xml"
static java.lang.String	DEFAULT_SUMMARY_FILENAME "MultiLogResultsSummary.xml"
static java.lang.String	DEFAULT_XSL_FILENAME "XSLMultiLogsListSummary.xsl"
protected java.io.File	DIR_LOGS
protected java.io.File	DIR_OUT
boolean	DO_SUMMARY Create an XML summary file from one or more SAFS XML log files.
protected java.io.File	FILE_LIST
protected java.io.File	FILE_LOG
protected java.io.File	FILE_SUMMARY
protected java.io.File	FILE_XSL
protected boolean	isListInput
protected boolean	isValidated
static java.lang.String	PROP_KEY_SAFS_MULTILOG_DIR "safs.multilog.dir"
static java.lang.String	PROP_KEY_SAFS_MULTILOG_LIST "safs.multilog.list"
static java.lang.String	PROP_KEY_SAFS_MULTILOG_LOG "safs.multilog.log"
static java.lang.String	PROP_KEY_SAFS_MULTILOG_NOSUMMARY "safs.multilog.nosummary"
static java.lang.String	PROP_KEY_SAFS_MULTILOG_OUT "safs.multilog.out"
static java.lang.String	PROP_KEY_SAFS_MULTILOG_SUMMARY "safs.multilog.summary"
static java.lang.String	PROP_KEY_SAFS_MULTILOG_XSL "safs.multilog.xsl"
protected static java.lang.String	UTF8_CHARSET "UTF-8"
protected static java.lang.String	XML_SUFFIX_LC ".xml"
protected static java.lang.String	XSL_SUFFIX_LC ".xsl"

Constructor Summary

Constructors

Constructor and Description
MultiLogResults()

Method Summary

Modifier and Type	Method and Description
protected static org.w3c.dom.Document	buildDoc(java.lang.String document) Used internally.
java.io.File	createSingleXMLLogList(java.lang.String inputLogDir, java.lang.String inputLogFile) Create an XML List File listing a single SAFS XML log file.
java.io.File	createXMLLogsList(java.lang.String inputLogsDir) Create an XML List File listing all SAFS XML log files in the inputLogsDir.
java.io.File	createXMLLogsSummary(java.lang.String inputXMLFile, java.lang.String inputXSLFile, java.lang.String outputXMLFile) Create an XML Summary File from the transformation of an XML List file and XSL transformation file.
org.w3c.dom.Node	createXMLLogsSummaryNodes(java.lang.String inputXMLFile, java.lang.String inputXSLFile) Create an JAXP XML Document Node from the transformation of an XML List file and XSL transformation file.
void	execute() Perform the end-to-end execution of creating an XML List File and XML Summary File from the current configuration of the instance.
protected static java.lang.String	getSystemProperty(java.lang.String pname) convenience routine to retrieve a System property value or null-- catching any thrown "not found" exceptions.
java.io.File	getXMLListFile() Normally only called AFTER a successful execution.
java.io.File	getXMLSummaryFile() Normally only called AFTER a successful execution.
java.io.File	getXSLFile()
boolean	hasListInput()
boolean	hasLogInput()
boolean	hasValidated()
boolean	hasXMLListFile() Normally only called AFTER a successful execution.
boolean	hasXMLSummaryFile() Normally only called AFTER a successful execution.
boolean	hasXSLFile()
boolean	hasXSLInput()
static void	log(java.lang.String message) Currently logs to System.out.
static void	main(java.lang.String[] args) primarily a testing/debug command-line entry point.
void	processArgs(java.lang.String[] args) String[] args will override any processJVMOptions previously set-- assuming JVM Options are processed BEFORE these args.
void	processJVMOptions() (Re)Set any arguments passed in as JVM -D Options.
void	resetValidation() clears ALL flags associated with validated settings including the isValidated flag.
boolean	validate() Call this routine to validate the current instance configuration settings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DO_SUMMARY

public boolean DO_SUMMARY

Create an XML summary file from one or more SAFS XML log files.

DEFAULT_LIST_FILENAME

public static final java.lang.String DEFAULT_LIST_FILENAME

"MultiLogResultsList.xml"

See Also:

Constant Field Values

DEFAULT_SUMMARY_FILENAME

public static final java.lang.String DEFAULT_SUMMARY_FILENAME

"MultiLogResultsSummary.xml"

See Also:

Constant Field Values

DEFAULT_XSL_FILENAME

public static final java.lang.String DEFAULT_XSL_FILENAME

"XSLMultiLogsListSummary.xsl"

See Also:

Constant Field Values

PROP_KEY_SAFS_MULTILOG_DIR

public static final java.lang.String PROP_KEY_SAFS_MULTILOG_DIR

"safs.multilog.dir"

See Also:

Constant Field Values

PROP_KEY_SAFS_MULTILOG_OUT

public static final java.lang.String PROP_KEY_SAFS_MULTILOG_OUT

"safs.multilog.out"

See Also:

Constant Field Values

PROP_KEY_SAFS_MULTILOG_XSL

public static final java.lang.String PROP_KEY_SAFS_MULTILOG_XSL

"safs.multilog.xsl"

See Also:

Constant Field Values

PROP_KEY_SAFS_MULTILOG_LIST

public static final java.lang.String PROP_KEY_SAFS_MULTILOG_LIST

"safs.multilog.list"

See Also:

Constant Field Values

PROP_KEY_SAFS_MULTILOG_LOG

public static final java.lang.String PROP_KEY_SAFS_MULTILOG_LOG

"safs.multilog.log"

See Also:

Constant Field Values

PROP_KEY_SAFS_MULTILOG_NOSUMMARY

public static final java.lang.String PROP_KEY_SAFS_MULTILOG_NOSUMMARY

"safs.multilog.nosummary"

See Also:

Constant Field Values

PROP_KEY_SAFS_MULTILOG_SUMMARY

public static final java.lang.String PROP_KEY_SAFS_MULTILOG_SUMMARY

"safs.multilog.summary"

See Also:

Constant Field Values

ARG_DIR

public static final java.lang.String ARG_DIR

"-dir"

See Also:

Constant Field Values

ARG_OUT

public static final java.lang.String ARG_OUT

"-out"

See Also:

Constant Field Values

ARG_LOG

public static final java.lang.String ARG_LOG

"-log"

See Also:

Constant Field Values

ARG_XSL

public static final java.lang.String ARG_XSL

"-xsl"

See Also:

Constant Field Values

ARG_LIST

public static final java.lang.String ARG_LIST

"-list"

See Also:

Constant Field Values

ARG_NOSUMMARY

public static final java.lang.String ARG_NOSUMMARY

"-nosummary"

See Also:

Constant Field Values

ARG_SUMMARY

public static final java.lang.String ARG_SUMMARY

"-summary"

See Also:

Constant Field Values

absoluteLogs

protected boolean absoluteLogs

absoluteList

protected boolean absoluteList

absoluteLog

protected boolean absoluteLog

absoluteXSL

protected boolean absoluteXSL

absoluteSummary

protected boolean absoluteSummary

absoluteOut

protected boolean absoluteOut

isValidated

protected boolean isValidated

isListInput

protected boolean isListInput

DIR_LOGS

protected java.io.File DIR_LOGS

DIR_OUT

protected java.io.File DIR_OUT

FILE_LIST

protected java.io.File FILE_LIST

FILE_LOG

protected java.io.File FILE_LOG

FILE_XSL

protected java.io.File FILE_XSL

FILE_SUMMARY

protected java.io.File FILE_SUMMARY

XML_SUFFIX_LC

protected static final java.lang.String XML_SUFFIX_LC

".xml"

See Also:

Constant Field Values

XSL_SUFFIX_LC

protected static final java.lang.String XSL_SUFFIX_LC

".xsl"

See Also:

Constant Field Values

UTF8_CHARSET

protected static final java.lang.String UTF8_CHARSET

"UTF-8"

See Also:

Constant Field Values

Constructor Detail

MultiLogResults

public MultiLogResults()

Method Detail

log

public static void log(java.lang.String message)

Currently logs to System.out. Other options may be supported in the future.

hasListInput

public boolean hasListInput()

Returns:

true if all set parameters have been validated successfully and the instance is set to process a pre-existing XML File list instead of creating one dynamically.

hasXSLInput

public boolean hasXSLInput()

Returns:

true if all set parameters have been validated successfully--which also means an XSL document has been identified as existing.

hasValidated

public boolean hasValidated()

Returns:

true if all the set parameters have been validated successfully.

hasLogInput

public boolean hasLogInput()

Returns:

true if all set parameters have been validated successfully and the instance is set to process a single pre-existing SAFS XML Log File instead of consolidating multiple SAFS XML log files.

resetValidation

public void resetValidation()

clears ALL flags associated with validated settings including the isValidated flag.

getSystemProperty

protected static java.lang.String getSystemProperty(java.lang.String pname)

convenience routine to retrieve a System property value or null-- catching any thrown "not found" exceptions.

processJVMOptions

public void processJVMOptions()

(Re)Set any arguments passed in as JVM -D Options. A call to this routine will also resetValidation()

processArgs

public void processArgs(java.lang.String[] args)

String[] args will override any processJVMOptions previously set-- assuming JVM Options are processed BEFORE these args. A call to this routine will also resetValidation().

Parameters:

args - -- the String[] command-line args received or otherwise provided.

validate

public boolean validate()
                 throws java.lang.IllegalArgumentException

Call this routine to validate the current instance configuration settings. This would normally be called after we have processJVMOptions and processArgs to verify the current setup should work. That is, that specified directories and files provided in the arguments do indeed exist, as appropriate.

                LOGS (-dir) must be specified unless an absolute LOG _OR_ an absolute LIST is specified.
                It is an error to specify both a LOG and a LIST.
                LOGS (-dir) will be assigned the LOG parent directory when an absolute LOG is specified.
                LOGS (-dir) will be assigned the LIST parent directory when an absolute LIST is specified and LOGS is not specified.
                OUT is optional always.  
                OUT will be assigned the LOGS directory if OUT is not specified.
                OUT will be assigned the SUMMARY parent directory when an absolute SUMMARY is specified and 
                    OUT is not specified.
                SUMMARY is optional always.  SUMMARY will be assigned the default name if not specified.
                LIST is optional always. LIST will be assigned the default name if not specified and we are 
                    NOT processing a single LOG.
 

Returns:

true if all settings validated successfully. Throws IllegalArgumentException otherwise.

Throws:

java.lang.IllegalArgumentException - if a problem is found with the current configuration.

createXMLLogsList

public java.io.File createXMLLogsList(java.lang.String inputLogsDir)
                               throws java.lang.IllegalArgumentException

Create an XML List File listing all SAFS XML log files in the inputLogsDir.

Parameters:

inputLogsDir - -- fullpath directory to process for SAFS XML log files. If this is null then we will use whatever arguments have previously been provided. If non-null, a call to re-validate all arguments will occur.

outputListFile - -- fullpath XML list file to create. If this is null then we will use whatever arguments have previously been provided. If non-null, a call to re-validate all arguments will occur.

Returns:

File object to created XML List File, or null if there were no logs found or processed.

Throws:

java.lang.IllegalArgumentException - if inputLogsDir is invalid, does not exist, or if the outputListFile cannot be created.

createSingleXMLLogList

public java.io.File createSingleXMLLogList(java.lang.String inputLogDir,
                                           java.lang.String inputLogFile)
                                    throws java.lang.IllegalArgumentException

Create an XML List File listing a single SAFS XML log file.

Parameters:

inputLogDir - -- full path to directory containing XML log file. If this is null then we will use whatever arguments have previously been provided. If non-null, a call to re-validate all arguments will occur.

inputLogFile - -- full or relative path to single SAFS XML log file. If this is null then we will use whatever arguments have previously been provided. If non-null, a call to re-validate all arguments will occur.

outputListFile - -- full path to the XML list file to create. If this is null then we will use whatever arguments have previously been provided. If non-null, a call to re-validate all arguments will occur.

Returns:

File object to created XML List File, or null if there was no log found or processed.

Throws:

java.lang.IllegalArgumentException - if inputLogFile is invalid, does not exist, or if the outputListFile cannot be created.

createXMLLogsSummary

public java.io.File createXMLLogsSummary(java.lang.String inputXMLFile,
                                         java.lang.String inputXSLFile,
                                         java.lang.String outputXMLFile)
                                  throws java.lang.IllegalArgumentException,
                                         java.lang.Exception

Create an XML Summary File from the transformation of an XML List file and XSL transformation file.

Parameters:

inputXMLFile - -- fullpath to valid XML List File to be used in transformation.

inputXSLFile - -- fullpath to valid XSL File to be used in transformation.

outputXMLFile - -- fullpath to the desired output XML File to be created or overwritten. The directory for this file must already exist.

Returns:

File object pointing to the created XML Summary File, or null if the file was not created or otherwise does not exist.

Throws:

java.lang.IllegalArgumentException - if any of the input parameters are invalid or otherwise not usable.

java.lang.Exception - --various exceptions that might be thrown from the JAXP XML transformation classes.

createXMLLogsSummaryNodes

public org.w3c.dom.Node createXMLLogsSummaryNodes(java.lang.String inputXMLFile,
                                                  java.lang.String inputXSLFile)
                                           throws java.lang.Exception

Create an JAXP XML Document Node from the transformation of an XML List file and XSL transformation file.

Parameters:

inputXMLFile - -- fullpath to valid XML List File to be used in transformation.

inputXSLFile - -- fullpath to valid XSL File to be used in transformation.

Returns:

The top-level XML Document as a DOM document Node if the transform was successful. Can be null if no Node was set, or if the transformation was not completed.

Throws:

java.lang.IllegalArgumentException - if any of the input parameters are invalid or otherwise not usable.

java.lang.Exception - -- various exceptions that might be thrown from the JAXP XML transformation classes.

buildDoc

protected static org.w3c.dom.Document buildDoc(java.lang.String document)
                                        throws java.lang.Exception

Used internally.

Parameters:

document - -- fullpath to valid (XSL) file to be used in transformation.

Returns:

JAXP DOM Document object loaded and parsed.

Throws:

java.lang.Exception - -- various exceptions that might be thrown from the JAXP XML transformation classes.

hasXMLListFile

public boolean hasXMLListFile()

Normally only called AFTER a successful execution.

Returns:

true if the instance is still "validated" and the file exists.

getXMLListFile

public java.io.File getXMLListFile()
                            throws java.lang.IllegalStateException

Normally only called AFTER a successful execution.

Returns:

File reference to the input or created XML Log List file, but only if the instance is still "validated" and the file exists. Otherwise, throws an IllegalStateException.

Throws:

java.lang.IllegalStateException - if the current configuration is not "validated" or the requested file does not exist.

hasXSLFile

public boolean hasXSLFile()

Returns:

true if the instance is still "validated" and the file exists.

getXSLFile

public java.io.File getXSLFile()
                        throws java.lang.IllegalStateException

Returns:

File reference to the XSL file, but only if the instance is still "validated" and the file exists. Otherwise, throws an IllegalStateException.

Throws:

java.lang.IllegalStateException - if the current configuration is not "validated" or the requested file does not exist.

hasXMLSummaryFile

public boolean hasXMLSummaryFile()

Normally only called AFTER a successful execution.

Returns:

true if the instance is still "validated" and the file exists.

getXMLSummaryFile

public java.io.File getXMLSummaryFile()
                               throws java.lang.IllegalStateException

Normally only called AFTER a successful execution.

Returns:

File reference to the created XML Logs Summary file, but only if the instance is still "validated" and the file exists. Otherwise, returns null.

Throws:

java.lang.IllegalStateException - if the current configuration is not "validated" or the requested file does not exist.

execute

public void execute()
             throws java.lang.IllegalArgumentException

Perform the end-to-end execution of creating an XML List File and XML Summary File from the current configuration of the instance.

The routine will first validate() the current configuration, then create the XML List File as necessary from a single XML log file, or all XML log files as required by the current configuration. This portion of the process is bypassed if the current configuration specifies to use a pre-existing XML List File.

With the XML List File ready, the routine will then create an XML Summary File consolidating all test results specified in the XML List File. This portion of the process is bypassed if the current configuration has the -nosummary setting set true.

Throws:

java.lang.IllegalArgumentException - as may be thrown during configuration validation.

java.lang.Exception - as may be thrown by the JAXP XML transformation process.

main

public static void main(java.lang.String[] args)

primarily a testing/debug command-line entry point. Default command-line execution performs:

                MultiLogResults process = new MultiLogResults();
                process.processJVMOptions();
                process.processArgs(args);
                process.execute();
 

Parameters:

args - -- command-line args.