Skip to content

Commit

Permalink
Exclude SocketTimeoutException from exceptions considered a cancellat…
Browse files Browse the repository at this point in the history 
…ion or application-induced interruption.

Add documentation listing the exceptions or errors considered a cancellation or application-induced interruption.
  • Loading branch information
@wmiaw
wmiaw committed Oct 24, 2016
1 parent 1661ea1 commit 5e85ca5
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 57 deletions.
80 changes: 47 additions & 33 deletions core/src/main/java/com/netflix/msl/msg/MslControl.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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.
* <p>Returns true if the current thread has been interrupted as indicated
* by the {@code Thread#isInterrupted()} method or the type of caught
* throwable.</p>
*
* <p>The following {@code Throwable} types are considered interruptions that the application
* initiated or should otherwise be aware of:
* <ul>
* <li>{@link InterruptedException}</li>
* <li>{@link InterruptedIOException} except for {@link SocketTimeoutException}</li>
* <li>{@link FileLockInterruptionException}</li>
* <li>{@link ClosedByInterruptException}</li>
* </ul></p>
*
* @param t caught throwable. May be null.
* @return true if this thread was interrupted or the exception indicates
Expand All @@ -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)
{
Expand Down Expand Up @@ -3512,12 +3522,13 @@ public MslChannel call() throws MslException, IOException, TimeoutException {
* <p>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}.</p>
* 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}.</p>
*
* <p>The remote entity input and output streams will not be closed in case
* the caller wishes to reuse them.</p>
Expand Down Expand Up @@ -3559,14 +3570,15 @@ public Future<MessageInputStream> receive(final MslContext ctx, final MessageCon
* only contain new application data that is a continuation of the previous
* message's application data.</p>
*
* <p>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
* <p>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)}.</p>
*
* <p>The {@code Future} may throw an {@code ExecutionException} whose
Expand Down Expand Up @@ -3605,9 +3617,9 @@ public Future<MslChannel> respond(final MslContext ctx, final MessageContext msg
* {@link #request(MslContext, MessageContext, URL, int)}.</p>
*
* <p>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}.</p>
* {@link #cancelled(Throwable) cancelled or interrupted}. The
* {@code Future} may throw an {@code ExecutionException} whose cause is a
* {@code MslException} or {@code IOException}.</p>
*
* <p>The remote entity input and output streams will not be closed in case
* the caller wishes to reuse them.</p>
Expand Down Expand Up @@ -3645,12 +3657,13 @@ public Future<Boolean> 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}.</p>
*
* <p>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}.</p>
* <p>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}.</p>
*
* <p>The caller must close the returned message input stream and message
* outut stream.</p>
Expand Down Expand Up @@ -3688,12 +3701,13 @@ public Future<MslChannel> 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}.</p>
*
* <p>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}.</p>
* <p>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}.</p>
*
* <p>The caller must close the returned message input stream and message
* outut stream. The remote entity input and output streams will not be
Expand Down
58 changes: 34 additions & 24 deletions core/src/main/javascript/msg/MslControl.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
* <p>Returns true if the current operation has been interrupted/cancelled
* as indicated by the type of caught error.</p>
*
* <p>The following error types are considered interruptions or
* cancellations that the application initiated or should otherwise be
* aware of:
* <ul>
* <li>{@link MslInterruptedException}</li>
* </ul></p>
*
* @param {?Error} e caught error. May be null.
* @return {boolean} true if the error indicates an operation was
Expand Down Expand Up @@ -2465,11 +2472,13 @@ var MslControl$MslChannel;
* <p>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}.</p>
* 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}.</p>
*
* <p>The remote entity input and output streams will not be closed in case
* the caller wishes to reuse them.</p>
Expand Down Expand Up @@ -2520,14 +2529,15 @@ var MslControl$MslChannel;
* only contain new application data that is a continuation of the previous
* message's application data.</p>
*
* <p>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
* <p>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)}.</p>
*
* <p>The {@code Future} may throw an {@code ExecutionException} whose
Expand Down Expand Up @@ -2570,9 +2580,9 @@ var MslControl$MslChannel;
* {@link #request(MslContext, MessageContext, URL, int)}.</p>
*
* <p>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}.</p>
* {@link #cancelled(Throwable) cancelled or interrupted}. The
* {@code Future} may throw an {@code ExecutionException} whose cause is a
* {@code MslException} or {@code IOException}.</p>
*
* <p>The remote entity input and output streams will not be closed in case
* the caller wishes to reuse them.</p>
Expand Down Expand Up @@ -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}.</p>
*
* <p>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}.</p>
* <p>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}.</p>
*/
request: function request(ctx, msgCtx /* variable arguments */) {
if (this._shutdown)
Expand Down

0 comments on commit 5e85ca5

Please sign in to comment.