From 7c13e2ca915574e144c61bbfed819276141031b0 Mon Sep 17 00:00:00 2001 From: timtay-microsoft Date: Wed, 13 Nov 2019 14:03:30 -0800 Subject: [PATCH 1/2] doc(device, e2e, prov-dev, service, samples): Fix javadoc issues --- .../microsoft/azure/sdk/iot/device/CustomLogger.java | 4 ++-- .../microsoft/azure/sdk/iot/device/DeviceClient.java | 1 - .../sdk/iot/device/transport/IotHubTransport.java | 4 ++-- .../transport/amqps/AmqpsSessionDeviceOperation.java | 4 +--- .../device/transport/amqps/AmqpsSessionManager.java | 1 - .../microsoft/azure/sdk/iot/ModuleMethodSample.java | 2 +- .../sdk/iot/common/helpers/IotHubServicesCommon.java | 8 ++++++-- .../sdk/iot/common/helpers/SSLContextBuilder.java | 12 ++++++++++++ .../azure/sdk/iot/common/helpers/Tools.java | 2 -- .../iot/common/helpers/X509CertificateGenerator.java | 1 + .../tests/iothubservices/TokenRenewalTests.java | 3 ++- .../common/tests/provisioning/ProvisioningTests.java | 3 ++- .../internal/contract/mqtt/ContractAPIMqtt.java | 2 +- .../azure/sdk/iot/ConfigurationManangerSample.java | 5 ++--- .../microsoft/azure/sdk/iot/DeviceManagerSample.java | 5 ++--- .../azure/sdk/iot/DeviceManagerX509Sample.java | 5 ++--- .../microsoft/azure/sdk/iot/ModuleManagerSample.java | 5 ++--- .../microsoft/azure/sdk/iot/ServiceClientSample.java | 7 +++---- 18 files changed, 41 insertions(+), 33 deletions(-) diff --git a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/CustomLogger.java b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/CustomLogger.java index 4da1dfb8c3..5c78fdb911 100644 --- a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/CustomLogger.java +++ b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/CustomLogger.java @@ -62,8 +62,8 @@ public void LogWarn(String message, Object...params) } /** - * @param message - * @param params + * @param message The message to log + * @param params The parameters to be put into the message * @deprecated Since the switch from Log4j to slf4j there is no fatal log level anymore. Mapped to error level */ public void LogFatal(String message, Object...params) diff --git a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/DeviceClient.java b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/DeviceClient.java index e6766fb7c5..b06da6e724 100644 --- a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/DeviceClient.java +++ b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/DeviceClient.java @@ -276,7 +276,6 @@ public DeviceClient setMessageCallback(MessageCallback callback, Object context) * @param deviceId The id for the device to use * @param securityProvider The security provider for the device * @param protocol The protocol the device shall use for communication to the IoT Hub - * @return The created device client instance * @throws URISyntaxException If the provided connString could not be parsed. * @throws IOException If the SecurityProvider throws any exception while authenticating */ diff --git a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/IotHubTransport.java b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/IotHubTransport.java index ac95938f81..d4ce06874a 100644 --- a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/IotHubTransport.java +++ b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/IotHubTransport.java @@ -669,7 +669,7 @@ else if (e instanceof UnauthorizedException || e instanceof MqttUnauthorizedExce /** * Creates a new iotHubTransportConnection instance, sets this object as its listener, and opens that connection - * @throws TransportException + * @throws TransportException if any exception is thrown while opening the connection */ private void openConnection() throws TransportException { @@ -713,7 +713,7 @@ private void openConnection() throws TransportException /** * Attempts to reconnect. By the end of this call, the state of this object shall be either CONNECTED or DISCONNECTED - * @param transportException + * @param transportException the exception that caused the disconnection */ private void handleDisconnection(TransportException transportException) { diff --git a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/amqps/AmqpsSessionDeviceOperation.java b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/amqps/AmqpsSessionDeviceOperation.java index d464b5d687..7151513753 100644 --- a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/amqps/AmqpsSessionDeviceOperation.java +++ b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/amqps/AmqpsSessionDeviceOperation.java @@ -150,9 +150,7 @@ void closeLinks() /** * Delegate the link initialization call to device operation objects. * - * @param link the link ti initialize. - * @throws TransportException throw if Proton operation throws. - * @throws IllegalArgumentException throw if the link parameter is null. + * @param link the link that was initialized */ void initLink(Link link) { diff --git a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/amqps/AmqpsSessionManager.java b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/amqps/AmqpsSessionManager.java index 7ad3c5e53c..ad08104083 100644 --- a/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/amqps/AmqpsSessionManager.java +++ b/device/iot-device-client/src/main/java/com/microsoft/azure/sdk/iot/device/transport/amqps/AmqpsSessionManager.java @@ -148,7 +148,6 @@ protected void subscribeDeviceToMessageType(MessageType messageType, String devi * Open the session and the links. * * @param connection the Proton connection object to work with. - * @return true if connection is ready, otherwise false to indicate authentication links open in progress */ void onConnectionInit(Connection connection) throws TransportException { diff --git a/device/iot-device-samples/module-method-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleMethodSample.java b/device/iot-device-samples/module-method-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleMethodSample.java index 5a7b2a73e0..40c5798c6e 100644 --- a/device/iot-device-samples/module-method-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleMethodSample.java +++ b/device/iot-device-samples/module-method-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleMethodSample.java @@ -117,7 +117,7 @@ else if (status == IotHubConnectionStatus.CONNECTED) * Receives method calls from IotHub. Default protocol is to use * use MQTT transport. * - * @param args + * @param args The connection string and the selected protocol */ public static void main(String[] args) throws IOException, URISyntaxException, ModuleClientException { diff --git a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/IotHubServicesCommon.java b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/IotHubServicesCommon.java index 990be92b6a..ee05104a99 100644 --- a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/IotHubServicesCommon.java +++ b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/IotHubServicesCommon.java @@ -157,11 +157,15 @@ public void execute(IotHubConnectionStatus status, IotHubConnectionStatusChangeR * * @param client the client to send the messages from * @param protocol the protocol the client is using + * @param numberOfMessages the number of messages to send + * @param breathPeriod time to sleep between checks of message callback arrival + * @param timeoutMilliseconds time to wait for any message to have its callback fired before the test times out + * @param authType the authentication type used is this test */ public static void sendMessagesExpectingSASTokenExpiration(DeviceClient client, String protocol, int numberOfMessages, - long retryMilliseconds, + long breathPeriod, long timeoutMilliseconds, AuthenticationType authType) { @@ -182,7 +186,7 @@ public static void sendMessagesExpectingSASTokenExpiration(DeviceClient client, long startTime = System.currentTimeMillis(); while(!messageSent.wasCallbackFired() || !statusUpdated.getResult()) { - Thread.sleep(retryMilliseconds); + Thread.sleep(breathPeriod); if (System.currentTimeMillis() - startTime > timeoutMilliseconds) { Assert.fail(buildExceptionMessage(protocol + ", " + authType + ": Sending message over " + protocol + " protocol failed: " + diff --git a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/SSLContextBuilder.java b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/SSLContextBuilder.java index 4c6c3bb21a..020ef9f481 100644 --- a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/SSLContextBuilder.java +++ b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/SSLContextBuilder.java @@ -34,6 +34,12 @@ public class SSLContextBuilder /** * Create an SSLContext instance with the provided public and private keys that also trusts the base iot hub certificates + * @param publicKeyCertificateString the public key to use for x509 authentication. Does not need to include the default + * Iot Hub trusted certificate as it will be added automatically + * @param privateKeyString The private key to use for x509 authentication + * @return The created SSLContext that uses the provided public key and private key + * @throws GeneralSecurityException If the certificate creation fails, or if the SSLContext creation using those certificates fails + * @throws IOException If the certificates cannot be read */ public static SSLContext buildSSLContext(String publicKeyCertificateString, String privateKeyString) throws GeneralSecurityException, IOException { @@ -61,6 +67,12 @@ public static SSLContext buildSSLContext(String publicKeyCertificateString, Stri /** * Build the default SSLContext. Trusts the iot hub base certificates, but can only be used for sas auth + * @return the default SSLContext + * @throws NoSuchAlgorithmException If the SSLContext cannot be created because of a missing algorithm + * @throws KeyManagementException If the SSLContext cannot be initiated + * @throws CertificateException If certificate creation fails + * @throws KeyStoreException If the keystore operations fail + * @throws IOException If the default certificate fails to be read */ public static SSLContext buildSSLContext() throws NoSuchAlgorithmException, KeyManagementException, CertificateException, KeyStoreException, IOException { diff --git a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/Tools.java b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/Tools.java index aa47681b66..0889b59a83 100644 --- a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/Tools.java +++ b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/Tools.java @@ -53,8 +53,6 @@ public static boolean isCause(Class possibleExceptionCause, * @param registryManager the registry manager to use. Will not be closed after this call * @param identitiesToDispose the list of modules and or devices to be removed from the iot hub using the provided * registry manager - * @throws IOException if deleting the identity fails - * @throws IotHubException if deleting the identity fails */ public static void removeDevicesAndModules(RegistryManager registryManager, Collection identitiesToDispose) { diff --git a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/X509CertificateGenerator.java b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/X509CertificateGenerator.java index 97419f9fed..7bf16c733d 100644 --- a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/X509CertificateGenerator.java +++ b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/helpers/X509CertificateGenerator.java @@ -64,6 +64,7 @@ public X509CertificateGenerator() /** * Constructor that generates a new self signed x509 certificate. Public certificate, private key, thumbprint, and the complete * certificate can be accessed by getters. The created certificate will have the provided common name. + * @param commonName the common name to use for the created certs */ public X509CertificateGenerator(String commonName) { diff --git a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/iothubservices/TokenRenewalTests.java b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/iothubservices/TokenRenewalTests.java index 060c887a8a..5465ddfe4b 100644 --- a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/iothubservices/TokenRenewalTests.java +++ b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/iothubservices/TokenRenewalTests.java @@ -70,9 +70,10 @@ public static void stopProxy() * Amqps/Amqps_ws : Expect the cbs link to send a new sas token before the old token expires * Mqtt/Mqtt_ws : Expect the connection to be lost briefly, but re-established with a new sas token * Http : No connection status callback, but should be able to send a message after the first generated sas token has expired + * @throws Exception if the test fails in any way */ @Test - public void tokenRenewalWorks() throws URISyntaxException, ModuleClientException, IotHubException, IOException, InterruptedException + public void tokenRenewalWorks() throws Exception { final long SECONDS_FOR_SAS_TOKEN_TO_LIVE_BEFORE_RENEWAL = 60; final long EXPIRED_SAS_TOKEN_GRACE_PERIOD_SECONDS = 600; diff --git a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/provisioning/ProvisioningTests.java b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/provisioning/ProvisioningTests.java index 84a671c254..a0969a55b4 100644 --- a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/provisioning/ProvisioningTests.java +++ b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/provisioning/ProvisioningTests.java @@ -176,7 +176,8 @@ public void individualEnrollmentWithCustomAllocationPolicy() throws Exception * The custom allocation policy has a webhook to an Azure function, and that function will always dictate to provision * the device to the hub with the longest host name. This test verifies that an enrollment with a custom allocation policy * pointing to that Azure function will always enroll to the hub with the longest name - * @param enrollmentType + * @param enrollmentType The type of the enrollment to test + * @throws Exception if an exception occurs during provisioning or while */ protected void customAllocationFlow(EnrollmentType enrollmentType) throws Exception { diff --git a/provisioning/provisioning-device-client/src/main/java/com/microsoft/azure/sdk/iot/provisioning/device/internal/contract/mqtt/ContractAPIMqtt.java b/provisioning/provisioning-device-client/src/main/java/com/microsoft/azure/sdk/iot/provisioning/device/internal/contract/mqtt/ContractAPIMqtt.java index ed007d55ad..57f8f573ae 100644 --- a/provisioning/provisioning-device-client/src/main/java/com/microsoft/azure/sdk/iot/provisioning/device/internal/contract/mqtt/ContractAPIMqtt.java +++ b/provisioning/provisioning-device-client/src/main/java/com/microsoft/azure/sdk/iot/provisioning/device/internal/contract/mqtt/ContractAPIMqtt.java @@ -302,7 +302,7 @@ public synchronized void getRegistrationStatus(RequestData requestData, Response /** * Requests hub to provide a device key to begin authentication over MQTT (Only for TPM) - * @param responseCallback A non {@code null} value for the callback + * @param requestData the request data to be used while requesting nonce for TPM * @param responseCallback A non {@code null} value for the callback * @param authorizationCallbackContext An object for context. Can be {@code null} * @throws ProvisioningDeviceClientException If any of the parameters are invalid ({@code null} or empty) diff --git a/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ConfigurationManangerSample.java b/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ConfigurationManangerSample.java index 8031be1ef9..458f30d37c 100644 --- a/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ConfigurationManangerSample.java +++ b/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ConfigurationManangerSample.java @@ -36,9 +36,8 @@ public class ConfigurationManangerSample /** * A simple sample for doing CRUD operations - * @param args - * @throws IOException - * @throws URISyntaxException + * @param args unused + * @throws Exception If any exception is thrown */ public static void main(String[] args) throws Exception { diff --git a/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/DeviceManagerSample.java b/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/DeviceManagerSample.java index 475ccf9849..42f60aeb46 100644 --- a/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/DeviceManagerSample.java +++ b/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/DeviceManagerSample.java @@ -17,9 +17,8 @@ public class DeviceManagerSample { /** * A simple sample for doing CRUD operations - * @param args - * @throws IOException - * @throws URISyntaxException + * @param args unused + * @throws Exception if any exception is thrown */ public static void main(String[] args) throws Exception { diff --git a/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/DeviceManagerX509Sample.java b/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/DeviceManagerX509Sample.java index b80bf82bab..593301cac7 100644 --- a/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/DeviceManagerX509Sample.java +++ b/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/DeviceManagerX509Sample.java @@ -22,9 +22,8 @@ public class DeviceManagerX509Sample /** * A simple sample for doing CRUD operations involving X509 authenticated devices - * @param args - * @throws IOException - * @throws URISyntaxException + * @param args unused + * @throws Exception if any exception occurs */ public static void main(String[] args) throws Exception { diff --git a/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleManagerSample.java b/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleManagerSample.java index 6c8da67b86..8501c1367c 100644 --- a/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleManagerSample.java +++ b/service/iot-service-samples/device-manager-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleManagerSample.java @@ -19,9 +19,8 @@ public class ModuleManagerSample { /** * A simple sample for doing CRUD operations - * @param args - * @throws IOException - * @throws URISyntaxException + * @param args unused + * @throws Exception if any exception is thrown */ public static void main(String[] args) throws Exception { diff --git a/service/iot-service-samples/service-client-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceClientSample.java b/service/iot-service-samples/service-client-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceClientSample.java index 8ffd314e4c..221e57307c 100644 --- a/service/iot-service-samples/service-client-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceClientSample.java +++ b/service/iot-service-samples/service-client-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ServiceClientSample.java @@ -41,11 +41,10 @@ public class ServiceClientSample private static final int RECEIVER_TIMEOUT = 10000; // Timeout in ms /** - * @param args - * @throws IOException - * @throws URISyntaxException + * @param args Unused + * @throws Exception if any exception occurs */ - public static void main(String[] args) throws IOException, URISyntaxException, Exception + public static void main(String[] args) throws Exception { System.out.println("********* Starting ServiceClient sample..."); From bda1328e4fe9a084cf3968767e02e2ee4b472ab6 Mon Sep 17 00:00:00 2001 From: timtay-microsoft Date: Thu, 14 Nov 2019 08:32:59 -0800 Subject: [PATCH 2/2] address pr comments --- .../com/microsoft/azure/sdk/iot/ModuleMethodSample.java | 3 ++- .../sdk/iot/common/tests/provisioning/ProvisioningTests.java | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/device/iot-device-samples/module-method-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleMethodSample.java b/device/iot-device-samples/module-method-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleMethodSample.java index 40c5798c6e..211932cdde 100644 --- a/device/iot-device-samples/module-method-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleMethodSample.java +++ b/device/iot-device-samples/module-method-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/ModuleMethodSample.java @@ -118,8 +118,9 @@ else if (status == IotHubConnectionStatus.CONNECTED) * use MQTT transport. * * @param args The connection string and the selected protocol + * @throws Exception if any exception is encountered */ - public static void main(String[] args) throws IOException, URISyntaxException, ModuleClientException + public static void main(String[] args) throws Exception { System.out.println("Starting..."); System.out.println("Beginning setup."); diff --git a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/provisioning/ProvisioningTests.java b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/provisioning/ProvisioningTests.java index a0969a55b4..e7940d8c1e 100644 --- a/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/provisioning/ProvisioningTests.java +++ b/iot-e2e-tests/common/src/main/java/com/microsoft/azure/sdk/iot/common/tests/provisioning/ProvisioningTests.java @@ -177,7 +177,7 @@ public void individualEnrollmentWithCustomAllocationPolicy() throws Exception * the device to the hub with the longest host name. This test verifies that an enrollment with a custom allocation policy * pointing to that Azure function will always enroll to the hub with the longest name * @param enrollmentType The type of the enrollment to test - * @throws Exception if an exception occurs during provisioning or while + * @throws Exception if an exception occurs during provisioning or while creating the security provider */ protected void customAllocationFlow(EnrollmentType enrollmentType) throws Exception {