org.apache.xalan.xslt

## Class EnvironmentCheck

- java.lang.Object
- - org.apache.xalan.xslt.EnvironmentCheck

-     public class EnvironmentCheck
      extends java.lang.Object

  Utility class to report simple information about the environment. Simplistic reporting about certain classes found in your JVM may help answer some FAQs for simple problems.

  Usage-command line: `java org.apache.xalan.xslt.EnvironmentCheck [-out outFile]`

  Usage-from program: `boolean environmentOK = (new EnvironmentCheck()).checkEnvironment(yourPrintWriter);`

  Usage-from stylesheet: ``

          <?xml version="1.0"?>
          <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
              xmlns:xalan="http://xml.apache.org/xalan"
              exclude-result-prefixes="xalan">
          <xsl:output indent="yes"/>
          <xsl:template match="/">
            <xsl:copy-of select="xalan:checkEnvironment()"/>
          </xsl:template>
          </xsl:stylesheet>

  Xalan users reporting problems are encouraged to use this class to see if there are potential problems with their actual Java environment before reporting a bug. Note that you should both check from the JVM/JRE's command line as well as temporarily calling checkEnvironment() directly from your code, since the classpath may differ (especially for servlets, etc).

  Also see http://xml.apache.org/xalan-j/faq.html

  Note: This class is pretty simplistic: results are not necessarily definitive nor will it find all problems related to environment setup. Also, you should avoid calling this in deployed production code, both because it is quite slow and because it forces classes to get loaded.

  Note: This class explicitly has very limited compile-time dependencies to enable easy compilation and usage even when Xalan, DOM/SAX/JAXP, etc. are not present.

  Note: for an improved version of this utility, please see the xml-commons' project Which utility which does the same kind of thing but in a much simpler manner.

  Version:
    $Id$
  Author:
    Shane_Curcuru@us.ibm.com

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `CLASS_NOTPRESENT` Marker that a class or .jar was not found.
    `static java.lang.String` | `CLASS_PRESENT` Marker that a class or .jar was found.
    `static java.lang.String` | `ERROR` Prefixed to hash keys that signify serious problems.
    `static java.lang.String` | `ERROR_FOUND` Value for any error found.
    `static java.lang.String` | `FOUNDCLASSES` Prefixed to hash keys that signify .jars found in classpath.
    `java.lang.String[]` | `jarNames` Listing of common .jar files that include Xalan-related classes.
    `static java.lang.String` | `VERSION` Prefixed to hash keys that signify version numbers.
    `static java.lang.String` | `WARNING` Added to descriptions that signify potential problems.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EnvironmentCheck()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `appendEnvironmentReport(org.w3c.dom.Node container, org.w3c.dom.Document factory, java.util.Hashtable h)` Stylesheet extension entrypoint: Dump a basic Xalan environment report from getEnvironmentHash() to a Node.
    `boolean` | `checkEnvironment(java.io.PrintWriter pw)` Programmatic entrypoint: Report on basic Java environment and CLASSPATH settings that affect Xalan.
    `java.util.Hashtable` | `getEnvironmentHash()` Fill a hash with basic environment settings that affect Xalan.
    `static void` | `main(java.lang.String[] args)` Command line runnability: checks for [-out outFilename] arg.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### ERROR

          public static final java.lang.String ERROR

      Prefixed to hash keys that signify serious problems.
      See Also:
        Constant Field Values

    - #### WARNING

          public static final java.lang.String WARNING

      Added to descriptions that signify potential problems.
      See Also:
        Constant Field Values

    - #### ERROR_FOUND

          public static final java.lang.String ERROR_FOUND

      Value for any error found.
      See Also:
        Constant Field Values

    - #### VERSION

          public static final java.lang.String VERSION

      Prefixed to hash keys that signify version numbers.
      See Also:
        Constant Field Values

    - #### FOUNDCLASSES

          public static final java.lang.String FOUNDCLASSES

      Prefixed to hash keys that signify .jars found in classpath.
      See Also:
        Constant Field Values

    - #### CLASS_PRESENT

          public static final java.lang.String CLASS_PRESENT

      Marker that a class or .jar was found.
      See Also:
        Constant Field Values

    - #### CLASS_NOTPRESENT

          public static final java.lang.String CLASS_NOTPRESENT

      Marker that a class or .jar was not found.
      See Also:
        Constant Field Values

    - #### jarNames

          public java.lang.String[] jarNames

      Listing of common .jar files that include Xalan-related classes.

  - ### Constructor Detail

    - #### EnvironmentCheck

          public EnvironmentCheck()

  - ### Method Detail

    - #### main

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

      Command line runnability: checks for [-out outFilename] arg.

      Command line entrypoint; Sets output and calls `checkEnvironment(PrintWriter)`.

      Parameters:
        `args` - command line args

    - #### checkEnvironment

          public boolean checkEnvironment(java.io.PrintWriter pw)

      Programmatic entrypoint: Report on basic Java environment and CLASSPATH settings that affect Xalan.

      Note that this class is not advanced enough to tell you everything about the environment that affects Xalan, and sometimes reports errors that will not actually affect Xalan's behavior. Currently, it very simplistically checks the JVM's environment for some basic properties and logs them out; it will report a problem if it finds a setting or .jar file that is likely to cause problems.

      Advanced users can peruse the code herein to help them investigate potential environment problems found; other users may simply send the output from this tool along with any bugs they submit to help us in the debugging process.

      Parameters:
        `pw` - PrintWriter to send output to; can be sent to a file that will look similar to a Properties file; defaults to System.out if null
      Returns:
        true if your environment appears to have no major problems; false if potential environment problems found
      See Also:
        `getEnvironmentHash()`

    - #### getEnvironmentHash

          public java.util.Hashtable getEnvironmentHash()

      Fill a hash with basic environment settings that affect Xalan.

      Worker method called from various places.

      Various system and CLASSPATH, etc. properties are put into the hash as keys with a brief description of the current state of that item as the value. Any serious problems will be put in with a key that is prefixed with `'ERROR.'` so it stands out in any resulting report; also a key with just that constant will be set as well for any error.

      Note that some legitimate cases are flaged as potential errors - namely when a developer recompiles xalan.jar on their own - and even a non-error state doesn't guaruntee that everything in the environment is correct. But this will help point out the most common classpath and system property problems that we've seen.

      Returns:
        Hashtable full of useful environment info about Xalan and related system properties, etc.

    - #### appendEnvironmentReport

          public void appendEnvironmentReport(org.w3c.dom.Node container,
                                              org.w3c.dom.Document factory,
                                              java.util.Hashtable h)

      Stylesheet extension entrypoint: Dump a basic Xalan environment report from getEnvironmentHash() to a Node.

      Copy of writeEnvironmentReport that creates a Node suitable for other processing instead of a properties-like text output.

      Parameters:
        `container` - Node to append our report to
        `factory` - Document providing createElement, etc. services
        `h` - Hash presumably from `getEnvironmentHash()`
      See Also:
        `for an equivalent that writes to a PrintWriter instead`

Copyright © 2023 Apache XML Project. All Rights Reserved.