Class SafeFormatter

java.lang.Object
org.bzdev.util.SafeFormatter

public final class SafeFormatter extends Object
An interpreter for printf-style format strings that will replace format directives with ones that accept strings if there is a failure. This class is identical java.util.Formatter in terms of the methods and constructors provided. It is intended to provide fail-safe text formatting for purposes such as creating localized exception messages. In these cases, a poorly formatted message is preferable to throwing an exception during exception handling.

The method and constructor documentation has been copied verbatim from the Open JDK 1.7 documentation as we cannot use inheritance to find it.

See Also:
  • Field Details

  • Constructor Details

    • SafeFormatter

      public SafeFormatter()
      Constructs a new formatter.

      The destination of the formatted output is a StringBuilder which may be retrieved by invoking out() and whose current content may be converted into a string by invoking toString(). The locale used is the default locale for this instance of the Java virtual machine.

    • SafeFormatter

      public SafeFormatter(Appendable a)
      Constructs a new formatter with the specified destination.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      a - Destination for the formatted output. If a is null then a StringBuilder will be created.
    • SafeFormatter

      public SafeFormatter(Appendable a, Locale l)
      Constructs a new formatter with the specified destination and locale.
      Parameters:
      a - Destination for the formatted output. If a is null then a StringBuilder will be created.
      l - The locale to apply during formatting. If l is null then no localization is applied.
    • SafeFormatter

      public SafeFormatter(File file) throws FileNotFoundException
      Constructs a new formatter with the specified file.

      The charset used is the default charset for this instance of the Java virtual machine.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      file - The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      Throws:
      FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
    • SafeFormatter

      public SafeFormatter(File file, String csn) throws FileNotFoundException, UnsupportedEncodingException
      Constructs a new formatter with the specified file and charset.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      file - The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      csn - The name of a supported charset
      Throws:
      FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
      UnsupportedEncodingException - If the named charset is not supported
    • SafeFormatter

      public SafeFormatter(File file, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException
      Constructs a new formatter with the specified file, charset, and locale.
      Parameters:
      file - The file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      csn - The name of a supported charset
      l - The locale to apply during formatting. If l is null then no localization is applied.
      Throws:
      FileNotFoundException - If the given file object does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
      UnsupportedEncodingException - If the named charset is not supported
    • SafeFormatter

      public SafeFormatter(Locale l)
      Constructs a new formatter with the specified locale.

      The destination of the formatted output is a StringBuilder which may be retrieved by invoking out() and whose current content may be converted into a string by invoking toString().

      Parameters:
      l - The locale to apply during formatting. If l is null then no localization is applied.
    • SafeFormatter

      public SafeFormatter(OutputStream os)
      Constructs a new formatter with the specified output stream.

      The charset used is the default charset for this instance of the Java virtual machine.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      os - The output stream to use as the destination of this formatter. The output will be buffered.
    • SafeFormatter

      public SafeFormatter(OutputStream os, String csn) throws UnsupportedEncodingException
      Constructs a new formatter with the specified output stream and charset.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      os - The output stream to use as the destination of this formatter. The output will be buffered.
      csn - The name of a supported charset
      Throws:
      UnsupportedEncodingException - If the named charset is not supported
    • SafeFormatter

      public SafeFormatter(OutputStream os, String csn, Locale l) throws UnsupportedEncodingException
      Constructs a new formatter with the specified output stream, charset, and locale.
      Parameters:
      os - The output stream to use as the destination of this formatter. The output will be buffered.
      csn - The name of a supported charset
      l - The locale to apply during formatting. If l is null then no localization is applied.
      Throws:
      UnsupportedEncodingException - If the named charset is not supported
    • SafeFormatter

      public SafeFormatter(PrintStream ps)
      Constructs a new formatter with the specified print stream.

      The locale used is the default locale for this instance of the Java virtual machine.

      Characters are written to the given PrintStream object and are therefore encoded using that object's charset.

      Parameters:
      ps - The stream to use as the destination of this formatter.
    • SafeFormatter

      public SafeFormatter(String fileName) throws FileNotFoundException
      Constructs a new formatter with the specified file name.

      The charset used is the default charset for this instance of the Java virtual machine.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      fileName - The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      Throws:
      FileNotFoundException - If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
    • SafeFormatter

      public SafeFormatter(String fileName, String csn) throws FileNotFoundException, UnsupportedEncodingException
      Constructs a new formatter with the specified file name and charset.

      The locale used is the default locale for this instance of the Java virtual machine.

      Parameters:
      fileName - The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      csn - The name of a supported charset
      Throws:
      FileNotFoundException - If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
      UnsupportedEncodingException - If the named charset is not supported
    • SafeFormatter

      public SafeFormatter(String fileName, String csn, Locale l) throws FileNotFoundException, UnsupportedEncodingException
      Constructs a new formatter with the specified file name, charset, and locale.
      Parameters:
      fileName - The name of the file to use as the destination of this formatter. If the file exists then it will be truncated to zero size; otherwise, a new file will be created. The output will be written to the file and is buffered.
      csn - The name of a supported charset
      l - The locale to apply during formatting. If l is null then no localization is applied.
      Throws:
      FileNotFoundException - If the given file name does not denote an existing, writable regular file and a new regular file of that name cannot be created, or if some other error occurs while opening or creating the file
      UnsupportedEncodingException - If the named charset is not supported
  • Method Details

    • close

      public void close()
      Closes this formatter. If the destination implements the Closeable interface, its close method will be invoked.

      Closing a formatter allows it to release resources it may be holding (such as open files). If the formatter is already closed, then invoking this method has no effect.

      Attempting to invoke any methods except ioException() in this formatter after it has been closed will result in a FormatterClosedException.

    • flush

      public void flush()
      Flushes this formatter. If the destination implements the Flushable interface, its flush method will be invoked.

      Flushing a formatter writes any buffered output in the destination to the underlying stream.

      Throws:
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • locale

      public Locale locale()
      Returns the locale set by the construction of this formatter.

      The format method for this object which has a locale argument does not change this value.

      Returns:
      null if no localization is applied, otherwise a locale
      Throws:
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • modify

      public static String modify(String format)
      Get a modified format that accepts any type of argument
      Parameters:
      format - the original format
      Returns:
      the modified format
    • getDirectiveCount

      public static int getDirectiveCount(String format)
      Get a count of the number of formatting directivves in a format string
      Parameters:
      format - the format string
      Returns:
      the number of formatting directives
    • format

      public SafeFormatter format(Locale l, String format, Object... args) throws IllegalFormatException, FormatterClosedException
      Writes a formatted string to this object's destination using the specified locale, format string, and arguments. If an error occurs, a separate attempt is made by making all formatting directives that take arguments "%s" directives, with positional parameters maintained. For example, after a failure, the directive "%3$8.3g" will be replaced with "%3$s" for the second attempt.
      Parameters:
      l - The locale to apply during formatting. If l is null then no localization is applied. This does not change this object's locale that was set during construction.
      format - A format string as described in Formatter
      args - Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by The Java™ Virtual Machine Specification.
      Returns:
      This formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • format

      Writes a formatted string to this object's destination using the specified format string and arguments. The locale used is the one defined during the construction of this formatter.

      If an error occurs, a separate attempt is made by making all formatting directives that take arguments "%s" directives, with positional parameters maintained. For example, after a failure, the directive "%3$8.3g" will be replaced with "%3$s" for the second attempt.

      Parameters:
      format - A format string as described in Formatter
      args - Arguments referenced by the format specifiers in the format string. If there are more arguments than format specifiers, the extra arguments are ignored. The maximum number of arguments is limited by the maximum dimension of a Java array as defined by The Java™ Virtual Machine Specification.
      Returns:
      This formatter
      Throws:
      IllegalFormatException - If a format string contains an illegal syntax, a format specifier that is incompatible with the given arguments, insufficient arguments given the format string, or other illegal conditions. For specification of all possible formatting errors, see the Formatter section of the formatter class specification.
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • ioException

      public IOException ioException()
      Returns the IOException last thrown by this formatter's Appendable.

      If the destination's append() method never throws IOException, then this method will always return null.

      Returns:
      The last exception thrown by the Appendable or null if no such exception exists.
    • out

      public Appendable out()
      Returns the destination for the output.
      Returns:
      The destination for the output
      Throws:
      FormatterClosedException - If this formatter has been closed by invoking its close() method
    • toString

      public String toString()
      Returns the result of invoking toString() on the destination for the output. For example, the following code formats text into a StringBuilder (created by Formatter's zero-argument constructor) and then retrieves the resultant string:
         Formatter f = new Formatter();
         f.format("Last reboot at %tc", lastRebootDate);
         String s = f.toString();
         // -> s == "Last reboot at Sat Jan 01 00:00:00 PST 2000"
       

      An invocation of this method behaves in exactly the same way as the invocation

           out().toString() 

      Depending on the specification of toString for the Appendable, the returned string may or may not contain the characters written to the destination. For instance, buffers typically return their contents in toString(), but streams cannot since the data is discarded.

      Overrides:
      toString in class Object
      Returns:
      The result of invoking toString() on the destination for the output
      Throws:
      FormatterClosedException - If this formatter has been closed by invoking its close() method