PIRL.Conductor
Class Notify

java.lang.Object
  PIRL.Conductor.Notify

public class Notify
extends Object

Notify is a mechanism for delivering messages to destinations.

Each of Notify's destinations is represented by a URI address which specifies the recipient of the message and the protocol to be used to deliver it. The mailto URI, which specifies how to deliver an e-mail message, is typical. If the address does not specify a protocol, it is treated as a mailto URI. If, for any reason, a destination cannot be used during the delivery of the notice, that destination is added to a Vector of undeliverable destinations.

Notify's message consists of text that is delivered to each destination via a URLConnection. The message contents may be provided by a resource specifier which may be a local resource - either a system filename or path within an enclosing jar file - or an external resource via a URL. The message may also be specified directly on the command line. The size of the message may be limited to a maximum number of lines and the number of last lines to always be retained in the message body may also be controlled. This is particularly useful for preventing unexpectedly large message files from causing memory exhaustion while still delivering the beginning and end of the message.

For mailto deliveries a From and Reply-To address and a Subject line may be provided.

Version:

1.25

Author:

Christian Schaller - UA/PIRL

Field Summary

static int	CANNOT_READ_MESSAGE_FILE Exit status values.
static String	DEFAULT_SMTP_SERVER
static char	FILENAME_MARKER Marker for a message source as opposed to a message string.
static String	ID
static int	ILLEGAL_SYNTAX Exit status values.
static int	NO_DESTINATION Exit status values.
static int	SUCCESS Exit status values.

Constructor Summary

Notify()
Constructs a Notify object with no destinations.

Notify(Vector destinations)
Constructs a Notify object with the specified destinations.

Method Summary

int	Deliver() Delivers the notice to each destination.
int	Deliver(Vector destinations) Delivers the notice to each destination.
Vector	Destinations() Gets the list of destinations to which the notice will be delivered.
Notify	Destinations(Vector destinations) Sets the list of destinations to which the message will be delivered.
String	From() Gets the From address for e-mail deliveries of the notice.
Notify	From(String from_address) Sets the From address for e-mail deliveries of the notice.
static void	main(String[] args) Processes the command line arguments.
int	Max_Last_Lines() Gets the maximum number of message last lines to be delivered.
Notify	Max_Last_Lines(int max_lines) Sets the maximum number of message last lines to be delivered.
int	Max_Message_Lines() Gets the maximum number of message lines to be delivered.
Notify	Max_Message_Lines(int max_lines) Sets the maximum number of message lines to be delivered.
Notify	Message_Source(String source) Reads a message from a named source.
Notify	Message_Source(String source, boolean convert_escapes, boolean append) Reads a message from a named source.
String	Message() Gets the message to be delivered.
Notify	Message(String message) Sets the message to be delivered.
Notify	Message(String message, boolean convert_escapes, boolean append) Sets the message to be delivered.
String	Reply_To() Gets the Reply-To address for e-mail deliveries of the notice.
Notify	Reply_To(String reply_to_address) Sets the Reply-To address for e-mail deliveries of the notice.
String	SMTP_Server() Gets the current SMTP Server setting.
Notify	SMTP_Server(String smtp_server) Sets the outgoing SMTP server hostname.
String	Subject() Gets the Subject line for e-mail deliveries of the notice.
Notify	Subject(String subject_line) Sets the Subject line for e-mail deliveries of the notice.
Vector	Undeliverable() Gets the list of destinations to which the notice could not be delivered.
static void	Usage(int exit_status) Prints the command line usage.

Methods inherited from class java.lang.Object

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

Field Detail

ID

public static final String ID

See Also:

Constant Field Values

FILENAME_MARKER

public static final char FILENAME_MARKER

Marker for a message source as opposed to a message string.

See Also:

Constant Field Values

SUCCESS

public static final int SUCCESS

Exit status values.

See Also:

Constant Field Values

ILLEGAL_SYNTAX

public static final int ILLEGAL_SYNTAX

Exit status values.

See Also:

Constant Field Values

NO_DESTINATION

public static final int NO_DESTINATION

Exit status values.

See Also:

Constant Field Values

CANNOT_READ_MESSAGE_FILE

public static final int CANNOT_READ_MESSAGE_FILE

Exit status values.

See Also:

Constant Field Values

DEFAULT_SMTP_SERVER

public static final String DEFAULT_SMTP_SERVER

See Also:

Constant Field Values

Constructor Detail

Notify

public Notify(Vector destinations)

Constructs a Notify object with the specified destinations.

Parameters:

destinations - The Vector of destinations to which the notification message will be delivered.

Notify

public Notify()

Constructs a Notify object with no destinations.

Method Detail

SMTP_Server

public Notify SMTP_Server(String smtp_server)

