Peer support

The IPeerSupport plugin, provided by both the Worker and Manager, allows a netlet to link up to its peers in the application and perform other sundry tasks:

public interface IPeerSupport
{
    /**
     *  Provides a server handle for the current leader netlet.  Waits
     *  up to <code>timeout</code> milliseconds for a leader to be
     *  elected if there is currently no leader.  Returns null if no
     *  leader exists when the timeout expires.
     * @param timeout   In milliseconds. 
     */
    public IServerHandle locateLeader(long timeout);

    /**
     *  Returns handles for the access points being serviced by this
     *  netlet.
     */
    public IAccessPointHandle[] listAccessPoints();

    /**
     *  List all netlets which can support the given service type.
     *  This is the set of managers or workers who have indicated
     *  service eligibility for the type, for example, by plugging in
     *  the right service provider.
     */
    public IServerHandle[] listServers(String service_type);

    /**
     *  Make this netlet eligible (or not) to serve the specified
     *  service.  New access points for the service may then connect
     *  to this netlet. It is likely this is not used directly, as it is
     *  called by any IServiceManager when an IServiceProvider or
     *  ISimpleServiceProvider plugin is added or removed.
     * @param service_type       Name of service.
     * @param willing_to_handle  Whether this netlet can handle the service.
     */
    public void setServiceEligibility(String service_type,
                                      boolean willing_to_handle);

    /**
     *  Set simple string-based status output for this netlet.
     *  It can be read from IManagedHandle.
     */
    public void setSimpleStatus(String status);

    /**
     *  Set complex property-based output for this netlet.
     *  It can be read from IManagedHandle.
     */
    public void setComplexStatus(PropertySet status);

    /**
     *  Return this netlet's label, as assigned by its creator at
     *  creation time.
     */
    public String getLabel();

    /** Retrieve Beatrix-provided console, if we want to merge in our own
     * commands.
     */
    public IConsoleFacet getStandardConsole();

    /**
     *  Creates a client session to be given to other services
     *  upon binding.
     * @param critical If true then this is a critical
     *                 service and termination of the service
     *                 results in the netlet terminating.
     */
    public IService createClientSession(boolean critical);

    /**
     *  Create a service session which implements the "standard"
     *  facets supported by the framework.  This can be used as a tool
     *  by normal user sessions.  The supplied flag indicates whether
     *  standard administrative mode facets should be included.
     * @param session  Reciprocating service session.
     * @param admin    Flag to indicate whether admin facets should be
     *                 included in the returned session.
     * @return    Service session incorporating all the standard
     *            facets, possibly including the admin facets.
     */
    public IService createStandardServiceSession(IService session, boolean admin);
     
    /** Ask the node for this netlet be terminated.
     */
    public void requestTermination();

    /** Get a reference to the node on which this netlet is running.
     */
    public INode getLocalNode();

    /** Check whether a warrant belongs to this application and is signed.
     *  @param warrant  Warrant to be checked
     *  @param require_sid  Whether warrant needs to have a service ID
     *      (and signature).
     */
    public boolean verifyOwnWarrant(Warrant warrant, boolean require_sid);

    /** Access to the applications name, public key, certificates.
     */
    public ApplicationCredentials getApplicationCredentials();

    /** Create a handle to another netlet in this application
     * @param epa the end point address to the other netlet.
     */
    public IServerHandle createServerHandle(EndPointAddress epa);
    
    /** Utility class helping lookup.
     */
    public static class Get
    {
        /** Get the only instance of this plugin in the given manager.
         * Only the first such plugin is returned. If there isn't one then
         * an ArrayIndexOutOfBoundsException is thrown.
         */
        public static IPeerSupport one(IPluginManager pm)
        {
            return ((IPeerSupport)pm.lookup(IPeerSupport.class)[0]);
        } 
        
    }
}

Setting netlet's simple or complex status is an easy way for it make information available to its peers. Once set through this plugin, it can be read by any other netlet which has a handle to it: an IManagedHandle interface.

Also createClientSession() is worth pointing out as a handy tool. It creates a simple service session with no facets which can be used as a reciprocating consumer service session when binding a service. Its boolean argument allows us to specify if, when the remote service terminates, this netlet should also terminate. In the future createClientSession() may automatically add facets to handle financial transactions, making it easier to pay for services.

See Section  for more on the Property and Oid classes.

See Section  for more on IConsoleFacet.