ConnectedThingClient Component
The ConnectedThingClient component facilitates communication to the ThingWorx Platform, as well as manages Virtual Things on the edge, both bound and unbound. A ConnectedThingClient can contain multiple Virtual Things.
To initialize an instance of a ConnectedThingClient, you construct it with a configured instance of a ClientConfigurator class. The start() method establishes a WebSocket connection, performs authentication, and binds the Virtual Things with the server. Use the shutdown() method to close the connection and clean up the resources of the client.
Here is an example of creating the ConnectedThingClient from the SteamSensorClient.java file:
public class SteamSensorClient extends ConnectedThingClient {
private static final Logger LOG = LoggerFactory.getLogger(SteamSensorClient.class);
static String hostName = "";
static int port = 8080;
static int logLevel = 2;
static String thingworxUri = "";
public SteamSensorClient(ClientConfigurator config) throws Exception {
super(config);
}
. . .
// Set the required configuration information
ClientConfigurator config = new ClientConfigurator();
config.setUri(thingworxUri);
// Reconnect every 15 seconds if a disconnect occurs or if initial connection cannot be made
config.setReconnectInterval(15);
// Enable tunneling if requested
if(cmd.hasOption("n")) {
config.tunnelsEnabled(true);
}
. . .
The sections listed below describe additional configuration options for the ConnectedThingClient and its ClientConfigurator. For information about passing authentication secrets such as application keys and passwords, refer to Password Callbacks. Click a section title to display its content:
Duty Cycle Modulation
Duty Cycle Modulation is the ability for a client application to regulate the time that the application is connected to the ThingWorx Platform. Periodically, the application checks to determine whether it is above or below its threshold for connections (a percentage), and connects to or disconnects from the ThingWorx Platform accordingly. Duty Cycle Modulation is crucial when you want to conserve the use of your connection to the network. Common scenarios include use over a cellular network or in low-connectivity/power-limited environments.
 | When a disconnect is initiated, pending requests are not terminated. The application waits for pending requests to finish. If any pending requests remain active after 40 seconds, the disconnect is executed forcibly. |
The ConnectedThingClient supports forcing a connection to be established for multiple operations, including:
Operation | Method to Use |
|---|---|
Invoke a service | invokeService |
Read a property value | readProperty |
Write a value to a property | writeProperty |
Generate an event | fireEvent |
Duty Cycle Example
A dutyCycleConnectionPercentage of 40 percent and a dutyCyclePeriod of 400 seconds results in the client application being connected to the ThingWorx Platform for the first 160 seconds of each 400–second duty cycle (0.4 * 400 = 160). At the end of the duty cycle period, the percentage is checked again. Operations such as property updates, service invocations, and so on, can be configured to force the application to reconnect to the ThingWorx Platform while in the off duty cycle.
Connecting Through a Proxy Server
The Java SDK supports connecting to a ThingWorx Platform that is behind an HTTP proxy server. Connecting through a proxy server is often required when data is being collected at remote locations outside of your local network. Authentication with the proxy server is also supported. The type of authentication used is determined when the Java SDK connects to it. The Java SDK queries a proxy server to determine what type of authentication it supports.
| | The Java SDK supports Basic and Digest authentication for proxy servers. Although not recommended, you can decide not to use authentication with the Java SDK and proxy servers. Proxy settings can be configured for all examples provided in the Java SDK distribution bundle. |
In your application, you need to set at most four parameters to use a proxy server:
• Proxy host — The host name of the machine that is running the proxy server.
• Proxy port number — The number of the port on the proxy server machine to which the client should connect.
• If authentication is required:
◦ A user name — The name of the "user" making the request. This could be the name of a device or an application, for example.
◦ A password callback — The callback that the application will invoke to supply the password to the proxy server for authentication.
| | If using a proxy that requires authentication, it is important to note that the proxy credentials are independent of the ThingWorx Platform. Proxy credentials are never passed beyond the proxy server, and are not used by the ThingWorx Platform. |
Here is an example from the SteamSensorClient:
// Configure Proxy if required
if(cmd.hasOption("j")) {
config.setProxyHost(cmd.getOptionValue("j"));
config.setProxyPort(Integer.parseInt(cmd.getOptionValue("r")));
config.setProxyUser(cmd.getOptionValue("u"));
if(cmd.hasOption("q")) {
config.setProxyPassCallback( new SamplePasswordCallback(cmd.getOptionValue("q")) );
}
}
In this example, the SteamSensorClient is taking input from the application for setting up the proxy server connection using the config.setProxyHost, config.setProxyPort, and config.setProxyUser methods with the cmd.getOptionValue() command. The proxy password is set using config.setProxyPassCallback( new SamplePasswordCallback(cmd.getOptionValue("q")) );. This configuration is done in the ClientConfigurator of the ConnectedThingClient.
Using a ClientConfigurator to Set Up the Proxy Server
The following example shows how to modify a ClientConfigurator configuration to create a secure WebSocket connection (WSS) through a proxy server that does not require authentication:
String URI="wss://localhost:443/Thingworx/WS";
String appKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
ClientConfigurator config = new ClientConfigurator();
config.setUri(uri);
config.setAppKey(appKey);
config.setProxyHost("proxy.your-company.com");//Put your proxy servers here
config.setProxyPort(3100);
ConnectedThingClient client = new ConnectedThingClient(config);
client.connect();
The following example shows how to modify the configuration to create the configuration for a WSS connection with a proxy server that requires Basic or Digest authentication:
String uri="wss://localhost:443/Thingworx/WS";
String appKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
ClientConfigurator config = new ClientConfigurator();
config.setUri(uri);
config.setAppKey(appKey)
config.setProxyHost("proxy.your-company.com");//Put your proxy servers here
config.setProxyPort(3100);
config.setUser("yourproxyusername");
config.setPass("yourproxypassword")
ConnectedThingClient client = new ConnectedThingClient(config);
client.start();