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 Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a new formatter.SafeFormatter
(File file) Constructs a new formatter with the specified file.SafeFormatter
(File file, String csn) Constructs a new formatter with the specified file and charset.SafeFormatter
(File file, String csn, Locale l) Constructs a new formatter with the specified file, charset, and locale.Constructs a new formatter with the specified output stream.SafeFormatter
(OutputStream os, String csn) Constructs a new formatter with the specified output stream and charset.SafeFormatter
(OutputStream os, String csn, Locale l) Constructs a new formatter with the specified output stream, charset, and locale.Constructs a new formatter with the specified print stream.Constructs a new formatter with the specified destination.SafeFormatter
(Appendable a, Locale l) Constructs a new formatter with the specified destination and locale.SafeFormatter
(String fileName) Constructs a new formatter with the specified file name.SafeFormatter
(String fileName, String csn) Constructs a new formatter with the specified file name and charset.SafeFormatter
(String fileName, String csn, Locale l) Constructs a new formatter with the specified file name, charset, and locale.Constructs a new formatter with the specified locale. -
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Closes this formatter.void
flush()
Flushes this formatter.Writes a formatted string to this object's destination using the specified format string and arguments.Writes a formatted string to this object's destination using the specified locale, format string, and arguments.static int
getDirectiveCount
(String format) Get a count of the number of formatting directivves in a format stringReturns theIOException
last thrown by this formatter'sAppendable
.locale()
Returns the locale set by the construction of this formatter.static String
Get a modified format that accepts any type of argumentout()
Returns the destination for the output.toString()
Returns the result of invokingtoString()
on the destination for the output.
-
Field Details
-
pattern
The regular expression used by SafeFormatter to match formatting directives provided byFormatter
.- See Also:
-
-
Constructor Details
-
SafeFormatter
public SafeFormatter()Constructs a new formatter.The destination of the formatted output is a
StringBuilder
which may be retrieved by invokingout()
and whose current content may be converted into a string by invokingtoString()
. The locale used is the default locale for this instance of the Java virtual machine. -
SafeFormatter
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. Ifa
isnull
then aStringBuilder
will be created.
-
SafeFormatter
Constructs a new formatter with the specified destination and locale.- Parameters:
a
- Destination for the formatted output. Ifa
isnull
then aStringBuilder
will be created.l
- The locale to apply during formatting. Ifl
isnull
then no localization is applied.
-
SafeFormatter
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 fileUnsupportedEncodingException
- 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 charsetl
- The locale to apply during formatting. Ifl
isnull
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 fileUnsupportedEncodingException
- If the named charset is not supported
-
SafeFormatter
Constructs a new formatter with the specified locale.The destination of the formatted output is a
StringBuilder
which may be retrieved by invokingout()
and whose current content may be converted into a string by invokingtoString()
.- Parameters:
l
- The locale to apply during formatting. Ifl
isnull
then no localization is applied.
-
SafeFormatter
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
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
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 charsetl
- The locale to apply during formatting. Ifl
isnull
then no localization is applied.- Throws:
UnsupportedEncodingException
- If the named charset is not supported
-
SafeFormatter
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
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 fileUnsupportedEncodingException
- 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 charsetl
- The locale to apply during formatting. Ifl
isnull
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 fileUnsupportedEncodingException
- If the named charset is not supported
-
-
Method Details
-
close
public void close()Closes this formatter. If the destination implements theCloseable
interface, itsclose
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 aFormatterClosedException
. -
flush
public void flush()Flushes this formatter. If the destination implements theFlushable
interface, itsflush
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 itsclose()
method
-
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 itsclose()
method
-
modify
Get a modified format that accepts any type of argument- Parameters:
format
- the original format- Returns:
- the modified format
-
getDirectiveCount
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. Ifl
isnull
then no localization is applied. This does not change this object's locale that was set during construction.format
- A format string as described inFormatter
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 theFormatter
section of the formatter class specification.FormatterClosedException
- If this formatter has been closed by invoking itsclose()
method
-
format
public SafeFormatter format(String format, Object... args) throws IllegalFormatException, FormatterClosedException 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 inFormatter
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 theFormatter
section of the formatter class specification.FormatterClosedException
- If this formatter has been closed by invoking itsclose()
method
-
ioException
Returns theIOException
last thrown by this formatter'sAppendable
.If the destination's
append()
method never throwsIOException
, then this method will always returnnull
.- Returns:
- The last exception thrown by the Appendable or
null
if no such exception exists.
-
out
Returns the destination for the output.- Returns:
- The destination for the output
- Throws:
FormatterClosedException
- If this formatter has been closed by invoking itsclose()
method
-
toString
Returns the result of invokingtoString()
on the destination for the output. For example, the following code formats text into aStringBuilder
(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 theAppendable
, the returned string may or may not contain the characters written to the destination. For instance, buffers typically return their contents intoString()
, but streams cannot since the data is discarded.- Overrides:
toString
in classObject
- Returns:
- The result of invoking
toString()
on the destination for the output - Throws:
FormatterClosedException
- If this formatter has been closed by invoking itsclose()
method
-