Show server output flag, closes #19 + improving test cases #11

- ExternalProcessAsciidoctorJServerLauncher provides now
  possibility to show server output or not
- because of race condition problems different testclasses are now
  using different ports
- Added another example code snippet and linked it inside
  documentation and README.md

README.adoc

@@ -52,8 +52,9 @@ You can use ASP server either as an external process or as an embedded server.
 
 ==== As an external process
 For this case a specialized launcher was created. Just use `ExternalProcessAsciidoctorJServerLauncher` as done in 
-https://github.com/de-jcup/asp/blob/master/asp-doc/src/test/java/de/jcup/asp/example/ExternalProcessExample.java
+https://github.com/de-jcup/asp/blob/master/asp-doc/src/test/java/de/jcup/asp/example/ExternalProcessExample.java[ExternalProcessExample.java] and
+https://github.com/de-jcup/asp/blob/master/asp-doc/src/test/java/de/jcup/asp/example/ExternalProcessWithDebugOutputExample.java[ExternalProcessWithDebugOutputExample.java] 
 
 ==== As embedded server
-Same as external variant, but use `EmbeddedAsciidoctorJServerLauncher` as launcher.
+Same as external variant, but use `EmbeddedAsciidoctorJServerLauncher` as launcher. For examples look into integration tests.
 

asp-api/src/main/java/de/jcup/asp/api/ProtocolData.java

