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.

### Field Summary

Fields
`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

Constructors
Constructor and Description
`Notify()` Constructs a Notify object with no destinations.
`Notify(Vector destinations)` Constructs a Notify object with the specified destinations.

### Method Summary

Methods
`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 `Deliver`y 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.