Overview

This section describes how to use/implement the Java library Client API  functions available to interact with the IoT Portal. The base class DwClient contains all the basic TR50 connection and communication APIs. Two additional classes DwMqttClient and DwHttpClient have been provided that extend the base set of client APIs to implement the TR50 connection and communication functions in MQTT and HTTP respectively.


DwClient

Constructors

Constructor Description
DwClient() Initializes the TR50 Client and Worker APIs

Methods

Modifier and Type Method and Description
int authenticate(java.lang.String user, java.lang.String password) 
int authenticate(java.lang.String appToken, java.lang.String appID, java.lang.String thingKey) 
abstract int connect() 
abstract int disconnect() 
java.util.Vector<DwOpenDisconnectActionListener> getDisconnectListeners() 
java.util.Vector<DwOpenMailboxEventListener> getMailboxListeners() 
java.util.Vector<DwOpenReceiveActionListener> getRecvListeners() 
java.util.Vector<DwOpenSendActionListener> getSendListeners() 
java.lang.String getSessionId() 
DwOpenWorker getWorker() 
void onDisconnect(DwClient source, java.lang.Throwable cause) 
void onMailboxReceive(int retCode, java.lang.Throwable cause, DwOpenMailboxMessage response) 
void onReceive(int retCode, java.lang.Throwable cause, DwPacket packet, DwOpenGenericResponse response) 
void onSend(int retCode, java.lang.Throwable cause, DwPacket packet) 
void registerDisconnectActionListener(DwOpenDisconnectActionListener listener) 
int registerMailboxCommandListener(java.lang.String command, DwOpenMailboxCommandListener listener) 
int registerMailboxEventListener(DwOpenMailboxEventListener listener) 
int registerMethod(DwOpenMethodCallback method) 
void registerReceiveActionListener(DwOpenReceiveActionListener listener) 
void registerSendActionListener(DwOpenSendActionListener listener) 
abstract int sendAsyncJSONRequest(int msgId, java.lang.String json) 
abstract int sendJSONRequest(int msgId, java.lang.String json, StringReply reply) 
int sendPacket(DwPacket packet) 
int sendPacket(DwPacket packet, DwOpenReceiveActionListener recv, java.lang.Object response) 
void setSessionId(java.lang.String sessionId) 
int unregisterDisconnectActionListener(DwOpenDisconnectActionListener listener) 
int unregisterMailboxCommandListener(DwOpenMailboxCommandListener listener) 
int unregisterMailboxEventListener(DwOpenMailboxEventListener listener) 
int unregisterMethod(DwOpenMethodCallback method) 
int unregisterReceiveActionListener(DwOpenReceiveActionListener listener) 
int unregisterSendActionListener(DwOpenSendActionListener listener) 

Notes

  • All current client implementations - DwMqttClient and DwHttpClient are subclasses of the abstract DwClient class and extend all of the API functions listed above.
  • All current client implementations - DwMqttClient and DwHttpClient implement the abstract methods connect(), disconnect(), sendJsonRequest() and sendAsyncJsonRequest() based on the protocol spec.
  • All current clients use the common DwOpenWorker, which is initialized by calling each clients super() - DwClient constructor class. This initializes the common set of JAVA - Worker APIs that allow interaction with the M2M Service APIs. See DwMqttClient and DwHttpClient implementations below for specific connection and communication related examples.

DwCommand (TR50 Command)

  • java.lang.Object
    • com.devicewise.tr50.protocol.DwCommand
    • All Implemented Interfaces:IDwCommand

Constructors

Constructor and Description
DwCommand() - Initializes a TR50 command
DwCommand(java.lang.String command) - Initializes a TR50 command with the specified command key

