ANTS v2.0 API

ants.core
Class Application

java.lang.Object
  |
  +--ants.core.Entity
        |
        +--ants.core.Application
Direct Known Subclasses:
DanteClient, DanteServer, DynamicRouteApp, MobileApplication, MulticastApplication, PingApplication, PongApplication, StatsApplication, StatsApplication, Tester

public abstract class Application
extends Entity

Abstract node application. An Application is an end-point for capsules. Capsules are sent and received via the Node associated with the Application.

Applications understand the '-port' KeyArg for setting their port address on the Node. If no '-port' is provided an available port will be found and allocated to the Application. getPort() will retrieve the port number.

In addition, applications understand the '-principal' KeyArg for setting the security principal. In the abscence of this keyarg, the principal defaults to SecurityDefaults.LOCAL_USERS. Some common principles are described in SecurityDefaults. Applications are started after the Node has completed initialization.

Author:
David Wetherall, Utah Janos Team
See Also:
SecurityDefaults

Field Summary
static java.lang.String[] defaults
          Default KeyArgs for an application.
 
Constructor Summary
Application()
          All applications must have a no-arg constructor as the Node invokes Class.newInstance() to create the application.
 
Method Summary
 int getDefaultResources()
          Deprecated. use getDefaultTTL()
 int getDefaultTTL()
           
 Node getNode()
          Redundant accessor method
 int getNodeAddress()
          Return logical ANTS address of the node hosting this application.
 short getPort()
          Get the integer port identifer for this Application.
 Principal getPrincipal()
          Returns the security principal.
 void receive(Capsule cap)
          Callback for packets that are delivered to this application.
 boolean send(Capsule cap)
          Send the given capsule.
 boolean send(Capsule cap, int ttl)
          Send the given capsule with the given resource limit.
 void setArgs(KeyArgs k)
          Parse command line arguments for this application.
 void setDefaultResources(int r)
          Deprecated. use setDefaultTTL(int)
 void setDefaultTTL(int ttl)
           
abstract  void start()
          Start this Application rolling.
 Node thisNode()
          Return the Node interface customized for this application.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

defaults

public static final java.lang.String[] defaults
Default KeyArgs for an application. Sets port to 0.
Constructor Detail

Application

public Application()
All applications must have a no-arg constructor as the Node invokes Class.newInstance() to create the application.
Method Detail

getDefaultTTL

public int getDefaultTTL()

setDefaultTTL

public void setDefaultTTL(int ttl)

getDefaultResources

public int getDefaultResources()
Deprecated. use getDefaultTTL()


setDefaultResources

public void setDefaultResources(int r)
Deprecated. use setDefaultTTL(int)


getPrincipal

public final Principal getPrincipal()
Returns the security principal.
See Also:
AppBooster#run(Flow,String[],CommSpaceHandle)

getPort

public short getPort()
Get the integer port identifer for this Application. Each application on a node has a unique "port" identifier which capsules use to direct themselves to particular applications on a node.

thisNode

public Node thisNode()
Return the Node interface customized for this application.

getNode

public Node getNode()
Redundant accessor method
See Also:
thisNode()

getNodeAddress

public int getNodeAddress()
Return logical ANTS address of the node hosting this application. Unlike Node.getAddress() which may return 0 (if the Node's address is not yet defined), this version will block for a while until it gets a valid address, or if it gets tired of waiting, it will throw a NodeHasNoAddressError.
See Also:
Node.getAddress()

send

public boolean send(Capsule cap)
Send the given capsule.

The capsule is sent with the default TTL for this application.

Parameters:
cap - the Capsule to send. XXX state of Xdr?
See Also:
send(Capsule,int), #ttl

send

public boolean send(Capsule cap,
                    int ttl)
Send the given capsule with the given resource limit.

The capsule is primed (that is, the 'from address' and ttl are set), and then marshalled and sent to the protocol flow that is responsible for the Capsule.

XXX this shouldn't return true/false. It should succeed or throw an exception.

Parameters:
ttl - the TTL to give the Capsule.
See Also:
#ttl, Capsule#prime(int,int), Node.send(Capsule), PrimordialNode.getProtocolQueue()

receive

public void receive(Capsule cap)
Callback for packets that are delivered to this application. This does nothing, so the default behavior for the application is to drop delivered packets on the floor.
Parameters:
cap - the Capsule that got delivered. XXX state of Xdr?

start

public abstract void start()
                    throws java.lang.Exception
Start this Application rolling. This is invoked once by the Node after it has been initialized.

Note that implementations of start should just set things up. If the application wants to do things like send packets, this function should start a new thread to do that. Creating a GUI and associating callbacks is a good thing to do here.

XXX mostly stuff that could just be done in the no-arg constructor, no?


setArgs

public void setArgs(KeyArgs k)
             throws InvalidKeyArgsException
Parse command line arguments for this application. Understands the -port option and the -principal option.

It is guaranteed that this method will be invoked before the application starts running (i.e. shortly after the constructor is invoked).

XXX A security issue related to this method is that a mallicious application could change its parameters by invoking this method after startup. For example, the application could change its principal to "Administrator". To avoid any pitfalls, the local copies of the argument variables should be ignored once control is given over to the application's start method

See Also:
#port, KeyArgs

toString

public java.lang.String toString()
Overrides:
toString in class Entity

ANTS v2.0 API

This documentation is Copyright (C) 1998-2001 The University of Utah and the University of Washington. All Rights Reserved. See the individual source files for distribution terms.
Documentation, software, and mailing lists for ANTS v2.0 can be found at the Janos Project: http://www.cs.utah.edu/flux/janos/