Class app.authkit.envoy.Envoy

All Packages  This Package  Class Hierarchy  Class Search  Index

Class app.authkit.envoy.Envoy

java.lang.Object
   |
   +----app.authkit.envoy.Envoy

Summary

public class  Envoy
     extends java.lang.Object
{
          // Fields 11
     public static final String PROTOCOL_BEGIN_OUTPUT;
     public static final String PROTOCOL_BEGIN_TASK;
     public static final String PROTOCOL_DELIM;
     public static final String PROTOCOL_END_OUTPUT;
     public static final String PROTOCOL_END_TASK;
     public static final String PROTOCOL_NEWLINE;
     public static final String PROTOCOL_STOP;
     public static final String TASKS_BETWEEN;
     public static final String TASKS_BETWEEN_PROP;
     protected int myTaskNumber;
     protected int myTaskStatus;

          // Constructors 1
     public Envoy();

          // Methods 20
     public static void main(String[]);

     protected Authorization buildAuth();
     public void explain(Throwable);
     public int finish();
     protected Authorization getAuthorization();
     protected void groupTaskArgs(Enumeration, Vector, String);
     protected Authorization newAuth();
     public void perform(String[]);
     public void prepare();
     protected void prepareTaskIO();
     protected void protocolBegins();
     protected void protocolEnds();
     protected InputStream protocolIn();
     protected PrintStream protocolOut();
     protected void taskBegins(int, String);
     protected void taskBeginsOutput(int, Task);
     protected void taskEnds(int, Task, int);
     protected void taskEndsOutput(int, Task);
     protected void taskFails(int, Task, int);
     protected int taskPerform(int, Vector);
}

Envoy performs Tasks in a presumably privileged process, reporting on their success.

The Envoy.main() method is the typical entry-point of a privileged process, executed via Authorization.execPrivileged(). As a result, its stdin and stdout (System.in and System.out) are presumed to be connected to a pipe going back to the parent process. The pipe's streams may be coupled together, so closing one may close both. This constrains how the Envoy can communicate results back to its parent. The Envoy is expected to return Task outcomes and data on its stdout, including its own termination status, since the privileged Process in the parent may not provide waitFor() or exitValue().

An Envoy's stderr stream is typically inherited from the parent process, and usually writes to the system console (or its log-file) in a double-clicked app. It writes to stderr when invoked at the command-line or in other-than-double-clicked launches. It may or may not be used by the Envoy protocol. By default, it is not.

The simplest communication protocol for an Envoy is to only return its own "exit status" on stdout, and to discard all output produced by Tasks or external commands. The provided protocol can do more than that, but it's still very simple, if not simple-minded.

Basic Envoy Communication Protocol

The current Envoy communication protocol is brutally simple. It uses the default System I/O streams for its own communications, and sets different streams into System.in, .out, and .err for use by Tasks. It uses the I/O streams as follows:

System.in (stdin): Not used. For Tasks, replaced with an immediate-EOF stream using System.setIn().
System.out (stdout): Send progress messages and result text back to client (the parent process). For Tasks, replaced by either an actual stream or a data sink stream, depending on whether the Task produces output or not. No Task should close System.out.
System.err (stderr): Available for diagnostics, such as stack-traces, etc. This stream is not currently used by the Envoy protocol, though the default Envoy class will print failure stack-traces on it. Tasks may freely print() or println() or printStackTrace() to this stream. No Task should close System.err.

If a Task produces output that is sent back to the parent process, and the Task closes System.out, it will cause a protocol failure. So don't do that. In the future, a safer stream may be used that doesn't actually close the stream on close(), but only flushes it.

As each Task is undertaken, the Envoy sends a task-begin message. As each Task is completed, the Envoy sends a task-end message containing that Task's completion-code. Between task-begin and task-end, an output-producing Task's output data is produced. The output data is bracketed by text-begin and text-end messages.

When all Tasks are complete, the Envoy sends a stop message containing the Envoy's status code, i.e. its exit-code. An EOF on the Envoy stream before a stop message appears is an indication of failure.

The default Envoy behavior is to stop performing Tasks as soon as one of them fails. That is, as soon as a Task returns a non-zero completion code or throws an uncaught exception. The appropriate text-end, task-end, and stop messages are sent when a Task fails.

All task and stop messages are in plain ASCII text, one byte per char. Each message consists of an LF-terminated line, regardless of the host platform's local line-ending convention. Each message contains multiple parameters separated by :'s.

task-begin:N:classname

is the task-begin message:

task-begin: is the literal text "task-begin".
N: is a decimal sequence number, the task-number, starting from 1 and increasing for each task.
classname: is the fully qualified classname of the Task about to be instantiated and performed.

The Task has not yet been loaded or created when this message is sent. Therefore, errors arising from Task instantiation appear as errors belonging to the failing Task, not as errors between Tasks.

text-begin:N

is the optional text-begin message:

text-begin: is the literal text "text-begin".
N: is a decimal sequence number matching the current task-number.

The task's output text follows, until a text-end message. If the task does not produce output, this message is not sent for that task.

text-end:N

is the optional text-end message:

text-end: is the literal text "text-end".
N: is a decimal sequence number matching the current task-number.

This message is sent even when the task produced no output, but only if a text-begin message was sent before.

task-end:N:status

is the task-end message:

task-end: is the literal text "task-end".
N: is a decimal sequence number matching the current task-number.
status: is a decimal number, the Task's status code, which is 0 for success, non-0 for failure.

If the task threw an uncaught exception, the status will be -1.

stop:0:status

is the stop message:

stop: is the literal text "stop".
0: is the apparent task-number, and is always zero.
status: is a decimal number, the Envoy's exit code, which is 0 for success, non-0 for failure.

In general, the Envoy's status is 0 when all Tasks perform() successfully. If the Envoy status is not 0, it is generally the status of the last Task, which presumably failed.

Subclasses of Envoy can use a different protocol, such as one based on XML. The messages are sent by specific methods, which can be overridden. If you use a different protocol, be sure to change the relevant Tool methods, too.

System Properties Used

"file.encoding": implicitly used anywhere a PrintStream is created or parsed, such as captureUntilEOF(), schlepUntilEOF(), or waitForEnvoy(); or anywhere encoded bytes are turned into a String, such as translateEnvoyMessage().
"os.name": in buildAuth() to determine which Authorization class to instantiate.
"envoy.tasks.between": a string value, in perform() to mark a task-name when parsing Task-groups from the args.

See Also: Task, Tool, Authorization

Fields

· TASKS_BETWEEN
Summary | Top

   public static final String TASKS_BETWEEN

The default marker between task-groups in the args received by main() and perform().