Sets the outgoing SMTP server hostname.

Parameters:

smtp_server - The hostname of the outgoing SMTP server. The default hostname is DEFAULT_SMTP_SERVER.

Returns:

This Notify object.

SMTP_Server

public String SMTP_Server()

Gets the current SMTP Server setting.

Returns:

The SMTP hostname String

Destinations

public Vector Destinations()

Gets the list of destinations to which the notice will be delivered.

Notify will attempt to deliver to each of these destinations on the next invocation of the Deliver() method. A failed delivery will add that destination to the list of undeliverable destinations.

Returns:

the destinations list as a Vector

See Also:

Undeliverable()

Destinations

public Notify Destinations(Vector destinations)

Sets the list of destinations to which the message will be delivered.

Redundant destination addresses are removed from the list.

Setting the destinations list has the side effect of resetting the list of undeliverable destinations.

Parameters:

destinations - The Vector of destination URIs.

Returns:

This Notify object.

See Also:

Undeliverable()

Undeliverable

public Vector Undeliverable()

Gets the list of destinations to which the notice could not be delivered.

Whenever a Delivery cycle is done destinations to which the notice could not be delivered - for whatever reason - are added to a list of undeliverable destinations.

Returns:

The Vector of undeliverable destinations.

See Also:

Deliver()

From

public String From()

Gets the From address for e-mail deliveries of the notice.

The From address is not used for other types of deliveries.

Returns:

The From address String.

From

public Notify From(String from_address)

Sets the From address for e-mail deliveries of the notice.

The From address is not used for other types of deliveries. Furthermore, if the From address is null, it will not be used at all. In this case, the underlying Java e-mail delivery mechanism (the mailto URL handler) will attempt to use an appropriate From address based on the owner of the Notify process.

Note that there is no checking provided to ensure that the From address is a valid e-mail address. The address should be a regular e-mail address and not a mailto URL.

Parameters:

from_address - The From address String.

Returns:

This Notify object.

Reply_To

public String Reply_To()

Gets the Reply-To address for e-mail deliveries of the notice.

The Reply-To address is not used for other types of deliveries.

Returns:

The Reply-To address String (may be null).

Reply_To

public Notify Reply_To(String reply_to_address)

Sets the Reply-To address for e-mail deliveries of the notice.

The Reply-To address is not used for other types of deliveries. Furthermore, if the Reply-To address is null, it will not be used at all.

Note that there is no checking provided to ensure that the Reply-To address is a valid e-mail address. The address should be a regular e-mail address and not a mailto URL.

Parameters:

reply_to_address - The Reply-To address String.

Returns:

This Notify object.

Subject

public String Subject()

Gets the Subject line for e-mail deliveries of the notice.

The Subject line is not used for other types of deliveries.

Returns:

The Subject line String.

Subject

public Notify Subject(String subject_line)

Sets the Subject line for e-mail deliveries of the notice.

The Subject line is not used for other types of deliveries. Furthermore, if the Subject line is null, it will not be used at all.

Parameters:

subject_line - The Subject line String.

Returns:

This Notify object.

Max_Message_Lines

public int Max_Message_Lines()

Gets the maximum number of message lines to be delivered.

Returns:

The maximum number of message lines to be delivered.

Max_Message_Lines

public Notify Max_Message_Lines(int max_lines)

Sets the maximum number of message lines to be delivered.

Parameters:

max_lines - The maximum number of message lines to be delivered. If this is less than or equal to 0, the maximum integer value will be used. If it is less than Max_Last_Lines() then Max_Last_Lines() will be lowered to the same value and there will be no initial message lines.

Returns:

This Notify object.

Max_Last_Lines

public int Max_Last_Lines()

Gets the maximum number of message last lines to be delivered.

Returns:

The maximum number of message last lines to be delivered.

Max_Last_Lines

public Notify Max_Last_Lines(int max_lines)

Sets the maximum number of message last lines to be delivered.

Parameters:

max_lines - The maximum number of message lines to be delivered. If this is less than 0, 0 will be used. If it is greater than Max_Message_Lines() then Max_Message_Lines() will be used and there will be no initial message lines.

Returns:

This Notify object.

Message

public String Message()

Gets the message to be delivered.

The message is composed of two parts: The initial lines of the message and the last lines of the message. No more than Max_Message_Lines() user provided lines - where a line is a sequence of characters terminated by a line separator - will be included. If this limit is exceeded additional lines will be dropped; however, the last Max_Last_Lines() lines will always be included. In this case the initial lines will be separated from the last lines by a line of the form:

... [number> lines omitted]

where number> is number of user provided lines that were omitted from the message.

Returns:

The message String.

Message_Source

