On-line tools

Socket Interface

Description

The TOTEM toolbox can execute events sent from a remote place through a socket interface. In this mode, the toolbox acts as a server and processes events coming from another machine on the network. Once a client is connected, it can send XML scenario events to the toolbox which executes them before returning a result.

For example the socket interface can be used online in a network for path computation : LSPCreation events are sent to the server which will respond by sending the computed path.

Message format

The messages that the clients should send consist of XML scenario events described in section 9. However it is important to note that for implementations reasons a single event sent through the socket interface must be written in only one text line.

Once the event has been executed by the toolbox, a response message is sent back to the client. The response message is also always transmitted in only one text line. It has the following format (shown here in multiple lines for readability):

<result>
    <command>
        ...
    </command>
    <output>
        <object>
            ...
        </object>
        <message>
            ...
        </message>
    </output>
    <status>
        ...
    </status>
    <exceptions>
        ...
    </exceptions>
</result>

The command element is a copy of the XML event sent by the client. The output element contains two subelements: object and message. These are respectively a representation of an object and a text message both related to the execution of the event. The text message is the same message that is written on standard output when the event is executed locally. For example, if a LSPCreation event is correctly executed, the object will be the XML representation of the new LSP and the message will be a string representation of the new LSP path followed by a list of preemped LSP ids. Note that both subelements are optional.

The status element can be either OK or FAILED depending on the success of the event execution. If the status is FAILED, the event was not correctly executed because of an exception. The exception is then described in the exceptions element. In this case, it contains one (or more) subelement(s) of the following form:

<exception class="...">
    ...
</exception>

The class attribute correspond to the class of the exception and the content of the exception element is the message of the exception.

How to use it

The toolbox socket interface can be started either by means of a scenario event, either in the GUI. The corresponding scenario event is startScenarioServer. An example of a scenario that starts the server is LSPComputationServer.xml located in the examples directory of the root TOTEM folder.

To start the server from the GUI, click on the Start server item under the Scenario menu. The result of every event executed from the remote place will be visible in the GUI.

The toolbox is also shipped with a simple client. This client sends a complete scenario to a toolbox running the socket interface. It takes three mandatory command line arguments (host, port and filename) and one optional (delay). The client establishes a connection with the given host on the given port, reads the scenario given by its filename and sends it to the server one event at a time. If delay is also given, the client will wait a certain time between each event.

To build the client, use the specific ant task:

ant build-socketclient

The jar file containing the client is then located in dist/socketclient.jar under the TOTEM root folder. You can start the client by using the script socketclient.sh.

Loading a domain from network

Description

TOTEM can be feeded with a domain that comes from network. This feature was originally developed to allow network discovery tools to feed the toolbox with a real domain.

In this operational mode, TOTEM acts as a client and it connects to a topology server. Once the server is ready, it sends a topology to the toolbox. The topology is loaded as it is being received. Note that the domain must be in the TOTEM XML format (see section 3).

How to use it

A domain can be loaded from a remote place either by using the corresponding scenario event (loadDistantDomain event), either by using the GUI (use "Load Topology from network" under the "File" menu). In both cases, the server host and port should be provided. If no server is present at the given host and port, this will result in an execution error. If the server is present, the connection will be established and TOTEM will start waiting for the topology to be received.

A simple topology server is provided as an example. It is located in the class TopologyServer in the be.ac.ulg.montefiore.run.totem.core package. This server sends a given topology file to a TOTEM toolbox instance that connects to it. It has two mandatory arguments: the port on which to listen for new connections and the filename from which to read the topology.

To build the server, use the specific ant task:

ant build-toposerver

The jar file containing the server is then located in dist/toposerver.jar under the TOTEM root folder. You can start the server by using the script toposerver.sh.