org.jtrix.base.INetlet

This is the interface which allows the node to communicate with a netlet. Notice that the initialise() method can return any arbitrary data. This is for when one netlet runs another; then the executing netlet can get back anything in return. But we don't need this if we're running a netlet from Jnode, because it's just interested in a successful start, and that means not throwing an exception.

public interface INetlet extends IFacetCollection
{
    /** Allows the node to initialise the netlet. Called at most once.
     *
     * @param node  Interface to the netlet's view of the node.
     * @param parameter_bean   Bean object for parameters from the descriptor.
     *     Since this comes from the descriptor, if the descriptor is signed
     *     then we can assume this data is equally trusted.
     * @param unsigned_arg  Arbituary data that arrived with the descriptor,
     *     but external to it. Hence it is not signed (unlike the
     *     <tt>parameter_bean</tt>) and it is therefore untrusted.
     * @throws InitialiseException  In case of failure an exception is thrown;
     *     the netlet can then expect to be terminated.
     * @return Some arbitrary data; it is determined by the implementation and
     *     the context; it must be properly intepreted by whoever executed
     *     this netlet. Null is a valid, non-error return.
     */
    public byte[] initialise(INode node,
                             Object parameter_bean,
                             byte[] unsigned_arg) throws InitialiseException;
    
    /** Allows the node to request termination of netlet.  Called before
     * netlet is actually shutdown regardless of initialisation state. May be
     * aborted without notice if takes too long. No threads should be left
     * when this function returns, otherwise they will be shut down, too.
     *
     * @param time  The time when the node will force a terminate even if the
     *     netlet has not yet terminated. This is seconds since 1 Jan 1970
     *     GMT.  When negative there is no fixed time, but the node may then
     *     terminate at any time. If this number is 0 then the node is
     *     informing the netlet that connections may be terminated
     *     asynchronously.
     * @param progress  The interface the netlet uses to notify the node of
     *     the progress of the termination. If the time is 0 then there is no
     *     reason to notify the node of progress.
     */
    public void terminate(long time, IShutdownProgress progress);
    
    /** Requests a service connection from this netlet.
     *
     * @param warrant   The warrant that was used to bind to this netlet.
     *     The implementation can assume that the node has checked the warrant
     *     by the time the implementation is called.
     * @param consumer  The consumer side of the connection. It is through
     *     this that the calling netlet offers its side of the two-way service
     *     connection.
     * @return  This side of the service connection. A null return is
     *     interpreted as a declined bind.
     */
    public IService bindService(Warrant warrant, IService consumer)
        throws ServiceBindException;    

    /** Callback interface for the progress of a shutdown. This interface
     * will be given to a netlet by the node when it is requested to terminate.
     * The netlet can then use it inform the node of its shutdown progress.
     * Even though a node gives us a certain amount of time to shutdown
     * if we're seen to progressing well and we seem to need some extra time
     * then the node's administrator might be benevolent and give us a little
     * leeway.
     */
    public interface IShutdownProgress extends IRemote
    {
        /** Tell the node how we're progressing with our own shutdown.
         * @param progress  A percentage of the progress of the shutdown.
         */
        public void performed(double progress);
    }    
}