ThingWorx Edge Java SDK > ThingWorx Edge Java SDK and File Transfers
ThingWorx Edge Java SDK and File Transfers
The ThingWorx Edge Java SDK supports transfers of files both to and from the ThingWorx platform. File transfers are performed over the websocket connection maintained with the ThingWorx platform, so there is no need for the client application to open another connection.
Configuring File Transfers
To support file transfers in your client application, you must use a FileTransferVirtualThing to enable the functionality and define the directories available for file operations. A virtual directory maps a unique name to an absolute path of a directory in the file system. All subdirectories of the specified directory are exposed to the ThingWorx platform. You can define multiple virtual directories. The directories do not need to be contiguous.
As of v.6.1.0, the Java SDK uses WebSocket compression (per-message-deflate) by default for all WebSocket communications between the edge and the platform, including file transfers. In general, leaving compression enabled reduces bandwidth used by the edge application but requires more memory and CPU usage. Choose whether to leave compression enabled, based on the capabilities of your devices and on the available bandwidth. Compression is enabled in the ClientConfigurator, using the compressionEnabled flag.
You can define the maximum size of a file to be transferred and also retrieve the current setting for the parameter, using the following methods:
setMaxFileSize — Use this method to specify the number of bytes that a file can contain before the transfer is rejected and an error message about the size is displayed. The default maximum size is 1000 bytes.
getMaxFileSize — Use this method to retrieve the current setting for the maximum size of a file to be transferred.
If you attempt to transfer a file that is larger than the maximum file size, the transfer fails with this error message: Size of source file ([source file size]) exceeds allowed maximum of [max file size].
You can also define the amount of data transferred at a time during a file transfer. For example, suppose you have a file that is 5000 bytes. If you specify a block size of 1000 bytes, the file is transferred 1000 bytes at a time. Two methods are available to set and retrieve the current value of this parameter:
setBlockSize — Use this method to specify the amount of data (in bytes) to be transferred at a time during a file transfer. The default block size is 1000 bytes.
getBlockSize — Use this method to retrieve the current setting for the amount of data to be transferred at a time during a file transfer.
Example 21. File Transfer
The following example can be found in the file (located in the directory, samples/com/thingworx/sdk/simple/). The example creates a simple client configuration with the URI of a local ThingWorx platform, an Application Key, and the developer-friendly ignoreSSLErrors set to true. It also sets the maximum file size for a file transfer and the block size for files that are to be separated into chunks for the transfer and reassembled at the destination. It then creates the ConnectedThingClient.
Next, the FileTransferVirtualThing is created. Then, two virtual directories that will act as the root directories in the virtual file system of this application are added. The client is set up to send the BIND message, and then the client is started. Compression is enabled by default so no line of code is needed here to enable it.
The While loop keeps the client “awake” to give a user of ThingWorx Composer the time to send a request. To catch any possible exceptions, a try/catch is set up.
// Create a client config
ClientConfigurator config = new ClientConfigurator();

// Basic configuration. See for additional info.

try {

ConnectedThingClient client = new ConnectedThingClient(config);

FileTransferVirtualThing myThing = new FileTransferVirtualThing(ThingName,
"File Transfer Example", client);

// Add two virtual directories that will act as the root directories in this
// virtual file system of this application.
myThing.addVirtualDirectory("in", "/home/username/files/in");
myThing.addVirtualDirectory("out", "/home/username/files/out");


while(!client.isShutdown()) {

} catch(Exception e) {

Once it connects to the server, this client binds its FileTransferVirtualThing to the appropriate remote thing on the platform. The remote thing on the platform must be created, using the RemoteThingWithFileTransfer thing template. Once bound, the various file system services that are available in the remote thing (inherited from the RemoteThingWithFileTransfer template) can be used to interact with the file system of the client machine.
For example, from the platform, a user can call the BrowseDirectory service of the remote thing. If a forward slash (‘/’) is used for the path parameter, the two configured virtual directories would be returned. If /logs were passed in, a list of the files and directories in <user_home>/logs would be returned.