Methods

 
Modifier and TypeMethod and Description
voidaddBooleanArrayParam(java.lang.String name, boolean[] value) 
voidaddBooleanParam(java.lang.String name, boolean value) 
voidaddDoubleArrayParam(java.lang.String name, double[] loc) 
voidaddDoubleParam(java.lang.String name, double value) 
voidaddFloatArrayParam(java.lang.String name, float[] loc) 
voidaddFloatParam(java.lang.String name, float value) 
voidaddIntegerArrayParam(java.lang.String name, int[] value) 
voidaddIntegerParam(java.lang.String name, int value) 
voidaddObjectArrayParam(java.lang.String name, java.lang.Object... data) 
voidaddObjectArrayParamWithKey(java.lang.String name, DwJsonObjectWithKey... data) 
voidaddObjectParam(java.lang.String name, java.lang.Object value) 
voidaddParam(java.lang.String param, java.lang.Object value) 
voidaddParamsFromObjectArray(java.lang.Object[] params) 
voidaddParamsFromStringArrayNameValuePairs(java.lang.String... params) 
voidaddParamsFromVectorNameValuePairs(java.util.Vector<java.lang.String> params) 
voidaddParmasFromObjectVector(java.util.Vector<java.lang.Object> params) 
voidaddStringArrayParam(java.lang.String name, java.lang.String[] tags) 
voidaddStringParam(java.lang.String name, java.lang.String value) 
voiddeleteParam(java.lang.String param) 
java.lang.StringgetCommand() 
java.util.LinkedHashMap<java.lang.String,java.lang.Object>getParams() 
voidsetCommand(java.lang.String command) 
voidsetParams(java.util.LinkedHashMap<java.lang.String,java.lang.Object> params) 


DwPacket ( TR50 Message )

  • java.lang.Object
    • com.devicewise.tr50.protocol.DwPacket
    • extends java.lang.Object implements IDwPacket

Constructors

Constructor and Description
DwPacket() - Initializes a TR50 message packet
DwPacket(DwClient client) - Initalizes a TR50 message packet with the appropriate client object for session authentication

Methods

Modifier and Type Method and Description
int addCommand(java.lang.String corrId, IDwCommand command) 
void endPacket() 
java.util.Vector<java.lang.String> getCorrelIDs() 
DwJsonRequestBuilder getJsonBuilder() 
java.util.LinkedHashMap<java.lang.String,java.lang.Object> getRawResponse() 
java.util.LinkedHashMap<java.lang.String,java.lang.Object> getRawResponse(java.lang.String corrId) 
java.lang.String getRequest() 
java.lang.String getResponse() 
void setJsonBuilder(DwJsonRequestBuilder jsonBuilder) 
void setRequest(java.lang.String jsonRequest) 
void setResponse(java.lang.String jsonResponse) 

Usage Examples: Building and Sending a TR50 Message and Parsing a Response.

     
    @Test
    public void testMultiCommandPacketParser() throws DwOpenException, IOException{
        
        DwPacket packet = new DwPacket();
        DwCommand cmd1 = new DwCommand(DwOpenCommands.CMD_API_THING_LIST);
        cmd1.addIntegerParam("offset",0);
        cmd1.addIntegerParam("limit", 10);
        DwCommand cmd2 = new DwCommand(DwOpenCommands.CMD_API_THINGDEF_LIST);
        packet.addCommand("corrId1",cmd1);
        packet.addCommand("corrId2",cmd2);
        
        Assert.assertTrue(packet.getRequest().equals("{\"corrId1\":{\"command\":\"thing.list\",\"params\":{\"offset\":0,\"limit\":10}},\"corrId2\":{\"command\":\"thing_def.list\",\"params\":{}}}"));
        
        Assert.assertEquals(client.sendPacket(packet),0);
        
        DwOpenThingList list = new DwOpenThingList();
        list.getCorrId();
        list.parseResponse("corrId1",packet.getResponse());
        DwOpenThingDefList defList = new DwOpenThingDefList();
        defList.setCorrId("corrId2");
        defList.parseResponse(packet.getResponse());
        
        Assert.assertTrue(list.isSuccess());
        Assert.assertTrue(defList.isSuccess());
        Assert.assertNotNull(list.getResult());
        Assert.assertEquals(list.getResult().size(), 10);
        Assert.assertNotNull(defList.getResult());
        Assert.assertTrue(defList.getResult().size()>0 && defList.getResult().size()<5);
        
        LinkedHashMap<String,Object> response = packet.getRawResponse("corrId2");
        Assert.assertTrue((boolean)response.get("success"));
 
        LinkedHashMap<String,Object> params = ((LinkedHashMap<String,Object>)(packet.getRawResponse("1").get("params")));
        ArrayList<LinkedHashMap<String,Object>> result = (ArrayList<LinkedHashMap<String,Object>>)params.get("result");
        Assert.assertTrue(result.size()==10);
    }
 


