Showing results for 
Search instead for 
Did you mean: 
Showing results for 
Search instead for 
Did you mean: 

Community Tip - Did you get called away in the middle of writing a post? Don't worry you can find your unfinished post later in the Drafts section of your profile page. X

Java SDK Tutorial Part 5

No ratings



Step 9: File Transfer 


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


Set Up File Transfer


  1. Right-click the project. Click New. Scroll and select Folder.

  2. Enter transfer/incoming into the text box at the bottom. Click Finish.

  3. Repeat steps 1 and 2, but create a folder called transfer/outgoing.

  4. Right-click the transfer/outgoing folder. Click New. Scroll and select File.

  5. Create a file with the name outgoing.txt. Click Finish.

  6. Once the outgoing.txt document is open, add the following text, click Save, and close the file:

    Hello. This is a file coming from the client application.
  7. Navigate to the code and update the lines below with the appropriate information for your IP, port, and the admin_key Application Key’skeyId value 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.


FileTransferExampleHelper Methods


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 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 ( to make the design cleaner.


The below table provides insight into some of the helper methods created to separate roles for a cleaner solution.


createSystemRepositoryIncomingPathCreate the payload for the call to create the “incoming” directory on the SystemRepository in the ThingWorx Platform.
createSystemRepositoryOutgoingPathCreate the payload for the call to create the “outgoing” directory on the SystemRepository in the ThingWorx Platform.
createTransferIncomingParametersCreate 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.
createTransferOutgoingParametersCreate 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.



Service Parameters


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.


sourceRepo“SystemRepository”The name of a FileRepository or RemoteThingWithFileTransfer Thing to transfer the file from.
sourcePath“/outgoing”The path specifying the location in the file repository of the source file.
sourceFile“example.txt”The name of the source file.
targetRepoFileTransferExampleThe name of a FileRepository or RemoteThingWithFileTransfer Thing to transfer the file to.
targetPath“in”The path specifying the destination location of the file.
targetFile“example.txt”The name of the file at the target location. This name can differ from the sourceName parameter.
timeout15000The amount of time to wait for the synchronous transfer to complete (seconds) before cancelling the transfer.
asyncfalseIf 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.


200TW_UNKNOWN_WEBSOCKET_ERRORAn unknown error occurred on the websocket.
201TW_ERROR_INITIALIZING_WEBSOCKETAn error occurred while initializing the websocket. Check your websocket configuration parameters for validity.
202TW_TIMEOUT_INITIALIZING_WEBSOCKETA timeout occurred while initializing the websocket. Check the status of the connection to ThingWorx.
203TW_WEBSOCKET_NOT_CONNECTEDThe websocket is not connected to ThingWorx. The requested operation cannot be performed.
204TW_ERROR_PARSING_WEBSOCKET_DATAAn error occurred while parsing websocket data. The parser could not break down the data from the websocket.
205TW_ERROR_READING_FROM_WEBSOCKETAn error occurred while reading data from the websocket. Retry the read operation. If necessary, resend the data.
206TW_WEBSOCKET_FRAME_TOO_LARGEThe 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).
207TW_INVALID_WEBSOCKET_FRAME_TYPEThe type of the frame coming in over the websocket is invalid.
208TW_WEBSOCKET_MSG_TOO_LARGEThe 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.
209TW_ERROR_WRITING_TO_WEBSOCKETAn error occurred while writing to the Web socket.
210TW_INVALID_ACCEPT_KEYThe Accept key sent earlier from ThingWorx is not valid.




Step 11: Tunneling Example 


To handle file transfers, a virtual directory is created in the TunnelExample Entity and in the project directory. The source code used for this example is in


To enable tunneling, create the configurations like other steps, and then either invoke ClientConfigurator.tunnelsEnabled(true), or set the tunnelsEnabled directive in your config file.


Once it connects to the server, this client binds thingName to the matching RemoteThingWithTunnels defined 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.


The next guide in the Connect and Configure Industrial Devices and Systems learning path is C SDK Tutorial.


Learn More


We recommend the following resources to continue your learning experience:


BuildDesign Your Data Model
BuildImplement Services, Events, and Subscriptions


Additional Resources


If you have questions, issues, or need additional information, refer to:


CommunityDeveloper Community Forum
SupportJava Edge SDK Help Center



Version history
Last update:
‎Nov 18, 2022 04:23 PM
Updated by:
Labels (1)