ix.util
Class Util

java.lang.Object
  ix.util.Util

public class Util
extends java.lang.Object

Class for useful static methods that don't belong anywhere else.

See Also:

Collect, Fn, Strings

Constructor Summary

Util()

Method Summary

static java.lang.String	aClass(java.lang.Class c) Returns a "nice" name for a class, using dash-syntax rather than Java capitalisation, prefixed by "a" or "an" as appropriate.
static java.lang.String	aClass(java.lang.Object o) Returns a "nice" name for an object's class, using dash-syntax rather than Java capitalisation, prefixed by "a" or "an" as appropriate.
static java.lang.Object	appendArrays(java.lang.Object[] arrays) Appends the arrays in an array of arrays.
static java.lang.Object	appendArrays(java.lang.Object array1, java.lang.Object array2) Appends two arrays.
static java.lang.String	askLine(java.lang.String prompt) Simple, text-based user interaction.
static java.lang.String	askLines(java.lang.String prompt) Prompts for multi-line textual input.
static java.lang.Class	classForNameElseNull(java.lang.String name) Returns the class of the specified name or else null if the class cannot be found.
static java.lang.Object	clone(java.lang.Object obj) Clones an object without any declared checked exceptions.
static java.lang.Object	cloneBySerializing(java.lang.Object obj) Performs a deep-copy clone by serializing then deserialising an object.
static boolean	dialogConfirms(java.awt.Component parent, java.lang.Object text) Displays a confirmation dialog and returns true or false depending on whether the use selected "Yes" or "No".
static void	displayAndWait(java.awt.Component parentComponent, java.lang.Object message) Asks the GUI event-handling thread to display a text message in a dialogue box and does not return until this has occurred and the user has dismissed the dialogue.
static java.util.Queue<java.lang.String>	fileLines(java.lang.String url) Returns the contents of a text file (or similar resource) as a queue of lines.
static java.util.Queue<java.lang.String>	fileLines(java.net.URL url) Returns the contents of a text file (or similar resource) as a queue of lines.
static java.lang.String	getContentCharset(java.lang.String contentType) Extracts the charset name from the content type, if given; otherwise returns null.
static java.lang.String	getContentCharset(java.net.URLConnection conn) Extracts the charset name from the content type, if given; otherwise returns null.
static java.lang.String	getHostName() Returns the name of the machine that is running this JVM.
static javax.swing.ImageIcon	getImageIcon(java.lang.String name) Constructs an ImageIcon from the named (image) resource.
static java.lang.String	getUserName() Returns the name of the user who started this JVM.
static boolean	hostNameMatchesAddr(java.lang.String name, java.net.InetAddress expected) Checks whether a symbolic host name corresponds to an InetAddress.
static <T> T	makeInstance(java.lang.Class<T> c) Makes an instance of a class using the 0-argument constructor.
static <T> T	makeInstance(java.lang.Class<T> c, java.lang.Object... args) Makes an instance of a class using the most specifc constructor.
static <T> T	mustBe(java.lang.Class<T> c, java.lang.Object o) Returns an object if it is an instance of the specified class, but throws a ClassCastException if it isn't.
static java.lang.String	mustBeStringlike(java.lang.Object o) Returns the String representation of a String, Symbol, or Name, and throws a ClassCastException for anything else.
static void	notImplemented(java.awt.Component parent, java.lang.String item) Brings up a message that the given string item is not yet supported.
static java.io.Reader	openURLReader(java.net.URL url) Returns a Reader for the specified URL based on the InputStream and content charset obtained by opening a connection to the URL.
static void	printGreeting(java.lang.String name) A method to print the name of the system, the release version, and the release date.
static void	printLines(java.lang.String[] lines) Print the elements of a String[] array to System.out as lines.
static java.lang.String	quote(java.lang.String text) Puts double quotes around a string.
static java.util.Queue<java.lang.String>	readAllLines(java.io.Reader r) Reads lines of text from a Reader until there are no more, then returns them in a queue.
static java.lang.String	readLine() Reads a line from System.in.
static java.lang.String	readLine(java.io.InputStream is) Reads a line from an InputStream and returns it as a String.
static java.lang.String	readLines() Reads lines from System.in.
static java.lang.String	readLines(java.io.InputStream in) Reads lines up to a blank line, then returns all of the lines, except the blank one, concatenated into one string.
static void	renameToBackup(java.io.File file) Renames the file to indicate it is an earlier version so that a new version can then be written.
static javax.swing.ImageIcon	resourceImageIcon(java.lang.String name) Constructs an ImageIcon from the named (image) resource found on the system's class path.
static void	run(java.lang.Runnable thunk) A method that lets you write "run" before the creation of a Runnable.
static void	runHooks(java.lang.String when, java.util.List<java.lang.Runnable> hooks) Runs each item, in sequence, in a list of Runnables.
static java.lang.String	showInputDialog(java.awt.Component parent, java.lang.Object message, java.lang.Object initialValue) Display a textual input dialog with a specified initial value.
static void	sleepSeconds(int seconds) Sleeps for the specified number of seconds.
static void	swingAndWait(java.lang.Runnable thunk) A version of SwingUtilities.invokeAndWait(Runnable) that does not require local handling of checked exceptions.

