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