From 5e85ca5594c929cdd613fc97f5fb0713970780ce Mon Sep 17 00:00:00 2001 From: Wesley Miaw Date: Mon, 24 Oct 2016 13:01:04 -0700 Subject: [PATCH] Exclude SocketTimeoutException from exceptions considered a cancellation or application-induced interruption. Add documentation listing the exceptions or errors considered a cancellation or application-induced interruption. --- .../java/com/netflix/msl/msg/MslControl.java | 80 +++++++++++-------- core/src/main/javascript/msg/MslControl.js | 58 ++++++++------ 2 files changed, 81 insertions(+), 57 deletions(-) diff --git a/core/src/main/java/com/netflix/msl/msg/MslControl.java b/core/src/main/java/com/netflix/msl/msg/MslControl.java index c7989cda..78581eb3 100644 --- a/core/src/main/java/com/netflix/msl/msg/MslControl.java +++ b/core/src/main/java/com/netflix/msl/msg/MslControl.java @@ -20,6 +20,7 @@ import java.io.InputStream; import java.io.InterruptedIOException; import java.io.OutputStream; +import java.net.SocketTimeoutException; import java.net.URL; import java.nio.channels.ClosedByInterruptException; import java.nio.channels.FileLockInterruptionException; @@ -688,9 +689,18 @@ public void write(final MessageOutputStream output) throws IOException { } /** - * Returns true if the current thread has been interrupted as indicated by - * the {@code Thread#isInterrupted()} method or the type of caught - * throwable. + *

Returns true if the current thread has been interrupted as indicated + * by the {@code Thread#isInterrupted()} method or the type of caught + * throwable.

+ * + *

The following {@code Throwable} types are considered interruptions that the application + * initiated or should otherwise be aware of: + *

* * @param t caught throwable. May be null. * @return true if this thread was interrupted or the exception indicates @@ -703,7 +713,7 @@ protected static boolean cancelled(Throwable t) { return true; while (t != null) { if (t instanceof InterruptedException || - t instanceof InterruptedIOException || + (t instanceof InterruptedIOException && !(t instanceof SocketTimeoutException)) || t instanceof FileLockInterruptionException || t instanceof ClosedByInterruptException) { @@ -3512,12 +3522,13 @@ public MslChannel call() throws MslException, IOException, TimeoutException { *

The returned {@code Future} will return the received * {@code MessageInputStream} on completion or {@code null} if a reply was * automatically sent (for example in response to a handshake request) or - * if the operation was cancelled or interrupted. The returned message may - * be an error message if the maximum number of messages is hit without - * successfully receiving the final message. The {@code Future} may throw - * an {@code ExecutionException} whose cause is a {@code MslException}, - * {@code MslErrorResponseException}, {@code IOException}, or - * {@code TimeoutException}.

+ * if the operation was + * {@link #cancelled(Throwable) cancelled or interrupted}. The returned + * message may be an error message if the maximum number of messages is hit + * without successfully receiving the final message. The {@code Future} may + * throw an {@code ExecutionException} whose cause is a + * {@code MslException}, {@code MslErrorResponseException}, + * {@code IOException}, or {@code TimeoutException}.

* *

The remote entity input and output streams will not be closed in case * the caller wishes to reuse them.

@@ -3559,14 +3570,15 @@ public Future receive(final MslContext ctx, final MessageCon * only contain new application data that is a continuation of the previous * message's application data.

* - *

The returned {@code Future} will return {@code null} if cancelled, - * interrupted, if an error response was received (peer-to-peer only) - * resulting in a failure to establish the communication channel, if the - * response could not be sent with encryption or integrity protection when - * required (trusted network-mode only), if a user cannot be attached to - * the response due to lack of a master token, or if the maximum number of - * messages is hit without sending the message. In these cases the remote - * entity's next message can be received by another call to + *

The returned {@code Future} will return {@code null} if + * {@link #cancelled(Throwable) cancelled or interrupted}, if an error + * response was received (peer-to-peer only) resulting in a failure to + * establish the communication channel, if the response could not be sent + * with encryption or integrity protection when required (trusted network- + * mode only), if a user cannot be attached to the response due to lack of + * a master token, or if the maximum number of messages is hit without + * sending the message. In these cases the remote entity's next message can + * be received by another call to * {@link #receive(MslContext, MessageContext, InputStream, OutputStream, int)}.

* *

The {@code Future} may throw an {@code ExecutionException} whose @@ -3605,9 +3617,9 @@ public Future respond(final MslContext ctx, final MessageContext msg * {@link #request(MslContext, MessageContext, URL, int)}.

* *

The returned {@code Future} will return true on success or false if - * cancelled or interrupted. The {@code Future} may throw an - * {@code ExecutionException} whose cause is a {@code MslException} or - * {@code IOException}.

+ * {@link #cancelled(Throwable) cancelled or interrupted}. The + * {@code Future} may throw an {@code ExecutionException} whose cause is a + * {@code MslException} or {@code IOException}.

* *

The remote entity input and output streams will not be closed in case * the caller wishes to reuse them.

@@ -3645,12 +3657,13 @@ public Future error(final MslContext ctx, final MessageContext msgCtx, * channel. If an error message was received then the MSL channel's message * output stream will be {@code null}.

* - *

The returned {@code Future} will return {@code null} if cancelled or - * interrupted. The returned message may be an error message if the maximum - * number of messages is hit without successfully sending the request and - * receiving the response. The {@code Future} may throw an - * {@code ExecutionException} whose cause is a {@code MslException}, - * {@code IOException}, or {@code TimeoutException}.

+ *

The returned {@code Future} will return {@code null} if + * {@link #cancelled(Throwable) cancelled or interrupted}. The returned + * message may be an error message if the maximum number of messages is hit + * without successfully sending the request and receiving the response. The + * {@code Future} may throw an {@code ExecutionException} whose cause is a + * {@code MslException}, {@code IOException}, or + * {@code TimeoutException}.

* *

The caller must close the returned message input stream and message * outut stream.

@@ -3688,12 +3701,13 @@ public Future request(final MslContext ctx, final MessageContext msg * channel. If an error message was received then the MSL channel's message * output stream will be {@code null}.

* - *

The returned {@code Future} will return {@code null} if cancelled or - * interrupted. The returned message may be an error message if the maximum - * number of messages is hit without successfully sending the request and - * receiving the response. The {@code Future} may throw an - * {@code ExecutionException} whose cause is a {@code MslException}, - * {@code IOException}, or {@code TimeoutException}.

+ *

The returned {@code Future} will return {@code null} if + * {@link #cancelled(Throwable) cancelled or interrupted}. The returned + * message may be an error message if the maximum number of messages is hit + * without successfully sending the request and receiving the response. The + * {@code Future} may throw an {@code ExecutionException} whose cause is a + * {@code MslException}, {@code IOException}, or + * {@code TimeoutException}.

* *

The caller must close the returned message input stream and message * outut stream. The remote entity input and output streams will not be diff --git a/core/src/main/javascript/msg/MslControl.js b/core/src/main/javascript/msg/MslControl.js index aa575d4b..eebb03b0 100644 --- a/core/src/main/javascript/msg/MslControl.js +++ b/core/src/main/javascript/msg/MslControl.js @@ -514,8 +514,15 @@ var MslControl$MslChannel; var NULL_MASTER_TOKEN = {}; /** - * Returns true if the current operation has been interrupted/cancelled as - * indicated by the type of caught error. + *

Returns true if the current operation has been interrupted/cancelled + * as indicated by the type of caught error.

+ * + *

The following error types are considered interruptions or + * cancellations that the application initiated or should otherwise be + * aware of: + *

    + *
  • {@link MslInterruptedException}
    • + *

* * @param {?Error} e caught error. May be null. * @return {boolean} true if the error indicates an operation was @@ -2465,11 +2472,13 @@ var MslControl$MslChannel; *

The returned {@code Future} will return the received * {@code MessageInputStream} on completion or {@code null} if a reply was * automatically sent (for example in response to a handshake request) or - * if the operation was cancelled or interrupted. The returned message may - * be an error message if the maximum number of messages is hit without - * successfully receiving the final message. The {@code Future} may throw - * an {@code ExecutionException} whose cause is a {@code MslException}, - * {@code MslErrorResponseException}, or {@code IOException}.

+ * if the operation was + * {@link #cancelled(Throwable) cancelled or interrupted}. The returned + * message may be an error message if the maximum number of messages is hit + * without successfully receiving the final message. The {@code Future} may + * throw an {@code ExecutionException} whose cause is a + * {@code MslException}, {@code MslErrorResponseException}, + * or {@code IOException}.

* *

The remote entity input and output streams will not be closed in case * the caller wishes to reuse them.

@@ -2520,14 +2529,15 @@ var MslControl$MslChannel; * only contain new application data that is a continuation of the previous * message's application data.

* - *

The returned {@code Future} will return {@code null} if cancelled, - * interrupted, if an error response was received (peer-to-peer only) - * resulting in a failure to establish the communication channel, if the - * response could not be sent with encryption or integrity protection when - * required (trusted network-mode only), if a user cannot be attached to - * the response due to lack of a master token, or if the maximum number of - * messages is hit without sending the message. In these cases the remote - * entity's next message can be received by another call to + *

The returned {@code Future} will return {@code null} if + * {@link #cancelled(Throwable) cancelled or interrupted}, if an error + * response was received (peer-to-peer only) resulting in a failure to + * establish the communication channel, if the response could not be sent + * with encryption or integrity protection when required (trusted network- + * mode only), if a user cannot be attached to the response due to lack of + * a master token, or if the maximum number of messages is hit without + * sending the message. In these cases the remote entity's next message can + * be received by another call to * {@link #receive(MslContext, MessageContext, InputStream, OutputStream, int)}.

* *

The {@code Future} may throw an {@code ExecutionException} whose @@ -2570,9 +2580,9 @@ var MslControl$MslChannel; * {@link #request(MslContext, MessageContext, URL, int)}.

* *

The returned {@code Future} will return true on success or false if - * cancelled or interrupted. The {@code Future} may throw an - * {@code ExecutionException} whose cause is a {@code MslException} or - * {@code IOException}.

+ * {@link #cancelled(Throwable) cancelled or interrupted}. The + * {@code Future} may throw an {@code ExecutionException} whose cause is a + * {@code MslException} or {@code IOException}.

* *

The remote entity input and output streams will not be closed in case * the caller wishes to reuse them.

@@ -2667,12 +2677,12 @@ var MslControl$MslChannel; * channel. If an error message was received then the MSL channel's message * output stream will be {@code null}.

* - *

The returned {@code Future} will return {@code null} if cancelled or - * interrupted. The returned message may be an error message if the maximum - * number of messages is hit without successfully sending the request and - * receiving the response. The {@code Future} may throw an - * {@code ExecutionException} whose cause is a {@code MslException} or - * {@code IOException}.

+ *

The returned {@code Future} will return {@code null} if + * {@link #cancelled(Throwable) cancelled or interrupted}. The returned + * message may be an error message if the maximum number of messages is hit + * without successfully sending the request and receiving the response. The + * {@code Future} may throw an {@code ExecutionException} whose cause is a + * {@code MslException} or {@code IOException}.

*/ request: function request(ctx, msgCtx /* variable arguments */) { if (this._shutdown)