Help Center> IoT Device Access> SDK Reference> Old SDKs> Application Java SDK API Reference> SDK Usage Guide (for China Unicom Users Only)
View PDF

SDK Usage Guide (for China Unicom Users Only)

Non-China Unicom users can view the IoT Device Access (IoTDA) Developer Guide.

SDK Demo Architecture

  • The demo code is the sample code used for calling SDK APIs, including initializing and calling each API. The demo code is for your reference only.
  • The Java SDK uses Java methods to call platform APIs to communicate with the IoT platform.
  • The message push callback uses Java code to implement the callback API, which is called by the platform to push messages to applications. An application inherits the PushMessageReceiver class and overrides the methods in the class to receive the content of a push message.
  • The test API tests whether the basic functions between the SDK and platform are available and generates test results. During the test, the internal test certificate and the certificate set by developers are used.

Methods of the NorthApiClient Class

The methods of the NorthApiClient class are used to create an application instance. They are the prerequisites for calling other SDK APIs. The table below describes the main methods.

Method

Description

public void setClientInfo( ClientInfo clientInfo)

Initializes the parameters of NorthApiClient. For details on the definition of ClientInfo, see Methods of the ClientInfo Class.

public void setHttpConnection(int httpSocketTimeout, int httpConnectionTimeout, int maxConnectionAmount, int maxConnectionAmountPerRoute, int clearIdleTime, int httpRetryTimes)

Sets an HTTP connection pool. The following parameters can be set:

  • httpSocketTimeout: socket timeout interval, in milliseconds. The default value is 30000.
  • httpConnectionTimeout: connection timeout interval, in milliseconds. The default value is 30000.
  • maxConnectionAmount: maximum number of connections. The default value is 200.
  • maxConnectionAmountPerRoute: maximum number of connections for each route. The default value is 200.
  • clearIdleTime: duration that a link remains idle before it is cleared, in milliseconds. The default value is 20000.
  • httpRetryTimes: number of retry attempts. The default value is 0.

This method must be called before the initSSLConfig() or initSSLConfig(SSLConfig sslConfig) method is called.

public void initSSLConfig()

Initializes the two-way authentication configuration. Other methods can only be used after this method is called.

NOTICE:

This method uses a test certificate, which is an informal certificate, and does not verify the host name. Therefore, this method is used only in the integration interconnection commissioning phase.

public void initSSLConfig(SSLConfig sslConfig)

Initializes the two-way authentication configuration. Other methods can only be used after this method is called. For details about the SSLConfig class, see Methods of the SSLConfig Class.

NOTICE:

This method is used to import certificates and can be used in commercial use. Before calling this method, you can call the setHostnameVerifier(HostnameVerifier hostnameVerifier) method to verify the host name. Otherwise, the strict host name verification is used by default.

public void setHostnameVerifier(HostnameVerifier hostnameVerifier)

Customizes the host name verification method. This method needs to be called before the initSSLConfig(SSLConfig sslConfig) method is called. Otherwise, the strict host name verification is used by default.

NOTICE:
  • If the host name in the commercial certificate is the same as that in the platform environment, you do not need to call this method. By default, the strict host name verification is used.
  • The host name verification method should adhere to the security principle. The value true should not be returned directly.

public String getVersion()

Queries the SDK version.

Methods of the ClientInfo Class

The methods of the ClientInfo class are used to set basic information for interworking with the platform. The table below describes the main methods (excluding the get method):

Method

Description

public void setPlatformIp(String platformIp)

Sets the IP address of the platform.

public void setPlatformPort(String platformPort)

Sets the port of the platform, for example, 8743.

public void setAppId(String appId)

Sets the application ID. The application ID is an identity allocated by the platform to a third-party application, and is used to uniquely identify an application.

public void setSecret(String secret)

Sets the secret of the application. The secret indicates the password for the application ID on the platform.

Methods of the NorthApiException Class

When the SDK processing is abnormal or the platform fails to process an SDK request, a method of the NorthApiException class is thrown. The following describes the main methods (excluding the set method):

Method

Description

public String geterror_code()

Obtains an error code. If the SDK processing is abnormal, a four-digit error code is generated. If the platform fails to process an SDK request, a six-digit error code is generated.

public String getError_desc()

Obtains the description corresponding to the error code.

public String getHttpStatusCode()

Obtains the abnormal HTTP status code.

This SDK encapsulates RESTful APIs using HTTP. Therefore, if an exception occurs when an RESTful API is called by the SDK, an abnormal HTTP status code is returned, such as 404 or 200.

public String getHttpReasonPhase()

Obtains the cause description (ReasonPhrase) corresponding to the abnormal HTTP status code (ReasonPhrase).

For example, if the HTTP status code is 400, the cause is "Not Found." If the HTTP status code is 200, the cause is "OK."

public String getHttpMessage()

Obtains the exception content if the platform fails to process a request and the exception does not contain an error code.

Methods of the SSLConfig Class

The methods of the SSLConfig class are used to set the certificate path and password. The following describes the main methods (excluding the get method):

Method

Description

public String setSelfCertPath(String selfCertPath)

Sets the absolute path of a client certificate.

public String setSelfCertPwd(String selfCertPwd)

Sets the password of the client certificate.

public String setTrustCAPath(String trustCAPath)

Sets the absolute path of the server CA certificate.

public String setTrustCAPwd(String trustCAPwd)

Sets the password of the server CA certificate.

Methods of the BasicTest Class

The methods of the BasicTest class are used to test whether basic functions, such as certificate, login, and device registration, are normal. The method is as follows:

Method

Description

public static void beginBasicTest(String platformIp, String platformPort, String appId, String secret, SSLConfig sslConfig)

After setting the platform IP address, port, application ID, secret, and commercial certificate (optional), you can use this method to test whether basic functions, such as certificate, login, and device registration, are normal. If any exception occurs, the cause and suggestion are displayed on the console.