diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..cc752f8 --- /dev/null +++ b/Makefile @@ -0,0 +1,7 @@ +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 + +.PHONY: build-site diff --git a/README.md b/README.md index 5b7af7d..3399418 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Add the following dependency to your `pom.xml`. io.socket socket.io-client - 1.0.1/version> + 1.0.1 ``` diff --git a/pom.xml b/pom.xml index b4bd3ca..8a4bb03 100644 --- a/pom.xml +++ b/pom.xml @@ -219,20 +219,9 @@ 2.3 - com.github.github - site-maven-plugin - 0.12 - - Creating site for ${project.version} - - - - - site - - site - - + org.apache.maven.plugins + maven-site-plugin + 3.9.1 diff --git a/src/site/markdown/installation.md b/src/site/markdown/installation.md new file mode 100644 index 0000000..1d7d447 --- /dev/null +++ b/src/site/markdown/installation.md @@ -0,0 +1,33 @@ +## Compatibility + +| Client version | Socket.IO server | +| -------------- | ---------------- | +| 0.9.x | 1.x | +| 1.x | 2.x | +| WIP | 3.x | + +## Installation +The latest artifact is available on Maven Central. + +### Maven +Add the following dependency to your `pom.xml`. + +```xml + + + io.socket + socket.io-client + 1.0.1 + + +``` + +### Gradle +Add it as a gradle dependency for Android Studio, in `build.gradle`: + +```groovy +compile ('io.socket:socket.io-client:1.0.1') { + // excluding org.json which is provided by Android + exclude group: 'org.json', module: 'json' +} +``` diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md new file mode 100644 index 0000000..99f1468 --- /dev/null +++ b/src/site/markdown/usage.md @@ -0,0 +1,148 @@ +## Usage +Socket.IO-client Java has almost the same api and features with the original JS client. You use `IO#socket` to initialize `Socket`: + +```java +import io.socket.client.IO; +import io.socket.client.Socket; +... + +Socket socket = IO.socket("http://localhost"); +socket.on(Socket.EVENT_CONNECT, new Emitter.Listener() { + + @Override + public void call(Object... args) { + socket.emit("foo", "hi"); + socket.disconnect(); + } + +}).on("event", new Emitter.Listener() { + + @Override + public void call(Object... args) {} + +}).on(Socket.EVENT_DISCONNECT, new Emitter.Listener() { + + @Override + public void call(Object... args) {} + +}); +socket.connect(); +``` + +This Library uses [org.json](https://github.com/stleary/JSON-java) to parse and compose JSON strings: + +```java +// Sending an object +JSONObject obj = new JSONObject(); +obj.put("hello", "server"); +obj.put("binary", new byte[42]); +socket.emit("foo", obj); + +// Receiving an object +socket.on("foo", new Emitter.Listener() { + @Override + public void call(Object... args) { + JSONObject obj = (JSONObject)args[0]; + } +}); +``` + +Options are supplied as follows: + +```java +IO.Options opts = new IO.Options(); +opts.forceNew = true; +opts.reconnection = false; + +socket = IO.socket("http://localhost", opts); +``` + +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: + +```java +IO.Options opts = new IO.Options(); +opts.forceNew = true; +opts.query = "auth_token=" + authToken; +Socket socket = IO.socket("http://localhost", opts); +``` + +You can get a callback with `Ack` when the server received a message: + +```java +socket.emit("foo", "woot", new Ack() { + @Override + public void call(Object... args) {} +}); +``` + +And vice versa: + +```java +// ack from client to server +socket.on("foo", new Emitter.Listener() { + @Override + public void call(Object... args) { + Ack ack = (Ack) args[args.length - 1]; + ack.call(); + } +}); +``` + +SSL (HTTPS, WSS) settings: + +```java +OkHttpClient okHttpClient = new OkHttpClient.Builder() + .hostnameVerifier(myHostnameVerifier) + .sslSocketFactory(mySSLContext.getSocketFactory(), myX509TrustManager) + .build(); + +// default settings for all sockets +IO.setDefaultOkHttpWebSocketFactory(okHttpClient); +IO.setDefaultOkHttpCallFactory(okHttpClient); + +// set as an option +opts = new IO.Options(); +opts.callFactory = okHttpClient; +opts.webSocketFactory = okHttpClient; +socket = IO.socket("https://localhost", opts); +``` + +See the Javadoc for more details. + +http://socketio.github.io/socket.io-client-java/apidocs/ + +### Transports and HTTP Headers +You can access transports and their HTTP headers as follows. + +```java +// Called upon transport creation. +socket.io().on(Manager.EVENT_TRANSPORT, new Emitter.Listener() { + @Override + public void call(Object... args) { + Transport transport = (Transport)args[0]; + + transport.on(Transport.EVENT_REQUEST_HEADERS, new Emitter.Listener() { + @Override + public void call(Object... args) { + @SuppressWarnings("unchecked") + Map> headers = (Map>)args[0]; + // modify request headers + headers.put("Cookie", Arrays.asList("foo=1;")); + } + }); + + transport.on(Transport.EVENT_RESPONSE_HEADERS, new Emitter.Listener() { + @Override + public void call(Object... args) { + @SuppressWarnings("unchecked") + Map> headers = (Map>)args[0]; + // access response headers + String cookie = headers.get("Set-Cookie").get(0); + } + }); + } +}); +``` + +## Features +This library supports all of the features the JS client does, including events, options and upgrading transport. Android is fully supported. diff --git a/src/site/site.xml b/src/site/site.xml new file mode 100644 index 0000000..a006f9b --- /dev/null +++ b/src/site/site.xml @@ -0,0 +1,30 @@ + + + + + org.apache.maven.skins + maven-fluido-skin + 1.9 + + + + + + socketio/socket.io-client-java + right + gray + + + + + + + + + + + + + + \ No newline at end of file