To handle file transfers, create a virtual directory in the FileTransferExample Entity and in the project directory. The source code used for this example is found in com.thingworx.sdk.examples.FileTransferExample.java.
Set Up File Transfer
Right-click the project. ClickNew. Scroll and selectFolder.
Enter transfer/incoming into the text box at the bottom. ClickFinish.
Repeat steps 1 and 2, but create a folder calledtransfer/outgoing.
Right-click the transfer/outgoing folder. ClickNew. Scroll and selectFile.
Create a file with the name outgoing.txt. Click Finish.
Once the outgoing.txt document is open, add the following text, clickSave, and close the file:
Hello. This is a file coming from the client application.
Navigate to theFileTransferExample.javacode and update the lines below with the appropriate information for yourIP,port, and the admin_key Application Key’skeyIdvalue in Composer:
NOTE: Step 7 is only used for a time constraint of this guide. Best practice is to never use an Application Key for the Administrator. Provide a User with the necessary privileges and add an Application Key to that User.
To support file transfers in your client application, you must use aFileTransferVirtualThingto 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 server. You can define multiple virtual directories. The directories do not need to be contiguous.
The example provided creates the FileTransferVirtualThing with two virtual directories that will act as the root directories in the virtual file system of this application are added. The client is then started as follows:
All of the creations of the payloads have been moved to a helper class (FileTransferExampleHelper.java) to make the design cleaner.
The below table provides insight into some of the helper methods created to separate roles for a cleaner solution.
Create the payload for the call to create the “incoming” directory on the SystemRepository in the ThingWorx Platform.
Create the payload for the call to create the “outgoing” directory on the SystemRepository in the ThingWorx Platform.
Create the payload for the call to copy a file into the incoming directory on the FileTransferExample Thing in the ThingWorx Platform and the provided client application.
Create the payload for the call to copy a file from the outgoing directory in the provided client application to the SystemRepository on the ThingWorx Platform.
Once the connection is made, the script will call the four services. Here, we instruct the server to move the files from one repository to another.
The name of a FileRepository or RemoteThingWithFileTransfer Thing to transfer the file from.
The path specifying the location in the file repository of the source file.
The name of the source file.
The name of a FileRepository or RemoteThingWithFileTransfer Thing to transfer the file to.
The path specifying the destination location of the file.
The name of the file at the target location. This name can differ from the sourceName parameter.
The amount of time to wait for the synchronous transfer to complete (seconds) before cancelling the transfer.
If false, the service call will block for the length specified by the “timeout” parameter or until it completes.
After running this application, you will notice a new file in the transfer/incoming folder after refreshing. This is the file that we created in the ThingWorx Composer file system for the SystemRepository Entity and was copied from that location to our local project. We have also sent a file to the server’s SystemRepository. The BrowseFileSystem and GetFileListing Services can be used to check for the folders and files created.
Step 10: Troubleshooting
All Websocket errors indicate some general issue communicating with the ThingWorx platform. If you experience an issue connecting, refer to the table below for a list of websocket errors, their corresponding codes, and an explanation of the issue.
An unknown error occurred on the websocket.
An error occurred while initializing the websocket. Check your websocket configuration parameters for validity.
A timeout occurred while initializing the websocket. Check the status of the connection to ThingWorx.
The websocket is not connected to ThingWorx. The requested operation cannot be performed.
An error occurred while parsing websocket data. The parser could not break down the data from the websocket.
An error occurred while reading data from the websocket. Retry the read operation. If necessary, resend the data.
The SDK is attempting to send a websocket frame that is too large. The Maximum Frame Size is set when calling twAPI_Initialize and should always be set to the Message Chunk Size (twcfg.message_chunk_size).
The type of the frame coming in over the websocket is invalid.
The application is attempting to send a message that has been broken up in to chunks that are too large to fit in a frame. You should not see this error.
An error occurred while writing to the Web socket.
The Accept key sent earlier from ThingWorx is not valid.
Step 11: Tunneling Example
To handle file transfers, a virtual directory is created in theTunnelExample Entity and in the project directory. The source code used for this example is incom.thingworx.sdk.examples.TunnelExample.java.
To enable tunneling, create the configurations like other steps, and then either invokeClientConfigurator.tunnelsEnabled(true), or set thetunnelsEnableddirective in your config file.
Once it connects to the server, this client bindsthingNameto the matchingRemoteThingWithTunnelsdefined on the ThingWorx Platform. Once bound, the Thing can receive tunnel requests from the Platform, and facilitate tunnels to local applications.
Step 12: Next Steps
Congratulations! You've successfully completed the Java SDK Tutorial, and learned how to utilize the resources provided in the Java SDK create your own application.