DwMqttClient

  • java.lang.Object
    • com.devicewise.tr50.protocol.DwClient
      • com.devicewise.tr50.clients.DwMqttClient
  • All implemented interfaces: IDwClient, org.eclipse.paho.client.mqttv3.MqttCallback

Constructors

Constructor and Description
DwMqttClient() - Initializes the DwMqttClient and calls DwClient() to initialize the worker apis

Methods

Modifier and Type Method and Description
int authenticate(java.lang.String user, java.lang.String password) 
int connect() 
int disconnect() 
java.lang.String getBrokerURL() 
org.eclipse.paho.client.mqttv3.MqttClient getClient() 
java.lang.String getClientID() 
java.lang.String getPassword() 
java.lang.String getUser() 
void initialize(java.lang.String host, boolean isSSL, java.lang.String clientID) 
void initialize(java.lang.String host, java.lang.String port, boolean isSSL, java.lang.String clientID) 
boolean isConnected() 
int sendAsyncJSONRequest(int msgId, java.lang.String json) 
int sendJSONRequest(int msgId, java.lang.String json, StringReply response) 
void setBrokerURL(java.lang.String brokerURL) 
void setClient(org.eclipse.paho.client.mqttv3.MqttClient client) 
void setClientID(java.lang.String clientID) 
void setPassword(java.lang.String password) 
void setUser(java.lang.String user) 

Usage Examples: Authenticating and Making an API call with the MQTT Client

     public void MQTTClientAsUser() throws Exception{
        
        DwMqttClient user= new DwMqttClient();
        user.initialize(MqttConstants.DEFAULT_MQTTHOST, true, "tr50_client_id");
        user.authenticate("tr50user","tr50password");
        DwOpenWorker worker = client.getWorker();
        
        DwOpenLocationEncodeDecode response = new DwOpenLocationEncodeDecode();
        
        worker.Location().decode(30.455, -84.25333,response);
        
        user.disconnect();
    }
 
    public void MQTTClientAsThing() throws Exception{
        
        DwMqttClient thing= new DwMqttClient();
        thing.initialize(MqttConstants.DEFAULT_MQTTHOST, true, "tr50_client_id");
        thing.authenticate("myThingKey","myAppToken");
        DwOpenWorker worker = client.getWorker();
        
        DwOpenLocationEncodeDecode response = new DwOpenLocationEncodeDecode();
        
        worker.Location().decode(30.455, -84.25333,response);
        
        thing.disconnect();
    }

DwHttpClient

  • java.lang.Object
    • com.devicewise.tr50.protocol.DwClient
      • com.devicewise.tr50.clients.DwHttpClient

Constructors

Constructor Description
DwHttpClient() Initializes the DwHttpClient and calls DwClient() to initialize the worker apis

Methods

Modifier and Type

Method and Description
int connect() 
int disconnect() 
java.net.HttpURLConnection getConnection() 
int initialize(java.lang.String url) 
int sendAsyncJSONRequest(int msgId, java.lang.String json) 
int sendJSONRequest(int msgId, java.lang.String json, StringReply reply) 
void setConnection(java.net.HttpURLConnection connection) 

Usage Examples:  Authenticating and Making an API call with the HTTP Client

 public void HTTPClientAsUser() throws Exception{
        
        DwHttpClient user= new DwHttpClient();
        user.initialize("https://my.openserver.com/api");
        user.authenticate("tr50user","tr50password");
        DwOpenWorker worker = client.getWorker();
        
        DwOpenLocationEncodeDecode response = new DwOpenLocationEncodeDecode();
        
        worker.Location().decode(30.455, -84.25333,response); // does a connect, send and disconnect as per HTTP 1.0 Protocol Spec
    }
 
    public void HTTPClientAsThing() throws Exception{
        
        DwHttpClient thing= new DwHttpClient();
        thing.initialize("https://my.openserver.com/api");
        thing.authenticate("myThingKey","myAppToken");
        DwOpenWorker worker = client.getWorker();
        
        DwOpenLocationEncodeDecode response = new DwOpenLocationEncodeDecode();
        
        worker.Location().decode(30.455, -84.25333,response); // does a connect, send and disconnect as per HTTP 1.0 Protocol Spec
    }