|
| 1 | +## Usage |
| 2 | +Socket.IO-client Java has almost the same api and features with the original JS client. You use `IO#socket` to initialize `Socket`: |
| 3 | + |
| 4 | +```java |
| 5 | +import io.socket.client.IO; |
| 6 | +import io.socket.client.Socket; |
| 7 | +... |
| 8 | + |
| 9 | +Socket socket = IO.socket("http://localhost"); |
| 10 | +socket.on(Socket.EVENT_CONNECT, new Emitter.Listener() { |
| 11 | + |
| 12 | + @Override |
| 13 | + public void call(Object... args) { |
| 14 | + socket.emit("foo", "hi"); |
| 15 | + socket.disconnect(); |
| 16 | + } |
| 17 | + |
| 18 | +}).on("event", new Emitter.Listener() { |
| 19 | + |
| 20 | + @Override |
| 21 | + public void call(Object... args) {} |
| 22 | + |
| 23 | +}).on(Socket.EVENT_DISCONNECT, new Emitter.Listener() { |
| 24 | + |
| 25 | + @Override |
| 26 | + public void call(Object... args) {} |
| 27 | + |
| 28 | +}); |
| 29 | +socket.connect(); |
| 30 | +``` |
| 31 | + |
| 32 | +This Library uses [org.json](https://github.com/stleary/JSON-java) to parse and compose JSON strings: |
| 33 | + |
| 34 | +```java |
| 35 | +// Sending an object |
| 36 | +JSONObject obj = new JSONObject(); |
| 37 | +obj.put("hello", "server"); |
| 38 | +obj.put("binary", new byte[42]); |
| 39 | +socket.emit("foo", obj); |
| 40 | + |
| 41 | +// Receiving an object |
| 42 | +socket.on("foo", new Emitter.Listener() { |
| 43 | + @Override |
| 44 | + public void call(Object... args) { |
| 45 | + JSONObject obj = (JSONObject)args[0]; |
| 46 | + } |
| 47 | +}); |
| 48 | +``` |
| 49 | + |
| 50 | +Options are supplied as follows: |
| 51 | + |
| 52 | +```java |
| 53 | +IO.Options opts = new IO.Options(); |
| 54 | +opts.forceNew = true; |
| 55 | +opts.reconnection = false; |
| 56 | + |
| 57 | +socket = IO.socket("http://localhost", opts); |
| 58 | +``` |
| 59 | + |
| 60 | +You can supply query parameters with the `query` option. NB: if you don't want to reuse a cached socket instance when the query parameter changes, you should use the `forceNew` option, the use case might be if your app allows for a user to logout, and a new user to login again: |
| 61 | + |
| 62 | +```java |
| 63 | +IO.Options opts = new IO.Options(); |
| 64 | +opts.forceNew = true; |
| 65 | +opts.query = "auth_token=" + authToken; |
| 66 | +Socket socket = IO.socket("http://localhost", opts); |
| 67 | +``` |
| 68 | + |
| 69 | +You can get a callback with `Ack` when the server received a message: |
| 70 | + |
| 71 | +```java |
| 72 | +socket.emit("foo", "woot", new Ack() { |
| 73 | + @Override |
| 74 | + public void call(Object... args) {} |
| 75 | +}); |
| 76 | +``` |
| 77 | + |
| 78 | +And vice versa: |
| 79 | + |
| 80 | +```java |
| 81 | +// ack from client to server |
| 82 | +socket.on("foo", new Emitter.Listener() { |
| 83 | + @Override |
| 84 | + public void call(Object... args) { |
| 85 | + Ack ack = (Ack) args[args.length - 1]; |
| 86 | + ack.call(); |
| 87 | + } |
| 88 | +}); |
| 89 | +``` |
| 90 | + |
| 91 | +SSL (HTTPS, WSS) settings: |
| 92 | + |
| 93 | +```java |
| 94 | +OkHttpClient okHttpClient = new OkHttpClient.Builder() |
| 95 | + .hostnameVerifier(myHostnameVerifier) |
| 96 | + .sslSocketFactory(mySSLContext.getSocketFactory(), myX509TrustManager) |
| 97 | + .build(); |
| 98 | + |
| 99 | +// default settings for all sockets |
| 100 | +IO.setDefaultOkHttpWebSocketFactory(okHttpClient); |
| 101 | +IO.setDefaultOkHttpCallFactory(okHttpClient); |
| 102 | + |
| 103 | +// set as an option |
| 104 | +opts = new IO.Options(); |
| 105 | +opts.callFactory = okHttpClient; |
| 106 | +opts.webSocketFactory = okHttpClient; |
| 107 | +socket = IO.socket("https://localhost", opts); |
| 108 | +``` |
| 109 | + |
| 110 | +See the Javadoc for more details. |
| 111 | + |
| 112 | +http://socketio.github.io/socket.io-client-java/apidocs/ |
| 113 | + |
| 114 | +### Transports and HTTP Headers |
| 115 | +You can access transports and their HTTP headers as follows. |
| 116 | + |
| 117 | +```java |
| 118 | +// Called upon transport creation. |
| 119 | +socket.io().on(Manager.EVENT_TRANSPORT, new Emitter.Listener() { |
| 120 | + @Override |
| 121 | + public void call(Object... args) { |
| 122 | + Transport transport = (Transport)args[0]; |
| 123 | + |
| 124 | + transport.on(Transport.EVENT_REQUEST_HEADERS, new Emitter.Listener() { |
| 125 | + @Override |
| 126 | + public void call(Object... args) { |
| 127 | + @SuppressWarnings("unchecked") |
| 128 | + Map<String, List<String>> headers = (Map<String, List<String>>)args[0]; |
| 129 | + // modify request headers |
| 130 | + headers.put("Cookie", Arrays.asList("foo=1;")); |
| 131 | + } |
| 132 | + }); |
| 133 | + |
| 134 | + transport.on(Transport.EVENT_RESPONSE_HEADERS, new Emitter.Listener() { |
| 135 | + @Override |
| 136 | + public void call(Object... args) { |
| 137 | + @SuppressWarnings("unchecked") |
| 138 | + Map<String, List<String>> headers = (Map<String, List<String>>)args[0]; |
| 139 | + // access response headers |
| 140 | + String cookie = headers.get("Set-Cookie").get(0); |
| 141 | + } |
| 142 | + }); |
| 143 | + } |
| 144 | +}); |
| 145 | +``` |
| 146 | + |
| 147 | +## Features |
| 148 | +This library supports all of the features the JS client does, including events, options and upgrading transport. Android is fully supported. |
0 commit comments