public Notify Message_Source(String source,
                             boolean convert_escapes,
                             boolean append)
                      throws IOException

Reads a message from a named source.

The source can be the name of a local file, the full pathname to that file, the name of a file contained within a jar that packages Notify, a file URL that points to a local file, or a URL that points to an external resource.

Only Max_Message_Lines() lines - where a line is a sequence of characters terminated by a line separator - will be retained. The last Max_Last_Lines() lines from the source will be saved separately so they will be included in the delivered message regardless of the total number of lines available from the source (@see #Message()).

Parameters:

source - The name of the message file. If null an empty message is used.

convert_escapes - If true, any escape sequences in the message are converted to their character equivalents; otherwise the string is unchanged.

append - If true, the message is appended to any existing message; otherwise the any existing message is replaced.

Returns:

This Notify object.

Throws:

IOException - If an input stream cannot be obtained from the message source or if there is a problem reading from the input stream.

See Also:

Streams.Get_Stream(String), String_Buffer.escape_to_special()

Message_Source

public Notify Message_Source(String source)
                      throws IOException

Reads a message from a named source.

Any escape sequences are converted and any existing message appended.

Parameters:

source - The name of the message file. If null the message is set to the empty String.

Returns:

This Notify object.

Throws:

IOException - If an input stream cannot be obtained from the message source or if there is a problem reading from the input stream.

See Also:

Message_Source(String, boolean, boolean)

Message

public Notify Message(String message,
                      boolean convert_escapes,
                      boolean append)

Sets the message to be delivered.

Parameters:

message - The message String. A null message is empty.

convert_escapes - If true, any escape sequences in the message are converted to their character equivalents; otherwise the string is unchanged.

append - If true, the message is appended to any existing message; otherwise an existing message is replaced.

Returns:

This Notify object.

See Also:

String_Buffer.escape_to_special()

Message

public Notify Message(String message)

Sets the message to be delivered.

Any escape sequences are expanded. Any existing message is cleared.

Parameters:

message - The message String to be delivered. A null message is empty.

Returns:

This Notify object.

See Also:

Message(String, boolean, boolean)

Deliver

public int Deliver()

Delivers the notice to each destination.

The list of undeliverable destinations (destinations for which, for whatever reason, the delivery could not be made) is cleared prior to delivery.

Returns:

The number of successful destinations.

See Also:

Undeliverable()

Deliver

public int Deliver(Vector destinations)

Delivers the notice to each destination.

Parameters:

destinations - The Vector of desinations.

Returns:

The number of successful destinations.

See Also:

Deliver()

main

public static void main(String[] args)

Processes the command line arguments.

All error messages are written to stderr. If any destinations are undeliverable, they are listed.

The exit status will be one of:

• 0 - SUCCESS
• 1 - ILLEGAL_SYNTAX
• 2 - NO_DESTINATION
• 3 - CANNOT_READ_MESSAGE_FILE

Parameters:

args - The array of command line arguments.

See Also:

Usage(int)

Usage

public static void Usage(int exit_status)

Prints the command line usage.

Usage: Notify <Switches>
  Switches -
    [-To] <address | URI>[,...]
    [-From <address>] (default: username)
    [-Reply-to <address>]
    [-Subject <subject line>]
    [-Message <message> | @<source>]
    [-Limit[_Last] <lines> (default: message 1000, last 50)
    [-Outgoing_server] <hostname> (default: localhost)
    [-Version
    [-Help

At least one destination (To) address must be provided. Each destination is treated as a URI. If the address does not specify a protocol, it is treated as a mailto URI. A comma separated list of addresses may be provided.

The From and Reply-to addresses are optional and only used in association with mailto destinations. By default the user's address, if available, will be used for the From address. If no Reply-to address is provided, none will be used.

The Subject line is optional and only used in association with mailto destinations. If none is provided, none will be used.

To message may be any text. If the message text begins with the FILENAME_MARKER ('@') the text without the marker is interpreted as a file or URL resource specifiction. This may be a local resource, either a system filename or path within an enclosing jar file, or it may refer to an external resource via a URL.

Multiple messages may be specified. They will be concatenated in the order they occur on the command line.

The size of the message may be limited to a maximum number of lines. Excess lines will be dropped but the last lines of the message - the number may be specified - will be retained.

The hostname of an SMTP server to which the message will be transmitted may be specified. The default hostname is "localhost".

N.B.: Command line options are applied in the order in which they are encountered. Thus, for example, message limit values should be set before the message body is specified.

The -Version option causes the class ID to be written to stdout followed by a System.exit.

N.B.: This method always results in a System.exit.

Parameters:

exit_status - The exit status code. The usage statement is written to the stdout if the exit_status is SUCCESS, otherwise to stderr.