Table of Contents
This scenario demonstrates how to implement file transfer in a file update/distribution mechanism. It distributes files that are on the file system by sending them to another agent that stores it again. Although the tasks are available in a separate jar you should note that it is only intended as an example since it does not implement security checks other than file-write permission. This demo sends agent DNA files to another agent. This agent stores these files in the directory where the program was started.
The example runs on one habitat. A real-life system would use different habitats on different machines, but this would make the example too complicated. To run the example, go to the <ADK_ROOT>\examples\filetransfer directory [3] (not the bin directory) and type:
set ADK_ROOT=<ADK_ROOT>
..\..\bin\habitat.bat filetransfer-example.xml
Watch the agent send the files. It sends the files at different "part sizes" so one will take a lot more messages than the other. You will see the two DNA files appear in the directory if the agents completed their tasks successfully.
The diagram shows the message flow between SendFileAgent (S) and ReceiveFileAgent (R). The first message is a send-file-request, in which S tells R it wants to send a file. This message includes the filename, format and size of the file to be sent. The exact format of the message is described below.
When R receives the send-file-request, it checks if it can allocate the necessary resources. If this is the case, an agree is returned, otherwise refuse is replied. The only check performed is to check on available disk space. As soon as S receives an agree, the actual sending of the file will occur.
Sending the file is done through several parallel tasks that transfer a piece of the file to the other agents. The file is split up to prevent the computer's RAM from completely filling up in case an extremely large file is sent. The number of parallel tasks and the packet size are both configurable.
Please note that this diagram is a simplification of the actual implementation. It does not show the SendFilePartTasks running in parallel, nor show the handling of a possibly lost connection. For a more elaborate description, read the tasks section.
The example uses the following tasks.
SendFileTask
SendFilePartTask
ReceiveFileServerTask
ReceiveFileTask
In the API documentation, refer to javadoc. For actual implementation, see the source.
Since the system is push-oriented, the SendFileTask takes initiative by sending a send-file-request to the other agent. If the other agent replies refuse, the task fails; if it replies agree, the agent will start sending the file. After an agree is received, several SendFilePartTasks are started. These tasks all contain part of the file to be sent. If a SendFilePartTask fails, the SendFileTask fails. If a SendFilePartTask succeeds, it checks if more parts need to be sent. If it has just sent the last part, the SentFileTask will succeed, otherwise the task will take a new part of the file and send that.
The SendFilePartTask's responsibility is to send a piece of the file. The SendFilePartTask is started by the SentFileTask and gets information about the part of the file it should send:
the offset
the maximum size of the part
the sequence number
The task uses a SendMessageTask to send the file. After this task has been started, the SendFilePartTask waits for acknowledgement or a timeout of the task. If the task times out, it will be restarted (after checking if the maximum number of restarts has not been reached). This means that the receiving task could receive multiple copies of the same part, but it should be able to handle this.
The SendFilePartTask also listens for delivery reports from the ARE. These reports signal that a message could not be delivered to another habitat. The task will retry until the maximum number of retries has been reached. If the task receives an acknowledgement, it will succeed.
The ReceiveFileServerTask controls a number of ReceiveFileTasks to which it dispatches the actual receiving of the file. The ReceiveFileServerTask makes it possible to receive multiple files simultaneously. If the agent only needs to receive one file at a time, a single ReceiveFileTask is sufficient.
A ReceiveFileTask can be started standalone or as a subtask of a ReceiveFileServerTask. If the ReceiveFileTask is able to receive the file described in the sendfile request (checking directory write permissions, diskspace, etc.) it opens a RandomAccessFile to store the file and replies agree to the sender of the request. If storing the file seems impossible a refuse is sent. If it takes too long before a new filepart arrives, the task will time out and fail. This could happen if the connection is broken.
Also refer to the chapter on Communicating with Agents in the Developer's Guide for a general discussion on messaging.
All values are coded as constants in com.tryllian.filetransfer.MessageConstants.
Sendfile request. The initial message.
Table 10.1.
Subject | send-file | |
Performative | request | |
Content-Keys | filename | the name of the file that will be sent |
fileformat | the format of the file | |
filesize | the size of the file in bytes | |
filedescription | a description of the file |
Sendfile reply. The answer to the initial request.
Table 10.2.
Subject | send-file | |
Performative | agree/refuse | |
Content-Keys | reason | holds reason in case of a refuse |
Filepart. A message containing a part of the file that is being sent.
Table 10.3.
Subject | filepart | |
Performative | request | |
Content-Keys | sequence-number | the sequence number |
payload | base64 encoded part of the file being transferred | |
payload-size | the size of this part in bytes before base64 encoding it | |
offset | the location of this part in the file | |
last-message | boolean to signal if this is the last part or not |
Filepart reply. A reply to the message that contained a part of the file.
Table 10.4.
Subject | filepart-reply | |
Performative | agree/refuse | |
Content-Keys | sequence-number | the sequence number of the message to which this message is an acknowlegement |
reason | the reason in case of refuse |
[3] You have to run this example from its own directory because it uses relative paths to load the files it transfers.