IAdvancedConsoleFacet

Once you've spent some time with IConsoleFacet you may find it has several shortcomings. These are addressed in IAdvancedConsoleFacet which does everything that IConsoleFacet does, plus a bit more.

Before we go into the details of IAdvancedConsoleFacet we should own up to a small fib. Previously we said that when the launcher connects to a service it looks for an IConsoleFacet and uses that as its console interface. Actually, this isn't strictly true. What it really does is look for an IAdvancedConsoleFacet, and if it that's not there looks for an IConsoleFacet instead, and if it find that then it wraps it up as its more advanced sibling and uses that.

Now, here's what IAdvancedConsoleFacet gives us extra:

• Overloaded commands. Like object-oriented method overloading, it allows us to have the same command invoked with different kinds of properties.
• I/O streams. It allows a command to read input streams and return output streams. Very useful if you want to upload a large file from the launcher, or get a running display of output.
• Custom property types. No longer are we restricted to the launcher's Property object interpretation such as {long:1024}. Now we can make up our own application-specific properties such as {my_list:one,two,three} and use these on the launcher command line. This is achieved by the IAdvancedConsoleFacet providing a decoder which converts the command line string (in this case one,two,three) into Property object (in this case perhaps a String in a particular format or just an Object).

Here is the interface in full:

public interface IAdvancedConsoleFacet extends IRemote
{
    /** When there is a problem decoding an application-specific property.
     */
    public class DecodeException extends Exception
    {
        public DecodeException(String msg)
        {
            super(msg);
        }
        public DecodeException() {}
    }

    /**
     *  Fetch the list of supported commands.
     */
    public CommandDescription[] getCommands();

    /** Execute a command.
     * @param command  The command name.
     * @param arguments  All the Property arguments needed to invoke the
     *     command.
     * @param stdin  Some input stream from which the command might like
     *     to read bytes. This parameter must not be null; at least create
     *     an IInputStream with no data.
     * @param stdout  Some output stream though which the command can return
     *     bytes. This parameter must not be <tt>null</tt> although
     *     it is of course allowed to throw the bytes away if it wishes.
     * @return  An array of return values from the command.
     * @throws CommandException  If anything goes wrong executing the
     *     command.
     */
    public Property[] execCommand(CommandDescription command, Property[] arguments,
        IInputStream stdin, IOutputStream stdout) throws CommandException;

    /** Decode an application-specific property from a string. 
     * See this interface's description for an example of this.
     * @param type  The application-specific type given on the launcher
     *     (or other) command line.
     * @param encoded  The string sequence given on the command line, which
     *     this interface needs to interpret.
     * @return  The string, decoded to become a property.
     * @throws DecodeException  If the encoded string cannot be interpretted.
     */
    public Property decode(String type, String encoded) throws DecodeException;

    /** Get a list of application-specific types which can be decoded
     * with this console interface.
     * @return  Each element of the returned array is a string which could
     *     be the <tt>type</tt> parameter of the <tt>decode()</tt> method
     *     of this interface.
     */
    public String[] getDecoders();
}

Finally the advanced console facet has the expected useful tools. Have a look at...

• AdvancedConsoleFacetFactory for turning any ordinary facet into an advanced console facet via introspection;
• JointAdvancedConsoleFacet for combining two advanced console facets; and
• WrappedAdvancedConsoleFacet for turning an IConsoleFacet into an IAdvancedConsoleFacet.