ThingWorx Edge Java SDK > Application Details > ConnectedThingClient Component
ConnectedThingClient Component
The ConnectedThingClient component facilitates communication to the ThingWorx platform, as well as manages the contained virtual things. A ConnectedThingClient can contain multiple virtual things, as demonstrated in the Steam Sensor example.
To initialize an instance of a ConnectedThingClient, you set the parameters in a ClientConfigurator. 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.
The following sections describe additional configuration options for the ConnectedThingClient and its ClientConfigurator:
Duty Cycle Modulation
Connecting Through a Proxy Server
Using a ClientConfigurator to Set Up the Proxy Server
Using Security Claims for Authentication
Example 20. Adding Security Claims to the ClientConfigurator (example)
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 see if 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 useful when conservation of power and resources is important.
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 operation (methods), including:
Invoking a service (invokeService)
Reading a property value (readProperty)
Writing a value to a property (writeProperty)
Generating an event (fireEvent)
Example 19. 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.
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 no authentication as well as Basic and Digest authentication for proxy servers.
In your application, you need to set at most four parameters to use a proxy server:
Proxy host
Proxy port number
If authentication is required:
A user name
A password
If using a proxy that requires authentication, it is important to note that the proxy user name and password have nothing to do with the ThingWorx platform. The user name and password combination is never passed beyond the proxy server.
Using a ClientConfigurator to Set Up the Proxy Server
In your application, you need to build the ClientConfigurator and then set the additional parameters described above.
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.setProxyHost("");//Put your proxy servers here
ConnectedThingClient client = new ConnectedThingClient(config);
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.setProxyHost("");//Put your proxy servers here
ConnectedThingClient client = new ConnectedThingClient(config);
Using Security Claims for Authentication
The recommended method of setting up authentication is to use the ClientConfigurator.setAppKey(String appkey) method. However, you can also use the SecurityClaims object.
A security claim contains the security settings for connecting to a ThingWorx platform. The Java SDK supports the Application Key as the method of authenticating with a ThingWorx platform.
For example:
SecurityClaims claims =
If the security claim is well known, you can use the addClaim(String name, String value) method of the SecurityClaims object to pass in the appropriate value for the Application Key. Here are examples of using this method:
// Application Key Example

SecurityClaims claims = new SecurityClaims()
Example 20. Adding Security Claims to the ClientConfigurator
You can add security claims code to the ClientConfigurator, as shown in the following example:
public class SimpleClient extends ConnectedThingClient {

private static final Logger LOG = LoggerFactory.getLogger(SimpleClient.class);

public SimpleClient(ClientConfigurator config) throws Exception {

public static void main(String[] args) {
ClientConfigurator config = new ClientConfigurator();

// Set the URI of the ThingWorx platform to connect to

// Set the ApplicationKey as the security claim, which is the same
// as calling config.setAppKey(). .
SecurityClaims claims = new SecurityClaims();
claims.addClaim(Fields.AppKey, "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx");