ThingWorx Edge Java SDK > Using ThingWorx Platform and the Edge Java SDK > Connecting an Application to ThingWorx Platform
Connecting an Application to ThingWorx Platform
All connections follow a basic pattern, illustrated in the diagram below:
Connection Process
When the device starts, it establishes a connection over HTTP or HTTPS and a WebSockets upgrade occurs. The device authenticates, using its configured Application Key. At this point, a device can call invokeService().
The Java SDK follows this process when connecting to the ThingWorx platform. The three steps below describe the first three parts of the process, Connect, Authenticate, and Bind. Later sections will address Synchronization, Pushing Data, and Disconnecting.
In the following steps, “client” refers to the application and the SDK running on or near the device and “server” refers to the ThingWorx platform:
1. Connect: The client opens a websocket to the server, using the host and port that it has been configured to use. If configured, TLS is negotiated at this time.
2. Authenticate: The client sends an authentication message to the server, which contains an Application Key to authenticate with the server. This message is part of the ThingWorx AlwaysOn protocol. If the client attempts to send any other message before the authentication message, the server disconnects it. The platform also disconnects the client if it does not receive an authentication message within 15 seconds. You can configure this timeout in ThingWorx Composer (the WS Communication Subsystem configuration). The setting is named Amount of time to wait for authentication message (secs).
Establishing a connection and authenticating are both performed whenever a new SDK client is created and its start() method is called. Once authenticated, the client can interact with the server according to the permissions granted to the user account that is associated with its Application Key. At this point, the client can make requests to the server and interact with it. Note, however, that the server cannot yet direct requests to the client.
3. Bind: Binding is an optional step in the client connection process. The SDK client allows one or more virtual things to be associated with a websocket, using their names or identifiers. After associating a virtual thing with a websocket, the client sends a BIND request to the server. The server then links the associated thing (which was created using the RemoteThing thing template) on the server with the websocket from which it received the bind request. Binding enables the server to send request messages to a client application over the associated websocket. The server also updates the isConnected property to true and the time value of the lastConnected property for the newly bound thing to show the time that the binding was established.
In addition to connecting the device (client) to the thing (isConnected property), binding maps the properties and services of the thing to values and functions on your device. Binding also registers a thing to participate in property change subscriptions.
A client can also send an UNBIND request. This message tells the platform to remove the association between the thing on the platform and the websocket. The isConnected property of the thing is then updated to false.
To enable your application to connect to the server, you need to create a ClientConfigurator and then use it to create a ConnectedThingClient. The ConnectedThingClient then establishes the connection to the server. Here is an example from the SimpleClient example (samples/src/com/thingworx/sdk/simple/ that shows you how to connect to the server. It is important to note here that NO binding takes place here:
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 server that we are going to connect to
// You MUST include the port number in the URI.

// Set the Application Key to allow the client to authenticate with
// the server. The Key also determines what the client is authorized
// to do once connected.

// To test against a server using a self-signed certificate, you must
// use the ignoreSSLErrors method. HOWEVER< make sure that you remove
// this line for a production system.
config.ignoreSSLErrors(true); //All self-signed certificates
try {

// Create our client.
SimpleClient client = new SimpleClient(config);

// Start the client. The client will connect to the server and
// authenticate, using the Application Key specified above.

// Wait for the client to connect.
// When using binding, put the bind
// request here.
if (client.waitForConnection(30000)) {"The client is now connected.");

// Here is where you add activities such as reading
// a property or invoking a service

else {
// Log this as a warning. In production the application could
// continue to execute, and the client would attempt to
// reconnect periodically.
LOG.warn("Client did not connect within 30 seconds. Exiting");


catch (Exception e) {
LOG.error("An exception occurred while initializing the client", e);
}"SimpleClient is done. Exiting");
With this connection, you have a fast, continuously connected, bidirectional data channel between ThingWorx platform and as many remote processes as you want. The AlwaysOn protocol enables this communication.
It is strongly recommended that you use SSL/TLS with a valid server certificate for connections between your devices and the ThingWorx platform. Use of self-signed certificates and the ignoreSSLErrors method is purely for development purposes.
The next few sections build out this example to show how to read and write properties, invoke services, and fire events. The complete example is in the SDK installation, at samples/src/com/thingworx/sdk/ (simple and simplething). the ThingWorx platform entities used in these examples can be found in an export file included with the SDK that can be imported into the ThingWorx platform. That file can be found at entities/ExampleExport.xml.