docs: init migration guide

2020-12-16 00:16:28 +01:00
parent 4627329ab0
commit 6a2e0f493d
4 changed files with 205 additions and 1 deletions
--- a/2
+++ b/2
@@ -2,6 +2,6 @@ help: ## print this message
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'

 build-site: ## build the site
-	mvn javadoc:javadoc site -DskipTests
+	mvn clean javadoc:javadoc site -DskipTests

 .PHONY: build-site
--- a/src/site/markdown/changelog.md
+++ b/src/site/markdown/changelog.md
@@ -0,0 +1,18 @@
+
+## [2.0.0](https://github.com/socketio/socket.io-client-java/compare/socket.io-client-1.0.1...socket.io-client-2.0.0) (2020-12-14)
+
+
+### Features
+
+* add options builder ([#304](https://github.com/socketio/socket.io-client-java/issues/304)) ([49068d3](https://github.com/socketio/socket.io-client-java/commit/49068d3cc504c9b83e29a8d5cb4350360c6ef8ea))
+* add support for Socket.IO v3 ([79cb27f](https://github.com/socketio/socket.io-client-java/commit/79cb27fc979ecf1eec9dc2dd4a72c8081149d1e2)), closes [/github.com/socketio/socket.io-protocol#difference-between-v5-and-v4](https://github.com//github.com/socketio/socket.io-protocol/issues/difference-between-v5-and-v4)
+
+
+
+## [1.0.1](https://github.com/socketio/socket.io-client-java/compare/socket.io-client-1.0.0...socket.io-client-1.0.1) (2020-12-10)
+
+
+### Bug Fixes
+
+* don't process socket.connect() if we are already re-connecting ([#577](https://github.com/socketio/socket.io-client-java/issues/577)) ([54b7311](https://github.com/socketio/socket.io-client-java/commit/54b73114d19f33a78bec1ce99325893129f8a148))
+* handle case where URI.getHost() returns null ([#484](https://github.com/socketio/socket.io-client-java/issues/484)) ([567372e](https://github.com/socketio/socket.io-client-java/commit/567372ecfa6c86bdc72f8bc64985d6511dc87666))
--- a/src/site/markdown/migrating_from_1_x.md
+++ b/src/site/markdown/migrating_from_1_x.md
@@ -0,0 +1,177 @@
+# Migrating from 1.x
+
+The `2.0.0` release is the first release which is compatible with the Socket.IO v3 server. You can find more information about the v3 release here: https://socket.io/blog/socket-io-3-release/
+
+Here is the compatibility table:
+
+| Java client version | Socket.IO server |
+| -------------- | ---------------- |
+| 0.9.x  | 1.x |
+| 1.x    | 2.x |
+| 2.x    | 3.x |
+
+**Important note:** due to the backward incompatible changes to the Socket.IO protocol, a 2.x Java client will not be able to reach a 2.x server, and vice-versa
+
+Since the Java client matches the Javascript client quite closely, most of the changes listed in the migration guide [here](https://socket.io/docs/v3/migrating-from-2-x-to-3-0) also apply to the Java client:
+
+- [A middleware error will now emit an Error object](#A_middleware_error_will_now_emit_an_Error_object)
+- [The Socket `query` option is renamed to `auth`](#The_Socket_query_option_is_renamed_to_auth)
+- [The Socket instance will no longer forward the events emitted by its Manager](#The_Socket_instance_will_no_longer_forward_the_events_emitted_by_its_Manager)
+- [No more "pong" event](#No_more_.E2.80.9Cpong.E2.80.9D_event)
+
+Additional changes which are specific to the Java client:
+
+- [An `extraHeaders` option is now available](#An_extraHeaders_option_is_now_available)
+
+### A middleware error will now emit an Error object
+
+The `ERROR` event is renamed to `CONNECT_ERROR` and the object emitted is now a `JSONObject`:
+
+Before:
+
+```java
+socket.on(Socket.EVENT_ERROR, new Emitter.Listener() {
+    @Override
+    public void call(Object... args) {
+        String error = (String) args[0];
+        System.out.println(error); // not authorized
+    }
+});
+```
+
+After:
+
+```java
+socket.on(Socket.EVENT_CONNECT_ERROR, new Emitter.Listener() {
+    @Override
+    public void call(Object... args) {
+        JSONObject error = (JSONObject) args[0];
+        String message = error.getString("message");
+        System.out.println(error); // not authorized
+
+        JSONObject data = error.getJSONObject("data"); // additional details (optional)
+    }
+});
+```
+
+
+### The Socket `query` option is renamed to `auth`
+
+In previous versions, the `query` option was used in two distinct places:
+
+- in the query parameters of the HTTP requests (`GET /socket.io/?EIO=3&abc=def`)
+- in the Socket.IO handshake
+
+Which could lead to unexpected behaviors.
+
+New syntax:
+
+```java
+IO.Options options = new IO.Options();
+options.query = singletonMap("abc", singletonList("def")); // included in the query parameters
+options.auth = singletonMap("token", singletonList("1234")); // included in the Socket.IO handshake
+
+Socket socket = IO.socket("https://example.com", options);
+```
+
+### The Socket instance will no longer forward the events emitted by its Manager
+
+In previous versions, the Socket instance emitted the events related to the state of the underlying connection. This will not be the case anymore.
+
+You still have access to those events on the Manager instance (the `io()` method of the socket) :
+
+Before:
+
+```java
+socket.on(Socket.EVENT_RECONNECT_ATTEMPT, new Emitter.Listener() {
+    @Override
+    public void call(Object... objects) {
+        // ...
+    }
+});
+```
+
+After:
+
+```java
+socket.io().on(Manager.EVENT_RECONNECT_ATTEMPT, new Emitter.Listener() {
+    @Override
+    public void call(Object... objects) {
+        // ...
+    }
+});
+```
+
+Here is the updated list of events emitted by the Manager:
+
+| Name | Description | Previously (if different) |
+| ---- | ----------- | ------------------------- |
+| open | successful (re)connection | - |
+| error | (re)connection failure or error after a successful connection | connect_error |
+| close | disconnection | - |
+| reconnect_attempt | reconnection attempt | reconnect_attempt & reconnecting | - |
+| reconnect | successful reconnection | - |
+| reconnect_error | reconnection failure | - |
+| reconnect_failed | reconnection failure after all attempts | - |
+
+Here is the updated list of events emitted by the Socket:
+
+| Name | Description | Previously (if different) |
+| ---- | ----------- | ------------------------- |
+| connect | successful connection to a Namespace | - |
+| connect_error | connection failure | error |
+| disconnect | disconnection | - |
+
+
+And finally, here's the updated list of reserved events that you cannot use in your application:
+
+- `connect` (used on the client-side)
+- `connect_error` (used on the client-side)
+- `disconnect` (used on both sides)
+- `disconnecting` (used on the server-side)
+- `newListener` and `removeListener` (EventEmitter [reserved events](https://nodejs.org/api/events.html#events_event_newlistener))
+
+```java
+socket.emit("connect_error"); // will now throw an exception
+```
+
+### No more "pong" event
+
+In Socket.IO v2, you could listen to the `pong` event on the client-side, which included the duration of the last health check round-trip.
+
+Due to the reversal of the heartbeat mechanism (more information [here](https://socket.io/blog/engine-io-4-release/#Heartbeat-mechanism-reversal)), this event has been removed.
+
+Before:
+
+```java
+socket.once(Socket.EVENT_PONG, new Emitter.Listener() {
+    @Override
+    public void call(Object... args) {
+        long latency = (long) args[0];
+        // ...
+    }
+});
+```
+
+There is no similar API in the new release.
+
+### An `extraHeaders` option is now available
+
+This is a more straightforward way to provide headers that will be included in all HTTP requests.
+
+```java
+IO.Options options = new IO.Options();
+options.extraHeaders = singletonMap("Authorization", singletonList("Bearer abcd"));
+
+Socket socket = IO.socket("https://example.com", options);
+```
+
+Or with the new builder syntax:
+
+```java
+IO.Options options = IO.Options.builder()
+    .setExtraHeaders(singletonMap("Authorization", singletonList("Bearer abcd")))
+    .build();
+
+Socket socket = IO.socket("https://example.com", options);
+```
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -8,6 +8,10 @@
        <version>1.9</version>
    </skin>

+    <bannerLeft>
+        <name>Socket.IO Java client</name>
+    </bannerLeft>
+
    <custom>
        <fluidoSkin>
            <gitHub>
@@ -22,6 +26,11 @@
        <menu name="Overview">
            <item name="Installation" href="./installation.html"/>
            <item name="Usage" href="./usage.html"/>
+            <item name="Migrating from 1.x" href="./migrating_from_1_x.html"/>
+        </menu>
+
+        <menu name="Miscellaneous">
+            <item name="Changelog" href="./changelog.html"/>
            <item name="Javadoc" href="./apidocs/index.html"/>
        </menu>