|
| 1 | +# Migrating from 1.x |
| 2 | + |
| 3 | +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/ |
| 4 | + |
| 5 | +Here is the compatibility table: |
| 6 | + |
| 7 | +| Java client version | Socket.IO server | |
| 8 | +| -------------- | ---------------- | |
| 9 | +| 0.9.x | 1.x | |
| 10 | +| 1.x | 2.x | |
| 11 | +| 2.x | 3.x | |
| 12 | + |
| 13 | +**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 |
| 14 | + |
| 15 | +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: |
| 16 | + |
| 17 | +- [A middleware error will now emit an Error object](#A_middleware_error_will_now_emit_an_Error_object) |
| 18 | +- [The Socket `query` option is renamed to `auth`](#The_Socket_query_option_is_renamed_to_auth) |
| 19 | +- [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) |
| 20 | +- [No more "pong" event](#No_more_.E2.80.9Cpong.E2.80.9D_event) |
| 21 | + |
| 22 | +Additional changes which are specific to the Java client: |
| 23 | + |
| 24 | +- [An `extraHeaders` option is now available](#An_extraHeaders_option_is_now_available) |
| 25 | + |
| 26 | +### A middleware error will now emit an Error object |
| 27 | + |
| 28 | +The `ERROR` event is renamed to `CONNECT_ERROR` and the object emitted is now a `JSONObject`: |
| 29 | + |
| 30 | +Before: |
| 31 | + |
| 32 | +```java |
| 33 | +socket.on(Socket.EVENT_ERROR, new Emitter.Listener() { |
| 34 | + @Override |
| 35 | + public void call(Object... args) { |
| 36 | + String error = (String) args[0]; |
| 37 | + System.out.println(error); // not authorized |
| 38 | + } |
| 39 | +}); |
| 40 | +``` |
| 41 | + |
| 42 | +After: |
| 43 | + |
| 44 | +```java |
| 45 | +socket.on(Socket.EVENT_CONNECT_ERROR, new Emitter.Listener() { |
| 46 | + @Override |
| 47 | + public void call(Object... args) { |
| 48 | + JSONObject error = (JSONObject) args[0]; |
| 49 | + String message = error.getString("message"); |
| 50 | + System.out.println(error); // not authorized |
| 51 | + |
| 52 | + JSONObject data = error.getJSONObject("data"); // additional details (optional) |
| 53 | + } |
| 54 | +}); |
| 55 | +``` |
| 56 | + |
| 57 | + |
| 58 | +### The Socket `query` option is renamed to `auth` |
| 59 | + |
| 60 | +In previous versions, the `query` option was used in two distinct places: |
| 61 | + |
| 62 | +- in the query parameters of the HTTP requests (`GET /socket.io/?EIO=3&abc=def`) |
| 63 | +- in the Socket.IO handshake |
| 64 | + |
| 65 | +Which could lead to unexpected behaviors. |
| 66 | + |
| 67 | +New syntax: |
| 68 | + |
| 69 | +```java |
| 70 | +IO.Options options = new IO.Options(); |
| 71 | +options.query = singletonMap("abc", singletonList("def")); // included in the query parameters |
| 72 | +options.auth = singletonMap("token", singletonList("1234")); // included in the Socket.IO handshake |
| 73 | + |
| 74 | +Socket socket = IO.socket("https://example.com", options); |
| 75 | +``` |
| 76 | + |
| 77 | +### The Socket instance will no longer forward the events emitted by its Manager |
| 78 | + |
| 79 | +In previous versions, the Socket instance emitted the events related to the state of the underlying connection. This will not be the case anymore. |
| 80 | + |
| 81 | +You still have access to those events on the Manager instance (the `io()` method of the socket) : |
| 82 | + |
| 83 | +Before: |
| 84 | + |
| 85 | +```java |
| 86 | +socket.on(Socket.EVENT_RECONNECT_ATTEMPT, new Emitter.Listener() { |
| 87 | + @Override |
| 88 | + public void call(Object... objects) { |
| 89 | + // ... |
| 90 | + } |
| 91 | +}); |
| 92 | +``` |
| 93 | + |
| 94 | +After: |
| 95 | + |
| 96 | +```java |
| 97 | +socket.io().on(Manager.EVENT_RECONNECT_ATTEMPT, new Emitter.Listener() { |
| 98 | + @Override |
| 99 | + public void call(Object... objects) { |
| 100 | + // ... |
| 101 | + } |
| 102 | +}); |
| 103 | +``` |
| 104 | + |
| 105 | +Here is the updated list of events emitted by the Manager: |
| 106 | + |
| 107 | +| Name | Description | Previously (if different) | |
| 108 | +| ---- | ----------- | ------------------------- | |
| 109 | +| open | successful (re)connection | - | |
| 110 | +| error | (re)connection failure or error after a successful connection | connect_error | |
| 111 | +| close | disconnection | - | |
| 112 | +| reconnect_attempt | reconnection attempt | reconnect_attempt & reconnecting | - | |
| 113 | +| reconnect | successful reconnection | - | |
| 114 | +| reconnect_error | reconnection failure | - | |
| 115 | +| reconnect_failed | reconnection failure after all attempts | - | |
| 116 | + |
| 117 | +Here is the updated list of events emitted by the Socket: |
| 118 | + |
| 119 | +| Name | Description | Previously (if different) | |
| 120 | +| ---- | ----------- | ------------------------- | |
| 121 | +| connect | successful connection to a Namespace | - | |
| 122 | +| connect_error | connection failure | error | |
| 123 | +| disconnect | disconnection | - | |
| 124 | + |
| 125 | + |
| 126 | +And finally, here's the updated list of reserved events that you cannot use in your application: |
| 127 | + |
| 128 | +- `connect` (used on the client-side) |
| 129 | +- `connect_error` (used on the client-side) |
| 130 | +- `disconnect` (used on both sides) |
| 131 | +- `disconnecting` (used on the server-side) |
| 132 | +- `newListener` and `removeListener` (EventEmitter [reserved events](https://nodejs.org/api/events.html#events_event_newlistener)) |
| 133 | + |
| 134 | +```java |
| 135 | +socket.emit("connect_error"); // will now throw an exception |
| 136 | +``` |
| 137 | + |
| 138 | +### No more "pong" event |
| 139 | + |
| 140 | +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. |
| 141 | + |
| 142 | +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. |
| 143 | + |
| 144 | +Before: |
| 145 | + |
| 146 | +```java |
| 147 | +socket.once(Socket.EVENT_PONG, new Emitter.Listener() { |
| 148 | + @Override |
| 149 | + public void call(Object... args) { |
| 150 | + long latency = (long) args[0]; |
| 151 | + // ... |
| 152 | + } |
| 153 | +}); |
| 154 | +``` |
| 155 | + |
| 156 | +There is no similar API in the new release. |
| 157 | + |
| 158 | +### An `extraHeaders` option is now available |
| 159 | + |
| 160 | +This is a more straightforward way to provide headers that will be included in all HTTP requests. |
| 161 | + |
| 162 | +```java |
| 163 | +IO.Options options = new IO.Options(); |
| 164 | +options.extraHeaders = singletonMap("Authorization", singletonList("Bearer abcd")); |
| 165 | + |
| 166 | +Socket socket = IO.socket("https://example.com", options); |
| 167 | +``` |
| 168 | + |
| 169 | +Or with the new builder syntax: |
| 170 | + |
| 171 | +```java |
| 172 | +IO.Options options = IO.Options.builder() |
| 173 | + .setExtraHeaders(singletonMap("Authorization", singletonList("Bearer abcd"))) |
| 174 | + .build(); |
| 175 | + |
| 176 | +Socket socket = IO.socket("https://example.com", options); |
| 177 | +``` |
0 commit comments