@@ -16,7 +16,7 @@ class ProtocolData {
     }
 
     static ProtocolData convertFromString(String data) throws ProtocolDataException {
-           LOG.debug("convert from String:{}",data);
+           LOG.trace("convert from String:{}",data);
 
            ProtocolData r = new ProtocolData();
            if (data==null) {

asp-client-java/src/main/java/de/jcup/asp/client/AspClientAction.java

@@ -102,7 +102,7 @@ private Response internalCallServer(Request r, AspClientProgressMonitor monitor)
                 if (encryptedfromServer.equals(Response.TERMINATOR)) {
                     break;
                 }
-                LOG.debug("receiving-encrypted:{}", encryptedfromServer);
+                LOG.trace("receiving-encrypted:{}", encryptedfromServer);
                 String fromServer = cryptoAccess.decrypt(encryptedfromServer);
                 if (communicationListener!=null) {
                     communicationListener.receiving(fromServer);

asp-doc/src/doc/asciidoc/documentation.adoc

@@ -11,13 +11,20 @@ include::./../../test/java/de/jcup/asp/example/ExternalProcessExample.java[tags=
 ----
 <1> Create the launcher
 <2> Launch server (timeout for server start is defined with 30 seconds) and fetch secret key for
-    encrypted clienet server communication 
+    encrypted client server communication 
 <3> Create new client, with secret key
 <4> Set some options - in this case we only setup backend to HTML
 <5> Execute convert file action
 <6> *Important:* This will terminate external process, otherwise ASP server will keep on running after this JVM has stopped!
 
-TIP: Complete example code can be found at https://github.com/de-jcup/asp/tree/master/asp-doc/src/test/java/ExternalProcessExample.java
+
+[TIP] 
+====
+Complete example code can be found at https://github.com/de-jcup/asp/tree/master/asp-doc/src/test/java/ExternalProcessExample.java
+
+An additional example with debug information output is available at
+https://github.com/de-jcup/asp/tree/master/asp-doc/src/test/java/ExternalProcessWithDebugOutputExample
+====
 
 == Architecture
 === Communication protocol

asp-doc/src/test/java/de/jcup/asp/example/ExternalProcessExample.java

@@ -14,6 +14,7 @@
 
 public class ExternalProcessExample {
 
+
     public static void main(String[] args) throws Exception {
         Path adocfile = createExampleAsciidocFile();
         String pathToServerJar = ensurePathToServerDistJar();
@@ -28,7 +29,7 @@ public static void main(String[] args) throws Exception {
             AspClient client = new AspClient(serverSecret); // <3>
             client.setPortNumber(4449);
 
-            /* now convert asciidoc to HTML by the ASP client */
+            /* now convert Asciidoc to HTML by ASP client */
             Map<String, Object> options = new HashMap<String, Object>();
             options.put("backend", "html");// <4>
 
@@ -45,7 +46,7 @@ public static void main(String[] args) throws Exception {
 
     }
 
-    private static Path createExampleAsciidocFile() throws IOException {
+     static Path createExampleAsciidocFile() throws IOException {
         Path adocfile = Files.createTempFile("asp_test", ".adoc");
         Files.write(adocfile, (":toc:\n== Headline1\nSome text...\n\n== Headline2\nThis is just an example content for ASP...").getBytes());
         return adocfile;

asp-doc/src/test/java/de/jcup/asp/example/ExternalProcessWithDebugOutputExample.java

@@ -0,0 +1,80 @@
+package de.jcup.asp.example;
+
+import java.awt.Desktop;
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.Map;
+
+import de.jcup.asp.api.Response;
+import de.jcup.asp.client.AspClient;
+import de.jcup.asp.core.OutputHandler;
+import de.jcup.asp.server.asciidoctorj.launcher.ExternalProcessAsciidoctorJServerLauncher;
+
+public class ExternalProcessWithDebugOutputExample {
+
+
+    public static void main(String[] args) throws Exception {
+        Path adocfile = createExampleAsciidocFile();
+        String pathToServerJar = ensurePathToServerDistJar();
+        OutputHandler launcherOutputHandler = new OutputHandler() {
+
+            @Override
+            public void output(String message) {
+               System.out.println("LAUNCHER: "+message);
+            }
+        };
+        OutputHandler clientOutputHandler = new OutputHandler() {
+
+            @Override
+            public void output(String message) {
+               System.out.println("CLIENT: "+message);
+            }
+        };
+        // tag::launcherExample[]
+        ExternalProcessAsciidoctorJServerLauncher launcher = new ExternalProcessAsciidoctorJServerLauncher(pathToServerJar, 4449); // <1>
+        launcher.setOutputHandler(launcherOutputHandler);
+        launcher.setShowServerOutput(true);
+        try {
+            /* launch server*/
+            String serverSecret = launcher.launch(30); // <2>
+
+            /* create client with secret from server for encrypted communication */
+            AspClient client = new AspClient(serverSecret); // <3>
+            client.setPortNumber(4449);
+            client.setOutputHandler(clientOutputHandler);
+            client.setShowCommunication(true);
+
+            /* now convert Asciidoc to HTML by ASP client */
+            Map<String, Object> options = new HashMap<String, Object>();
+            options.put("backend", "html");// <4>
+
+            /* get the result and show it inside browser:*/
+            Response response = client.convertFile(adocfile, options, null);// <5>
+            Path resultFile = response.getResultFilePath();
+
+            Desktop.getDesktop().open(resultFile.toFile());
+        }finally {
+            launcher.stopServer(); //<6>
+        }
+        // end::launcherExample[]
+
+
+    }
+
+    private static Path createExampleAsciidocFile() throws IOException {
+        Path adocfile = Files.createTempFile("asp_test", ".adoc");
+        Files.write(adocfile, (":toc:\n== Headline1\nSome text...\n\n== Headline2\nThis is just an example content for ASP...").getBytes());
+        return adocfile;
+    }
+
+    private static String ensurePathToServerDistJar() {
+        String pathToServerJar= System.getProperty("user.home")+ "/.m2/repository/de/jcup/asp/asp-server-asciidoctorj/0.3.0/asp-server-asciidoctorj-0.3.0-dist.jar";
+        if (! new File(pathToServerJar).exists()) {
+            throw new RuntimeException("Distribution jar missing - please download server distribution into your local maven repository");
+        }
+        return pathToServerJar;
+    }
+}

asp-integrationtest/src/test/java/de/jcup/asp/integrationtest/TestConstants.java

@@ -0,0 +1,7 @@
+package de.jcup.asp.integrationtest;
+
+public class TestConstants {
+
+    public static final int EXTERNAL_PROCESS_PORT=4447;
+    public static final int EMBEDDED_TESTSERVER_PORT=4448;
+}

asp-integrationtest/src/test/java/de/jcup/asp/server/asciidoctorj/CancelOperationTest.java

@@ -16,6 +16,7 @@
 import de.jcup.asp.client.AspClient;
 import de.jcup.asp.client.DefaultAspClientProgressMonitor;
 import de.jcup.asp.integrationtest.FakeRequestHandler;
+import de.jcup.asp.integrationtest.TestConstants;
 import de.jcup.asp.integrationtest.TestServerSupport;
 import de.jcup.asp.integrationtest.TimeAssertData;
 public class CancelOperationTest {
@@ -29,7 +30,7 @@ public class CancelOperationTest {
     public void before() throws Exception{
         fakeRequestHandler = new FakeRequestHandler();
         integrationTestServersupport = new TestServerSupport(fakeRequestHandler);
-        client = integrationTestServersupport.launchServerAndGetPreparedClient(4447);
+        client = integrationTestServersupport.launchServerAndGetPreparedClient(TestConstants.EMBEDDED_TESTSERVER_PORT);
     }
 
     @After

asp-integrationtest/src/test/java/de/jcup/asp/server/asciidoctorj/EmbeddedAsciidoctorJServerLauncherIntTest.java

@@ -18,6 +18,7 @@
 import de.jcup.asp.client.AspClient;
 import de.jcup.asp.core.CryptoAccess;
 import de.jcup.asp.core.LaunchException;
+import de.jcup.asp.integrationtest.TestConstants;
 
 public class EmbeddedAsciidoctorJServerLauncherIntTest {
 
@@ -29,7 +30,7 @@ public class EmbeddedAsciidoctorJServerLauncherIntTest {
 
     @Before
     public void before() {
-        port = 4447;
+        port = TestConstants.EMBEDDED_TESTSERVER_PORT+1;
         launcherToTest = new EmbeddedAsciidoctorJServerLauncher();
     }
 

asp-integrationtest/src/test/java/de/jcup/asp/server/asciidoctorj/ShowCommunicationTest.java

@@ -15,6 +15,7 @@
 import de.jcup.asp.api.Response;
 import de.jcup.asp.client.AspClient;
 import de.jcup.asp.integrationtest.AdocTestFiles;
+import de.jcup.asp.integrationtest.TestConstants;
 import de.jcup.asp.integrationtest.TestOutputHandler;
 import de.jcup.asp.integrationtest.TestServerSupport;
 import de.jcup.asp.server.asciidoctorj.service.ConvertLocalFileService;
@@ -39,7 +40,7 @@ public void convertFile(Request request, Response response) {
                 };
             }
         });
-        client = integrationTestServersupport.launchServerAndGetPreparedClient(4447);
+        client = integrationTestServersupport.launchServerAndGetPreparedClient(TestConstants.EMBEDDED_TESTSERVER_PORT+2);
         client.setOutputHandler(testoutputhandler);
     }
 

asp-integrationtest/src/test/java/de/jcup/asp/server/asciidoctorj/launcher/ExternalProcessAsciidoctorJServerLauncherIntTest.java

@@ -18,6 +18,7 @@
 import de.jcup.asp.client.DefaultAspClientProgressMonitor;
 import de.jcup.asp.core.OutputHandler;
 import de.jcup.asp.integrationtest.FullIntegrationTestRule;
+import de.jcup.asp.integrationtest.TestConstants;
 
 public class ExternalProcessAsciidoctorJServerLauncherIntTest {
 
@@ -33,7 +34,7 @@ public class ExternalProcessAsciidoctorJServerLauncherIntTest {
 
     @Before
     public void before() {
-        port = 4447;
+        port = TestConstants.EXTERNAL_PROCESS_PORT;
         launcherToTest = new ExternalProcessAsciidoctorJServerLauncher(fullIntegrationTestRule.getEnsuredPathToServerJar(), port);
         launcherToTest.setOutputHandler(new OutputHandler() {
 

asp-server-asciidoctorj-launcher/src/main/java/de/jcup/asp/server/asciidoctorj/launcher/ExternalProcessAsciidoctorJServerLauncher.java

@@ -17,12 +17,13 @@
 import de.jcup.asp.core.ServerExitCodes;
 
 /**
- * This ASP launcher will create a new java process and start ASP server from given path to jar.
- * A {@link OutputHandler} can be set to obtain error and normal output from processs.
+ * This ASP launcher will create a new java process and start ASP server from
+ * given path to jar. A {@link OutputHandler} can be set to obtain error and
+ * normal output from processs.
  *
  */
 public class ExternalProcessAsciidoctorJServerLauncher implements ASPLauncher {
-    
+
     private int port;
     private String pathToJava;
     private String pathToServerJar;
@@ -31,65 +32,69 @@ public class ExternalProcessAsciidoctorJServerLauncher implements ASPLauncher {
     private Process process;
     private OutputHandler outputHandler;
     private LogHandler logHandler;
+    private boolean showServerOutput;
 
     public ExternalProcessAsciidoctorJServerLauncher(String pathToServerJar, int port) {
-        this(null, pathToServerJar,port);
+        this(null, pathToServerJar, port);
     }
 
-    public ExternalProcessAsciidoctorJServerLauncher(String pathTojava, String pathToServerJar,int port) {
+    public ExternalProcessAsciidoctorJServerLauncher(String pathTojava, String pathToServerJar, int port) {
         this.pathToJava = pathTojava;
         this.pathToServerJar = pathToServerJar;
-        this.port=port;
+        this.port = port;
     }
-    
+
     public void setShowSecretKey(boolean showSecretKey) {
         this.showSecretKey = showSecretKey;
     }
 
+    public void setShowServerOutput(boolean showServerOutput) {
+        this.showServerOutput = showServerOutput;
+    }
+
     /**
      * Launches an asp-server-asciidoctorj instance inside own process.
      * 
      * @return secret server key
      */
-    public String launch(int timeOutInSeconds) throws LaunchException{
+    public String launch(int timeOutInSeconds) throws LaunchException {
         ServerStartRunnable runnable = new ServerStartRunnable(port);
         Thread thread = new Thread(runnable, "ASP Launcher, port:" + port);
         thread.setDaemon(true);
         thread.start();
-     
+
         waitForSecretKey(timeOutInSeconds, runnable);
         return runnable.secretKey;
     }
 
     private void waitForSecretKey(int timeOutInSeconds, ServerStartRunnable runnable) throws LaunchException {
         Duration acceptedmax = Duration.ofSeconds(timeOutInSeconds);
         Instant start = Instant.now();
-
-
-        while ( hasNotEnded() && runnable.failed==null && runnable.secretKey == null) {
+
+        while (hasNotEnded() && runnable.failed == null && runnable.secretKey == null) {
             try {
-               Thread.sleep(500);
+                Thread.sleep(500);
             } catch (InterruptedException e) {
-               Thread.currentThread().interrupt();
-               break;
+                Thread.currentThread().interrupt();
+                break;
             }
             Instant finish = Instant.now();
             Duration duration = Duration.between(start, finish);
-            if (duration.compareTo(acceptedmax)>0) {
-                throw new LaunchException("Timed out after "+duration.getSeconds()+" seconds");
+            if (duration.compareTo(acceptedmax) > 0) {
+                throw new LaunchException("Timed out after " + duration.getSeconds() + " seconds");
             }
-            
+
         }
-        if (runnable.failed!=null) {
-            throw new LaunchException("Was not able to launch server on port:"+port, runnable.failed);
+        if (runnable.failed != null) {
+            throw new LaunchException("Was not able to launch server on port:" + port, runnable.failed);
         }
-        if (runnable.secretKey==null) {
-            throw new LaunchException("Server did not return secret!",null);
+        if (runnable.secretKey == null) {
+            throw new LaunchException("Server did not return secret!", null);
         }
     }
 
     private boolean hasNotEnded() {
-        if (process==null) {
+        if (process == null) {
             return true;// process has not been started
         }
         if (process.isAlive()) {
@@ -188,14 +193,16 @@ public void run() {
                         if (c == '\n') {
                             String line = lineStringBuffer.toString();
                             int secretPrefix = line.indexOf(CoreConstants.SERVER_SECRET_OUTPUT_PREFIX);
-                            if (secretPrefix!=-1) {
-                                secretKey=line.substring(secretPrefix+CoreConstants.SERVER_SECRET_OUTPUT_PREFIX.length());
+                            if (secretPrefix != -1) {
+                                secretKey = line.substring(secretPrefix + CoreConstants.SERVER_SECRET_OUTPUT_PREFIX.length());
                                 if (!showSecretKey) {
-                                    line = line.substring(0,secretPrefix)+CoreConstants.SERVER_SECRET_OUTPUT_PREFIX+"xxxxxxxxxxxxxxxxxxxxxxx";
+                                    line = line.substring(0, secretPrefix) + CoreConstants.SERVER_SECRET_OUTPUT_PREFIX + "xxxxxxxxxxxxxxxxxxxxxxx";
                                 }
                             }
                             if (outputHandler != null) {
-                                outputHandler.output(line);
+                                if (showServerOutput) {
+                                    outputHandler.output(line);
+                                }
                             }
                             lineStringBuffer = new StringBuffer();
                         } else {
@@ -209,7 +216,7 @@ public void run() {
                 int exitCode = process.waitFor();
                 if (outputHandler != null) {
                     ExitCode exitCodeObject = ServerExitCodes.from(exitCode);
-                    
+
                     outputHandler.output(">> ASP Server at port " + port + " exited with code:" + exitCodeObject.toMessage());
                 }
             } catch (Exception e) {
@@ -228,5 +235,4 @@ public void run() {
         }
     }
 
-
 }