From 95ccb1ee52f7336511e0eab54179b6d5e65a31e9 Mon Sep 17 00:00:00 2001 From: Mikael Mengistu Date: Fri, 19 Oct 2018 14:31:05 -0700 Subject: [PATCH] More Java Docs (#3138) --- .../java/com/microsoft/signalr/Action.java | 3 ++ .../java/com/microsoft/signalr/Action1.java | 5 ++ .../java/com/microsoft/signalr/Action2.java | 6 +++ .../java/com/microsoft/signalr/Action3.java | 7 +++ .../java/com/microsoft/signalr/Action4.java | 8 +++ .../java/com/microsoft/signalr/Action5.java | 9 ++++ .../java/com/microsoft/signalr/Action6.java | 10 ++++ .../java/com/microsoft/signalr/Action7.java | 11 ++++ .../java/com/microsoft/signalr/Action8.java | 12 +++++ .../signalr/HttpHubConnectionBuilder.java | 52 +++++++++++++++++++ .../com/microsoft/signalr/HubConnection.java | 36 +++++++++++++ .../signalr/HubConnectionBuilder.java | 14 +++++ .../microsoft/signalr/HubConnectionState.java | 3 ++ .../com/microsoft/signalr/HubException.java | 18 +++++++ .../com/microsoft/signalr/Subscription.java | 8 ++- 15 files changed, 201 insertions(+), 1 deletion(-) diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action.java index a677fd10d4..86d329e2ac 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action.java @@ -3,6 +3,9 @@ package com.microsoft.signalr; +/** + * A callback that takes no parameters. + */ @FunctionalInterface public interface Action { void invoke(); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action1.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action1.java index f5953dc5ff..fae504356f 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action1.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action1.java @@ -3,6 +3,11 @@ package com.microsoft.signalr; +/** + * A callback that takes one parameter. + * + * @param The type of the first parameter to the callback. + */ @FunctionalInterface public interface Action1 { void invoke(T1 param1); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action2.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action2.java index 0b1e369100..7c5d51c0e8 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action2.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action2.java @@ -3,6 +3,12 @@ package com.microsoft.signalr; +/** + * A callback that takes two parameters. + * + * @param The type of the first parameter to the callback. + * @param The type of the second parameter to the callback. + */ @FunctionalInterface public interface Action2 { void invoke(T1 param1, T2 param2); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action3.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action3.java index 0c81dc25c6..b7d65872a9 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action3.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action3.java @@ -3,6 +3,13 @@ package com.microsoft.signalr; +/** + * A callback that takes three parameters. + * + * @param The type of the first parameter to the callback. + * @param The type of the second parameter to the callback. + * @param The type of the third parameter to the callback. + */ @FunctionalInterface public interface Action3 { void invoke(T1 param1, T2 param2, T3 param3); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action4.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action4.java index 8d51885924..69d82365b3 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action4.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action4.java @@ -3,6 +3,14 @@ package com.microsoft.signalr; +/** + * A callback that takes four parameters. + * + * @param The type of the first parameter to the callback. + * @param The type of the second parameter to the callback. + * @param The type of the third parameter to the callback. + * @param The type of the fourth parameter to the callback. + */ @FunctionalInterface public interface Action4 { void invoke(T1 param1, T2 param2, T3 param3, T4 param4); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action5.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action5.java index a7324b8341..266297e452 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action5.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action5.java @@ -3,6 +3,15 @@ package com.microsoft.signalr; +/** + * A callback that takes five parameter. + * + * @param The type of the first parameter to the callback. + * @param The type of the second parameter to the callback. + * @param The type of the third parameter to the callback. + * @param The type of the fourth parameter to the callback. + * @param The type of the fifth parameter to the callback. + */ @FunctionalInterface public interface Action5 { void invoke(T1 param1, T2 param2, T3 param3, T4 param4, T5 param5); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action6.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action6.java index 73d1d6277f..9aaded586d 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action6.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action6.java @@ -3,6 +3,16 @@ package com.microsoft.signalr; +/** + * A callback that takes six parameters. + * + * @param The type of the first parameter to the callback. + * @param The type of the second parameter to the callback. + * @param The type of the third parameter to the callback. + * @param The type of the fourth parameter to the callback. + * @param The type of the fifth parameter to the callback. + * @param The type of the sixth parameter to the callback. + */ @FunctionalInterface public interface Action6 { void invoke(T1 param1, T2 param2, T3 param3, T4 param4, T5 param5, T6 param6); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action7.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action7.java index 3ec7713f44..1fd8c9bbff 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action7.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action7.java @@ -3,6 +3,17 @@ package com.microsoft.signalr; +/** + * A callback that takes seven parameters. + * + * @param The type of the first parameter to the callback. + * @param The type of the second parameter to the callback. + * @param The type of the third parameter to the callback. + * @param The type of the fourth parameter to the callback. + * @param The type of the fifth parameter to the callback. + * @param The type of the sixth parameter to the callback. + * @param The type of the seventh parameter to the callback. + */ @FunctionalInterface public interface Action7 { void invoke(T1 param1, T2 param2, T3 param3, T4 param4, T5 param5, T6 param6, T7 param7); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action8.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action8.java index 72d5ee75cf..d4abd3f8c7 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Action8.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Action8.java @@ -3,6 +3,18 @@ package com.microsoft.signalr; +/** + * A callback that takes eight parameters. + * + * @param The type of the first parameter to the callback. + * @param The type of the second parameter to the callback. + * @param The type of the third parameter to the callback. + * @param The type of the fourth parameter to the callback. + * @param The type of the fifth parameter to the callback. + * @param The type of the sixth parameter to the callback. + * @param The type of the seventh parameter to the callback. + * @param The type of the eighth parameter to the callback. + */ @FunctionalInterface public interface Action8 { void invoke(T1 param1, T2 param2, T3 param3, T4 param4, T5 param5, T6 param6, T7 param7, T8 param8); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/HttpHubConnectionBuilder.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/HttpHubConnectionBuilder.java index 8f5f35d018..33678087ae 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/HttpHubConnectionBuilder.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/HttpHubConnectionBuilder.java @@ -9,6 +9,9 @@ import java.util.Map; import io.reactivex.Single; +/** + * A builder for configuring {@link HubConnection} instances. + */ public class HttpHubConnectionBuilder { private final String url; private Transport transport; @@ -22,36 +25,80 @@ public class HttpHubConnectionBuilder { this.url = url; } + /** + * Sets the transport to be used by the {@link HubConnection}. + * + * @param transport The transport to be used. + * @return This instance of the HttpHubConnectionBuilder. + */ HttpHubConnectionBuilder withTransport(Transport transport) { this.transport = transport; return this; } + /** + * Sets the {@link HttpClient} to be used by the {@link HubConnection}. + * + * @param httpClient The {@link HttpClient} to be used by the {@link HubConnection}. + * @return This instance of the HttpHubConnectionBuilder. + */ HttpHubConnectionBuilder withHttpClient(HttpClient httpClient) { this.httpClient = httpClient; return this; } + /** + * Indicates to the {@link HubConnection} that it should skip the negotiate process. + * Note: This option only works with the Websockets transport and the Azure SignalR Service require the negotiate step. + * + * @param skipNegotiate Boolean indicating if the {@link HubConnection} should skip the negotiate step. + * @return This instance of the HttpHubConnectionBuilder. + */ public HttpHubConnectionBuilder shouldSkipNegotiate(boolean skipNegotiate) { this.skipNegotiate = skipNegotiate; return this; } + /** + * Sets the access token provider for the {@link HubConnection}. + * + * @param accessTokenProvider The access token provider to be used by the {@link HubConnection}. + * @return This instance of the HttpHubConnectionBuilder. + */ public HttpHubConnectionBuilder withAccessTokenProvider(Single accessTokenProvider) { this.accessTokenProvider = accessTokenProvider; return this; } + /** + * Sets the duration the {@link HubConnection} should wait for a Handshake Response from the server. + * + * @param timeout The duration that the {@link HubConnection} should wait for a Handshake Response from the server. + * @return This instance of the HttpHubConnectionBuilder. + */ public HttpHubConnectionBuilder withHandshakeResponseTimeout(Duration timeout) { this.handshakeResponseTimeout = timeout; return this; } + /** + * Sets a collection of Headers for the {@link HubConnection} to send with every Http request. + * + * @param headers A Map representing the collection of Headers that the {@link HubConnection} should send. + * @return This instance of the HttpHubConnectionBuilder. + */ public HttpHubConnectionBuilder withHeaders(Map headers) { this.headers = headers; return this; } + /** + * Sets a single header for the {@link HubConnection} to send. + * + * @param name The name of the header to set. + * @param value The value of the header to be set. + * @return This instance of the HttpHubConnectionBuilder. + */ public HttpHubConnectionBuilder withHeader(String name, String value) { if (headers == null) { this.headers = new HashMap<>(); @@ -60,6 +107,11 @@ public class HttpHubConnectionBuilder { return this; } + /** + * Builds a new instance of {@link HubConnection}. + * + * @return A new instance of {@link HubConnection}. + */ public HubConnection build() { return new HubConnection(url, transport, skipNegotiate, httpClient, accessTokenProvider, handshakeResponseTimeout, headers); } diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnection.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnection.java index fab2f7595c..932cb65352 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnection.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnection.java @@ -55,18 +55,38 @@ public class HubConnection { private final Logger logger = LoggerFactory.getLogger(HubConnection.class); + /** + * Sets the server timeout interval for the connection. + * + * @param serverTimeout The server timeout duration. + */ public void setServerTimeout(Duration serverTimeout) { this.serverTimeout = serverTimeout; } + /** + * Gets the server timeout duration. + * + * @return The server timeout duration. + */ public Duration getServerTimeout() { return this.serverTimeout; } + /** + * Sets the keep alive interval duration. + * + * @param keepAliveInterval The interval at which the connection should send keep alive messages. + */ public void setKeepAliveInterval(Duration keepAliveInterval) { this.keepAliveInterval = keepAliveInterval; } + /** + * Gets the keep alive interval. + * + * @return The interval between keep alive messages. + */ public Duration getKeepAliveInterval() { return this.keepAliveInterval; } @@ -339,6 +359,7 @@ public class HubConnection { /** * Stops a connection to the server. + * * @param errorMessage An error message if the connected needs to be stopped because of an error. * @return A Completable that completes when the connection has been stopped. */ @@ -364,6 +385,7 @@ public class HubConnection { /** * Stops a connection to the server. + * * @return A Completable that completes when the connection has been stopped. */ public Completable stop() { @@ -416,6 +438,15 @@ public class HubConnection { sendHubMessage(invocationMessage); } + /** + * Invokes a hub method on the server using the specified method name and arguments. + * + * @param returnType The expected return type. + * @param method The name of the server method to invoke. + * @param args The arguments used to invoke the server method. + * @param The expected return type. + * @return A Single that yields the return value when the invocation has completed. + */ @SuppressWarnings("unchecked") public Single invoke(Class returnType, String method, Object... args) { String id = connectionState.getNextInvocationId(); @@ -478,6 +509,11 @@ public class HubConnection { logger.trace("Removing handlers for client method: {}.", name); } + /** + * Registers a callback to run when the connection is closed. + * + * @param callback A callback to run when the connection closes. + */ public void onClosed(Consumer callback) { if (onClosedCallbackList == null) { onClosedCallbackList = new ArrayList<>(); diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnectionBuilder.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnectionBuilder.java index 3aee028ee4..dcba7bd0f3 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnectionBuilder.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnectionBuilder.java @@ -3,7 +3,16 @@ package com.microsoft.signalr; +/** + * A builder for configuring {@link HubConnection} instances. + */ public abstract class HubConnectionBuilder { + /** + * Creates a new instance of {@link HttpHubConnectionBuilder}. + * + * @param url The URL of the SignalR hub to connect to. + * @return An instance of {@link HttpHubConnectionBuilder}. + */ public static HttpHubConnectionBuilder create(String url) { if (url == null || url.isEmpty()) { throw new IllegalArgumentException("A valid url is required."); @@ -11,5 +20,10 @@ public abstract class HubConnectionBuilder { return new HttpHubConnectionBuilder(url); } + /** + * Builds a new instance of {@link HubConnection}. + * + * @return A new instance of {@link HubConnection}. + */ public abstract HubConnection build(); } \ No newline at end of file diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnectionState.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnectionState.java index 6a55fc3fc2..a357946b6a 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnectionState.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/HubConnectionState.java @@ -3,6 +3,9 @@ package com.microsoft.signalr; +/** + * Indicates the state of the {@link HubConnection}. + */ public enum HubConnectionState { CONNECTED, DISCONNECTED, diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/HubException.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/HubException.java index a5f44433e4..189b222182 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/HubException.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/HubException.java @@ -3,16 +3,34 @@ package com.microsoft.signalr; +/** + * An exception thrown when the server fails to invoke a Hub method. + */ public class HubException extends RuntimeException { private static final long serialVersionUID = -572019264269821519L; + /** + * Initializes a new instance of the {@link HubException} class. + */ public HubException() { } + /** + * Initializes a new instance of the {@link HubException} class with a specified error message. + * + * @param errorMessage The error message that explains the reason for the exception. + */ public HubException(String errorMessage) { super(errorMessage); } + /** + * Initializes a new instance of the {@link HubException} class with a specified error message and a reference + * to the exception that is the cause of this exception. + * + * @param errorMessage The error message that explains the reason for the exception. + * @param innerException The exception that is the cause of the current exception, or null if no inner exception is specified. + */ public HubException(String errorMessage, Exception innerException) { super(errorMessage, innerException); } diff --git a/clients/java/signalr/src/main/java/com/microsoft/signalr/Subscription.java b/clients/java/signalr/src/main/java/com/microsoft/signalr/Subscription.java index 0ce344959d..07f39b7d62 100644 --- a/clients/java/signalr/src/main/java/com/microsoft/signalr/Subscription.java +++ b/clients/java/signalr/src/main/java/com/microsoft/signalr/Subscription.java @@ -5,17 +5,23 @@ package com.microsoft.signalr; import java.util.List; +/** + * Represents the registration of a handler for a client method. + */ public class Subscription { private final CallbackMap handlers; private final InvocationHandler handler; private final String target; - public Subscription(CallbackMap handlers, InvocationHandler handler, String target) { + Subscription(CallbackMap handlers, InvocationHandler handler, String target) { this.handlers = handlers; this.handler = handler; this.target = target; } + /** + * Removes the client method handler represented by this subscription. + */ public void unsubscribe() { List handler = this.handlers.get(target); if (handler != null) {