Methods inherited from class java.lang.Object

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

Constructor Detail

Util

public Util()

Method Detail

printGreeting

public static void printGreeting(java.lang.String name)

A method to print the name of the system, the release version, and the release date.

displayAndWait

public static void displayAndWait(java.awt.Component parentComponent,
                                  java.lang.Object message)

Asks the GUI event-handling thread to display a text message in a dialogue box and does not return until this has occurred and the user has dismissed the dialogue.

If this method is called outside the event dispatching thread, it calls SwingUtilities.invokeAndWait(Runnable).

Parameters:

parentComponent - determines the Frame in which dialogs are displayed.

message - the contents of the message.

swingAndWait

public static void swingAndWait(java.lang.Runnable thunk)

A version of SwingUtilities.invokeAndWait(Runnable) that does not require local handling of checked exceptions.

Throws:

RethrownException - if SwingUtilities.invokeAndWait throws an InvocationTargetException or InterruptedException.

notImplemented

public static void notImplemented(java.awt.Component parent,
                                  java.lang.String item)

Brings up a message that the given string item is not yet supported. e.g. "Deleting a schema is not yet supported"

showInputDialog

public static java.lang.String showInputDialog(java.awt.Component parent,
                                               java.lang.Object message,
                                               java.lang.Object initialValue)

Display a textual input dialog with a specified initial value.

Such a method is provided by JOptionPane in JDK 1.4 and later, but not, it seems, in earlier versions.

dialogConfirms

public static boolean dialogConfirms(java.awt.Component parent,
                                     java.lang.Object text)

Displays a confirmation dialog and returns true or false depending on whether the use selected "Yes" or "No". It can be called in any thread and will switch to the Swing / AWT event-dispatching thread to display the dialog if it is called in some other thread. In all cases, the user must make the selection before this method will return.

See Also:

swingAndWait(Runnable), displayAndWait(java.awt.Component, Object)

sleepSeconds

public static void sleepSeconds(int seconds)

Sleeps for the specified number of seconds.

getImageIcon

public static javax.swing.ImageIcon getImageIcon(java.lang.String name)

Constructs an ImageIcon from the named (image) resource. The resource can be specified as a file-name, a URL, or as the name of a resource that can be found on the agent's class-path. If the name does not work as-is, and it is not a URL and does not contain "/", it is tried again with "resources/images/" added to the front.

See Also:

XML.toURL(String)

resourceImageIcon

public static javax.swing.ImageIcon resourceImageIcon(java.lang.String name)

Constructs an ImageIcon from the named (image) resource found on the system's class path. If the name contains "/", it is used as-is; else "resources/images/" is added to the front.

getUserName

public static java.lang.String getUserName()

Returns the name of the user who started this JVM.

getHostName

public static java.lang.String getHostName()
                                    throws java.net.UnknownHostException

Returns the name of the machine that is running this JVM. The name can be given explicitly by specifying a "host" parameter.

Throws:

java.net.UnknownHostException - if it cannot determine the host name and no "host" parameter has been specified.

See Also:

Parameters

hostNameMatchesAddr

public static boolean hostNameMatchesAddr(java.lang.String name,
                                          java.net.InetAddress expected)

Checks whether a symbolic host name corresponds to an InetAddress. This is done by calling InetAddress.getByName(name) and checking whether the result equals the expected address.

quote

public static java.lang.String quote(java.lang.String text)

Puts double quotes around a string. This is useful to indicate the boundaries of the string when it's included in other text such as in an error or warning message.

run

public static void run(java.lang.Runnable thunk)

A method that lets you write "run" before the creation of a Runnable. For example:

    Util.run(new Runnable() {
        public void run() {
            ...
       }
    });
 

instead of the more awkward

    new Runnable() {
        public void run() {
            ...
       }
    }.run();
 

runHooks

public static void runHooks(java.lang.String when,
                            java.util.List<java.lang.Runnable> hooks)

Runs each item, in sequence, in a list of Runnables. "When" is a brief description of when this happens, for example "startup" or "exit".

classForNameElseNull

public static java.lang.Class classForNameElseNull(java.lang.String name)

Returns the class of the specified name or else null if the class cannot be found. It does this by calling Class.forName(name) and catching any ClassNotFoundException.

makeInstance

