INetlet

Interface which a class implements to be a netlet.

INetlet allows initialisation, service binding, and termination. Initialisation gives the netlet an interface to its node (INode), and both the signed and unsigned arguments from its descriptor.

The INetlet interface is presented by a netlet to a node. When another netlet accesses the netlet to use a service it gets an IService interface, not an INetlet interface.

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);
    }    
}