diff --git a/README.md b/README.md index 4e60884..3f286d9 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,14 @@ JPushover A simple, minimal (18 KB), zero-dependency convenient class for sending messages to [Pushover][1] in Java. -Supports [Messages API][3] and [Glances API][4], synchronous and asynchronous sending. +Supports [Messages API][3], [Glances API][4] and [OpenClient API][5]. Send synchronous or asynchronous. Requires Java 11. Usage ------------------ -1) Add the jpushover dependency to your pom.xml: +Add the jpushover dependency to your pom.xml: ``` @@ -22,20 +22,16 @@ Usage ``` -2) Use the JPushover object with the required informations were you want +Use the JPushover object with the required informations were you want + +**Message API** ``` -JPushover.newMessage() +JPushover.messageAPI() .withToken("MyToken") .withUser("MyUser") .withMessage("MyMessage") .push(); - -JPushover.newGlance() - .withToken("MyToken") - .withUser("MyUser") - .withText("MyText") - .push(); ``` When using the Message API you can additionally add available options from the official [Pushover documentation][2] @@ -47,7 +43,8 @@ boolean valid = JPushover.newMessage() .withToken("MyToken") .withUser("MyUser") .validate(); -``` +``` + If you want more information and/or the response from the Pushover API, use the PushoverResponse object. @@ -63,6 +60,7 @@ The PushoverResponse will return the raw HTTP status code, along with the raw JS Sending a Message or Glance asynchronous is simple. Just call the pushAsync() method instead of push(). Examples: + ``` JPushover.newMessage() .withToken("MyToken") @@ -79,12 +77,98 @@ JPushover.newGlance() If you are using pushAsync remember to shutdown the ExecutorService that is handling the tasks by calling: - ``` AsyncService.getInstance().shutdown(); ``` +**Glance API** + +``` +JPushover.glanceAPI() + .withToken("MyToken") + .withUser("MyUser") + .withText("MyText") + .push(); +``` + +**OpenClient API** + +Using the OpenClient API is a little bit more complex than Message API or Glance API. + +``` +//Prequisites - You require a message listener that listens for incoming messages + +import de.svenkubiak.jpushover.listener.MessageListener; + +public class MyMessageListener implements MessageListener { + + @Override + public void onMessage() { + // TODO Auto-generated method stub + } + + @Override + public void onError() { + // TODO Auto-generated method stub + } +} + + +//1 - Login (required once!) +PushoverResponse pushoverResponse = JPushover + .openClientAPI() + .login("YourUsername", "YourPassword"); + +//1 - Login with Two-Factor authentication enabled (required once!) +PushoverResponse pushoverResponse = JPushover + .openClientAPI() + .login("YourUsername", "YourPassword", "123456"); + +//2 - Parse secret from JSON response and store it +String secret = MyJsonParser(pushoverResponse.getResponse()); + +//3 - Register a new device (required once) +PushoverResponse pushoverResponse = JPushover + .openClientAPI() + .registerDevice(secret, "YourDeviceName"); + +//4 - Parse deviceId from JSON response and store it +String deviceId = MyJsonParser(pushoverResponse.getResponse()); + +//5 - Create a new class +String deviceId = MyJsonParser(pushoverResponse.getResponse()); + +//6 - Open a new WebSocket connection passing an instance of your message listener +JPushover.openClientAPI().open(secret, deviceId, new MyMessageListener()) + +``` + +Once new messages are pushed to your device the onMessage method of your message listener is called. If an error occurs, the onError message of your message listener is called. + +If you require to close the WebSocket connection, call the close() method and re-open the connection. + + +``` +//Close connection +JPushover.openClientAPI().close(); + +//Re-open +JPushover.openClientAPI().open(secret, deviceId, new MyMessageListener()) + +``` + + +Changelog +------------------ + +6.0.0. - 2021-06-21 + +* Partial API rewrite (breaks backward compatibility) +* Added support for Open Client API + + [1]: https://pushover.net [2]: https://pushover.net/api [3]: https://pushover.net/api [4]: https://pushover.net/api/glances +[5]: https://pushover.net/api/client \ No newline at end of file