Java SDK Tutorial Part 5

[#1]

• Step 9: File Transfer
• Step 10: Troubleshooting
• Step 11: Tunneling Example
• Step 12: Next Steps

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 com.thingworx.sdk.examples.FileTransferExample.java.

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 FileTransferExample.java code and update the lines below with the appropriate information for your IP, port, and the admin_key Application Key’skeyId value in Composer:
   

   config.setUri("ws://127.0.0.1:80/Thingworx/WS");        
   config.setAppKey("ce22e9e4-2834-419c-9656-ef9f844c784c");

   
   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 (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.

Method	Purpose
createSystemRepositoryIncomingPath	Create the payload for the call to create the “incoming” directory on the SystemRepository in the ThingWorx Platform.
createSystemRepositoryOutgoingPath	Create the payload for the call to create the “outgoing” directory on the SystemRepository in the ThingWorx Platform.
createTransferIncomingParameters	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.
createTransferOutgoingParameters	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.

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.

Parameter	Example	Description
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.
targetRepo	FileTransferExample	The 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.
timeout	15000	The amount of time to wait for the synchronous transfer to complete (seconds) before cancelling the transfer.
async	false	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.

Code	Message	Troubleshooting
200	TW_UNKNOWN_WEBSOCKET_ERROR	An unknown error occurred on the websocket.
201	TW_ERROR_INITIALIZING_WEBSOCKET	An error occurred while initializing the websocket. Check your websocket configuration parameters for validity.
202	TW_TIMEOUT_INITIALIZING_WEBSOCKET	A timeout occurred while initializing the websocket. Check the status of the connection to ThingWorx.
203	TW_WEBSOCKET_NOT_CONNECTED	The websocket is not connected to ThingWorx. The requested operation cannot be performed.
204	TW_ERROR_PARSING_WEBSOCKET_DATA	An error occurred while parsing websocket data. The parser could not break down the data from the websocket.
205	TW_ERROR_READING_FROM_WEBSOCKET	An error occurred while reading data from the websocket. Retry the read operation. If necessary, resend the data.
206	TW_WEBSOCKET_FRAME_TOO_LARGE	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).
207	TW_INVALID_WEBSOCKET_FRAME_TYPE	The type of the frame coming in over the websocket is invalid.
208	TW_WEBSOCKET_MSG_TOO_LARGE	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.
209	TW_ERROR_WRITING_TO_WEBSOCKET	An error occurred while writing to the Web socket.
210	TW_INVALID_ACCEPT_KEY	The 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 com.thingworx.sdk.examples.TunnelExample.java.

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:

Capability	Guide
Build	Design Your Data Model
Build	Implement Services, Events, and Subscriptions

 

Additional Resources

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

Resource	Link
Community	Developer Community Forum
Support	Java Edge SDK Help Center