Added BitmessageContext method to resent unacknowledged messages and updated README.md

README.md

@@ -5,10 +5,10 @@ Jabit
 [![Apache 2](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](https://raw.githubusercontent.com/Dissem/Jabit/master/LICENSE)
 [![Visit our IRC channel](https://img.shields.io/badge/irc-%23jabit-blue.svg)](https://kiwiirc.com/client/irc.freenode.net/#jabit)
 
-A Java implementation for the Bitmessage protocol. To build, use command `gradle build` or `./gradlew build`.
+A Java implementation for the Bitmessage protocol. To build, use command
+`gradle build` or `./gradlew build`.
 
-Please note that it still has its limitations, but the API should now be stable. Jabit uses Semantic Versioning, meaning
-as long as the major version doesn't change, nothing should break if you update.
+Please note that it still has its limitations, but the API should now be stable. Jabit uses Semantic Versioning, meaning as long as the major version doesn't change, nothing should break if you update.
 
 #### Master
 [![Build Status](https://travis-ci.org/Dissem/Jabit.svg?branch=master)](https://travis-ci.org/Dissem/Jabit) 
@@ -23,9 +23,7 @@ as long as the major version doesn't change, nothing should break if you update.
 Security
 --------
 
-There are most probably some security issues, me programming this thing all by myself. Jabit doesn't do anything against
-timing attacks yet, for example. Please feel free to use the library, report bugs and maybe even help out. I hope the
-code is easy to understand and work with.
+There are most probably some security issues, me programming this thing all by myself. Jabit doesn't do anything against timing attacks yet, for example. Please feel free to use the library, report bugs and maybe even help out. I hope the code is easy to understand and work with.
 
 Project Status
 --------------
@@ -74,17 +72,22 @@ BitmessageContext ctx = new BitmessageContext.Builder()
         .nodeRegistry(new MemoryNodeRegistry())
         .networkHandler(new NetworkNode())
         .cryptography(new BouncyCryptography())
+        .listener(System.out::println)
         .build();
 ```
-This creates a simple context using a H2 database that will be created in the user's home directory. Next you'll need to
-start the context and decide what happens if a message arrives:
+This creates a simple context using a H2 database that will be created in the user's home directory. In the listener you decide what happens when a message arrives. If you can't use lambdas, you may instead write
 ```Java
-ctx.startup(new BitmessageContext.Listener() {
+        .listener(new BitmessageContext.Listener() {
             @Override
             public void receive(Plaintext plaintext) {
                 // TODO: Notify the user
             }
-});
+        })
+```
+
+Next you'll need to start the context:
+```Java
+ctx.startup()
 ```
 Then you might want to create an identity
 ```Java
@@ -100,3 +103,22 @@ to which you can send some messages
 ```Java
 ctx.send(identity, contact, "Test", "Hello Chris, this is a message.");
 ```
+
+### Housekeeping
+
+As Bitmessage stores all currently valid messages, we'll need to delete expired objects from time to time:
+```Java
+ctx.cleanup();
+```
+If the client runs all the time, it might be a good idea to do this daily or at least weekly. Otherwise, you might just want to clean up on shutdown.
+
+Also, if some messages weren't acknowledged when it expired, they can be resent:
+```Java
+ctx.resendUnacknowledgedMessages();
+```
+This could be triggered periodically, or manually by the user. Please be aware that _if_ there is a message to resend, proof of work needs to be calculated, so to not annoy your users you might not want to trigger it on shutdown. As the client might have been offline for some time, it might as well be wise to wait until it caught up downloading new messages before resending those messages, after all they might be acknowledged by now.
+
+There probably won't happen extremely bad things if you don't - at least not more than otherwise - but you can properly shutdown the network connection by calling
+```Java
+ctx.shutdown();
+```

core/src/main/java/ch/dissem/bitmessage/BitmessageContext.java

@@ -221,10 +221,33 @@ public class BitmessageContext {
         return ctx.getNetworkHandler().send(server, port, request);
     }
 
+    /**
+     * Removes expired objects from the inventory. You should call this method regularly,
+     * e.g. daily and on each shutdown.
+     */
     public void cleanup() {
         ctx.getInventory().cleanup();
     }
 
+    /**
+     * Sends messages again whose time to live expired without being acknowledged. (And whose
+     * recipient is expected to send acknowledgements.
+     * <p>
+     *     You should call this method regularly, but be aware of the following:
+     *     <ul>
+     *         <li>As messages might be sent, POW will be done. It is therefore not advised to
+     *         call it on shutdown.</li>
+     *         <li>It shouldn't be called right after startup, as it's possible the missing
+     *         acknowledgement was sent while the client was offline.</li>
+     *         <li>Other than that, the call isn't expensive as long as there is no message
+     *         to send, so it might be a good idea to just call it every few minutes.</li>
+     *     </ul>
+     * </p>
+     */
+    public void resendUnacknowledgedMessages() {
+        ctx.resendUnacknowledged();
+    }
+
     public boolean isRunning() {
         return ctx.getNetworkHandler().isRunning();
     }

core/src/test/java/ch/dissem/bitmessage/BitmessageContextTest.java

@@ -309,7 +309,7 @@ public class BitmessageContextTest {
         assertTrue(plaintext.getTo().has(Pubkey.Feature.DOES_ACK));
         when(ctx.messages().findMessagesToResend()).thenReturn(Collections.singletonList(plaintext));
         when(ctx.messages().getMessage(any(byte[].class))).thenReturn(plaintext);
-        ctx.internals().resendUnacknowledged();
+        ctx.resendUnacknowledgedMessages();
         verify(ctx.labeler(), timeout(1000).times(1)).markAsSent(eq(plaintext));
     }
 }