break(iot-dev): Rework thrown exceptions, add new device reconnection sample

[timtay-microsoft]

All of DeviceClient, ModuleClient and MultiplexingClient will now share an exception class

public class IotHubClientException extends Exception
{
    @Getter
    boolean isRetryable;

    @Getter
    IotHubStatusCode iotHubStatusCode;
}

We'll still expose the IotHubStatusCode so users can catch for each specific error scenario that they are worried about and have a more general catch for scenarios they are less worried about. For instance:

try
{
    deviceClient.sendEvent(new Message("some message"));
}
catch (IotHubClientException e)
{
    if (e.isRetryable())
    {
        // retry logic
    }
    else
    {
        if (e.getStatusCode() == MESSAGE_TOO_LARGE)
        {
            // break message into smaller chunks
        }
    }
}

In general, here is the before and after for non-open/close operations:

// current sync pattern
public IotHubStatusCode sendEvent(Message message) throws InterruptedException, TimeoutException, IllegalStateException

// current async pattern
public void sendEventAsync(Message message, IotHubEventCallback callback, Object context) throws IllegalStateException 

interface IotHubEventCallback 
{
    void execute(IotHubStatusCode responseStatus, Object context);
}

// proposed sync pattern
public void sendEvent(Message message) throws InterruptedException, IllegalStateException, IotHubClientException

// proposed async pattern
public void sendEventAsync(Message message, IotHubEventCallback callback, Object context) throws IllegalStateException

interface IotHubEventCallback 
{
    void execute(IotHubStatusCode responseStatus, IotHubClientException e, Object context);
}

I want to stop returning IotHubStatusCodes to the user and expecting them to write logic to interpret them, so instead of returning the status code in the sync methods, we'll throw the IotHubClientException derived from the status code instead. Similarly, we'll include that exception in the async callback alongside the status code so that users can ignore the status code and just check the exception.

As a part of this PR, I've included my take on the new "device reconnection sample" that demonstrates best practices for keeping the connection alive and how to retry on each particular operation. It leans heavily on the proposed exception structure. It may be easiest to review the exception structure changes by reviewing this sample

I also renamed a few callback interfaces to keep the subscribeToXYZ() methods consistent with each other

I also added the sent message as a parameter in the callback for when a message was acknowledged by the service

Once this code is signed off, I plan on deleting the current device reconnection sample and replacing it with the new sample I wrote. That way, any user that already had a link to our device reconnection sample will still have a link to our recommended patterns.

[timtay-microsoft]

Incorrectly labeled when this enum was first created to represent 403 errors

[timtay-microsoft]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 4 pipeline(s).

[timtay-microsoft]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 4 pipeline(s).

[timtay-microsoft]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 4 pipeline(s).

[timtay-microsoft]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 4 pipeline(s).

[timtay-microsoft]

Using admin privileges to squash and merge this without horton passing since I need to make changes to horton like we've done a few times now.

[azabbasi]

LGTM