public static <T> T makeInstance(java.lang.Class<T> c)

Makes an instance of a class using the 0-argument constructor.

Throws:

RethrownException - if the attempt fails, with the original exception inside it.

makeInstance

public static <T> T makeInstance(java.lang.Class<T> c,
                                 java.lang.Object... args)

Makes an instance of a class using the most specifc constructor.

Throws:

RethrownException - if the attempt fails, with the original exception inside it.

clone

public static java.lang.Object clone(java.lang.Object obj)

Clones an object without any declared checked exceptions.

cloneBySerializing

public static java.lang.Object cloneBySerializing(java.lang.Object obj)

Performs a deep-copy clone by serializing then deserialising an object.

mustBe

public static <T> T mustBe(java.lang.Class<T> c,
                           java.lang.Object o)

Returns an object if it is an instance of the specified class, but throws a ClassCastException if it isn't. This allows us to provide a more infomative error message than if we'd just cast the object to the desired class.

mustBeStringlike

public static java.lang.String mustBeStringlike(java.lang.Object o)

Returns the String representation of a String, Symbol, or Name, and throws a ClassCastException for anything else.

aClass

public static java.lang.String aClass(java.lang.Class c)

Returns a "nice" name for a class, using dash-syntax rather than Java capitalisation, prefixed by "a" or "an" as appropriate.

aClass

public static java.lang.String aClass(java.lang.Object o)

Returns a "nice" name for an object's class, using dash-syntax rather than Java capitalisation, prefixed by "a" or "an" as appropriate.

appendArrays

public static java.lang.Object appendArrays(java.lang.Object[] arrays)

Appends the arrays in an array of arrays. The component class of the result array will be the same as that of the 1st of the appended arrays.

Throws:

java.lang.IllegalArgumentException - if there isn't at least one array to append or if any of the objects to append isn't an array.

appendArrays

public static java.lang.Object appendArrays(java.lang.Object array1,
                                            java.lang.Object array2)

Appends two arrays. The component class of the result array will be the same as that of the 1st of the appended arrays.

Throws:

java.lang.IllegalArgumentException - if either of the objects to append isn't an array.

openURLReader

public static java.io.Reader openURLReader(java.net.URL url)
                                    throws java.io.IOException

Returns a Reader for the specified URL based on the InputStream and content charset obtained by opening a connection to the URL.

Throws:

java.io.IOException

getContentCharset

public static java.lang.String getContentCharset(java.net.URLConnection conn)

Extracts the charset name from the content type, if given; otherwise returns null.

getContentCharset

public static java.lang.String getContentCharset(java.lang.String contentType)

Extracts the charset name from the content type, if given; otherwise returns null.

fileLines

public static java.util.Queue<java.lang.String> fileLines(java.lang.String url)

Returns the contents of a text file (or similar resource) as a queue of lines.

fileLines

public static java.util.Queue<java.lang.String> fileLines(java.net.URL url)

Returns the contents of a text file (or similar resource) as a queue of lines.

readAllLines

public static java.util.Queue<java.lang.String> readAllLines(java.io.Reader r)

Reads lines of text from a Reader until there are no more, then returns them in a queue.

printLines

public static void printLines(java.lang.String[] lines)

Print the elements of a String[] array to System.out as lines.

askLine

public static java.lang.String askLine(java.lang.String prompt)

Simple, text-based user interaction. askLine prints a prompt to System.out and returns a String containing the next line from System.in.

If askLine blocks when reading, we'd like other threads to be able to run; but that doesn't seem to happen reliably. Presumably, this is a bug. In any case, askLine works around the problem by having a loop that checks whether input is available and sleeps for a second if it isn't.

askLines

public static java.lang.String askLines(java.lang.String prompt)

Prompts for multi-line textual input.

See Also:

askLine(String), readLines()

readLine

public static java.lang.String readLine()

Reads a line from System.in.

See Also:

readLine(InputStream)

readLine

public static java.lang.String readLine(java.io.InputStream is)

Reads a line from an InputStream and returns it as a String. In Java, we seem to have to write this ourself unless we wrap a special stream (or Reader) around whatever we want to read. Here we provide a static method, because that's easier to mix with other operations. The only InputStream method called is read().

readLines

public static java.lang.String readLines()

Reads lines from System.in.

See Also:

readLines(InputStream)

readLines

public static java.lang.String readLines(java.io.InputStream in)

Reads lines up to a blank line, then returns all of the lines, except the blank one, concatenated into one string.

See Also:

readLine(InputStream)

renameToBackup

public static void renameToBackup(java.io.File file)

Renames the file to indicate it is an earlier version so that a new version can then be written. If a file with the desired "backup name" already exists, it is first deleted. At present, the backup name is formed by replacing any extension/type with ".bak".