python+java send related updates

chapters/chapter_5/section_1.md

@@ -114,10 +114,41 @@ class LogDestination(object):
     def send(self, msg):
         """Send a message to the target service
 
-        It should return True to indicate success, False will suspend the
-        destination for a period specified by the time-reopen() option."""
+        It can return boolean. Since 3.20, it can return integer
+        alternatively.
+        Boolean: True to indicate success, False will suspend the
+        destination for a period specified by the time-reopen() option.
+        After that the same message is retried until retries() times.
+
+        Integer:
+        self.SUCCESS: message sending was successful (same as boolean True)
+        self.ERROR: message sending was unsuccessful. Same message is retried.
+            (same as boolean False)
+        self.DROP: message cannot be sent, it should be dropped immediately.
+        self.QUEUED: message is not sent immediately, it will be sent with the flush method.
+        self.NOT_CONNECTED: message is put back to the queue, open method will be called until success.
+        self.RETRY: message is put back to the queue, try to send again until 3 times, then fallback to self.NOT_CONNECTED."""
+
         return True
 
+    def flush(self):
+        """Flush the queued messages
+
+        Since 3.20. It can return either a boolean or integer.
+        Send needs to return with self.QUEUED in order to work.
+        Boolean: True to indicate that the batch is successfully sent.
+        False indicates error while sending the batch. The destination is suspended
+        for time-reopen period. The messages in the batch are passed again to send, one by one.
+
+        Integer:
+        self.SUCCESS: batch sending was successful (same as boolean True)
+        self.ERROR: batch sending was unsuccessful. (same as boolean False)
+        self.DROP: batch cannot be sent, the messages should be dropped immediately.
+        self.NOT_CONNECTED: the messages in the batch is put back to the queue,
+            open method will be called until success.
+        self.RETRY: message is put back to the queue, try to send again until 3 times, then fallback to self.NOT_CONNECTED."""
+
+        return True
 
 class TextDestination(LogDestination):
     def __init__(self):

chapters/chapter_5/section_2.md

@@ -5,7 +5,7 @@ Java is one of the most widely used programming languages, and being able to wri
 
 ###The syslog-ng configuration file
 
-To create a Java destination, you will have to specify the destination of your compiled Java destination in your syslog-ng configuration file. It must be compiled into either a `.class` file or a `.jar` file. 
+To create a Java destination, you will have to specify the destination of your compiled Java destination in your syslog-ng configuration file. It must be compiled into either a `.class` file or a `.jar` file.
 If compiled into a `.class` file, the class path argument must be the folder containing the `.class` file.
 
 The following example demonstrates a Java destination in the configuration file, where the Java destination is compiled to a `.class` file:
@@ -62,9 +62,17 @@ public class SampleJavaDestination extends TextLogDestination {
     ...
     }
 
+    // since 3.20
+    public int flush() {
+      // In order to work, send must return with QUEUED.
+      ...
+      return SUCCESS;
+    }
+
+    // Removed in 3.20, replaced with flush
     public void onMessageQueueEmpty(){
     ...
-    }   
+    }
 
     public boolean init(){
     ...
@@ -75,17 +83,23 @@ public class SampleJavaDestination extends TextLogDestination {
     }
 
     public boolean isOpened(){
-    ... 
+    ...
     }
 
     public void close(){
     ...
     }
 
-    public boolean send(String message){
+    // After 3.20
+    public int send(String message){
     ...
     }
 
+    // Before 3.20
+    // public boolean send(String message){
+    //...
+    //}
+
 
 ```
 
@@ -95,6 +109,18 @@ When syslog-ng starts, it will create an instance of the class, then attempt to
 
 Whenever a new message is generated and fed to your Java class, the send function will be called and passed the message as a String.
 
+Return values of `send`:
+Since 3.20: send returns int. The following values are available:
+
+DROP: message is dropped by syslog-ng.
+ERROR: message is retried later (`retries` times, suspending destination for `time-reopen` in between)
+SUCCESS: send was successful
+QUEUED: destination wants to handle messages as batch, and successfully added the message to the batch. One needs to override `flush` for batching to work.
+NOT_CONNECTED: Message is put back to the queue, destination is suspended for `time-reopen` seconds.
+RETRY: message is retried immediately. After 3rd retry attempt, the message is dropped. This case is similar to ERROR, the difference is that the destination is not suspended between the attemts in the RETRY case.
+
+Prior to 3.20: send returns boolean. True is equivalent to SUCCESS. False is equivalent to ERROR.
+
 The next example is a complete (albeit basic) example. A Java class takes messages and logs them to a file, using the destination defined above.
 
 #### Example: Java file ####
@@ -190,12 +216,12 @@ public class SampleJavaDestination extends TextLogDestination {
         catch (Exception e)
         {
             InternalMessageSender.error("error in writing message :" + message);
-            return false;
+            return ERROR;
         }
-        return true;
+        return SUCCESS;
     }
 }
-        
+
 ```
 ### Java-specific notes
 To use a syslog-ng Java destination, you have to add the path of the `libjvm.so` to the `LD_LIBRARY_PATH`.