[ZEPPELIN-699] Update Notebook REST API documentation

docs/rest-api/rest-notebook.md

@@ -450,12 +450,12 @@ If you work with Apache Zeppelin and find a need for an additional REST API, ple
   </table>
 
 <br/>
-### Run a paragraph
+### Run a paragraph asynchronously
   <table class="table-configuration">
     <col width="200">
     <tr>
       <td>Description</td>
-      <td>This ```POST``` method runs the paragraph by given notebook and paragraph id.
+      <td>This ```POST``` method runs the paragraph asynchronously by given notebook and paragraph id. This API always return SUCCESS even if the execution of the paragraph fails later because the API is asynchronous
       </td>
     </tr>
     <tr>
@@ -487,6 +487,56 @@ If you work with Apache Zeppelin and find a need for an additional REST API, ple
     </tr>
   </table>
 
+<br/>
+### Run a paragraph synchronously
+  <table class="table-configuration">
+    <col width="200">
+    <tr>
+      <td>Description</td>
+      <td> This ```POST``` method runs the paragraph synchronously by given notebook and paragraph id. This API can return SUCCESS or ERROR depending on the outcome of the paragraph execution
+      </td>
+    </tr>
+    <tr>
+      <td>URL</td>
+      <td>```http://[zeppelin-server]:[zeppelin-port]/api/notebook/job/[notebookId]/[paragraphId]```</td>
+    </tr>
+    <tr>
+      <td>Success code</td>
+      <td>200</td>
+    </tr>
+    <tr>
+      <td> Fail code</td>
+      <td> 500 </td>
+    </tr>
+    <tr>
+      <td> sample JSON input (optional, only needed when if you want to update dynamic form's value) </td>
+      <td><pre>
+{
+  "name": "name of new notebook",
+  "params": {
+    "formLabel1": "value1",
+    "formLabel2": "value2"
+  }
+}</pre></td>
+    </tr>
+    <tr>
+      <td> sample JSON response </td>
+      <td><pre>{"status": "OK"}</pre></td>
+    </tr>    
+    <tr>
+      <td> sample JSON error </td>
+      <td><pre>
+{
+   "status": "INTERNAL\_SERVER\_ERROR",
+   "body": {
+       "code": "ERROR",
+       "type": "TEXT",
+       "msg": "bash: -c: line 0: unexpected EOF while looking for matching ``'\nbash: -c: line 1: syntax error: unexpected end of file\nExitValue: 2"
+   }
+}</pre></td>
+    </tr>
+  </table>
+
 <br/>
 ### Stop a paragraph
   <table class="table-configuration">
@@ -922,4 +972,3 @@ If you work with Apache Zeppelin and find a need for an additional REST API, ple
     </tr>
     </tr>
   </table>
-  

zeppelin-server/src/main/java/org/apache/zeppelin/rest/NotebookRestApi.java

@@ -567,7 +567,7 @@ public class NotebookRestApi {
   }
 
   /**
-   * Run paragraph job REST API
+   * Run asynchronously paragraph job REST API
    *
    * @param message - JSON with params if user wants to update dynamic form's value
    *                null, empty string, empty json if user doesn't want to update
@@ -580,7 +580,7 @@ public class NotebookRestApi {
   public Response runParagraph(@PathParam("notebookId") String notebookId,
       @PathParam("paragraphId") String paragraphId, String message)
       throws IOException, IllegalArgumentException {
-    LOG.info("run paragraph job {} {} {}", notebookId, paragraphId, message);
+    LOG.info("run paragraph job asynchronously {} {} {}", notebookId, paragraphId, message);
 
     Note note = notebook.getNote(notebookId);
     if (note == null) {
@@ -593,17 +593,7 @@ public class NotebookRestApi {
     }
 
     // handle params if presented
-    if (!StringUtils.isEmpty(message)) {
-      RunParagraphWithParametersRequest request =
-          gson.fromJson(message, RunParagraphWithParametersRequest.class);
-      Map<String, Object> paramsForUpdating = request.getParams();
-      if (paramsForUpdating != null) {
-        paragraph.settings.getParams().putAll(paramsForUpdating);
-        AuthenticationInfo subject = new AuthenticationInfo(SecurityUtils.getPrincipal());
-        note.setLastReplName(paragraph.getId());
-        note.persist(subject);
-      }
-    }
+    handleParagraphParams(message, note, paragraph);
 
     note.run(paragraph.getId());
     return new JsonResponse<>(Status.OK).build();
@@ -642,12 +632,8 @@ public class NotebookRestApi {
     // handle params if presented
     handleParagraphParams(message, note, paragraph);
 
-    if (paragraph.getNoteReplLoader() == null) {
-      paragraph.setNoteReplLoader(note.getNoteReplLoader());
-    }
-
     if (paragraph.getListener() == null) {
-      paragraph.setListener(note.getJobListenerFactory().getParagraphJobListener(note));
+      note.initializeJobListenerForParagraph(paragraph);
     }
 
     paragraph.run();
@@ -857,12 +843,14 @@ public class NotebookRestApi {
       throws IOException {
     // handle params if presented
     if (!StringUtils.isEmpty(message)) {
-      RunParagraphWithParametersRequest request = gson.fromJson(message,
-              RunParagraphWithParametersRequest.class);
+      RunParagraphWithParametersRequest request =
+              gson.fromJson(message, RunParagraphWithParametersRequest.class);
       Map<String, Object> paramsForUpdating = request.getParams();
       if (paramsForUpdating != null) {
         paragraph.settings.getParams().putAll(paramsForUpdating);
-        note.persist();
+        AuthenticationInfo subject = new AuthenticationInfo(SecurityUtils.getPrincipal());
+        note.setLastReplName(paragraph.getId());
+        note.persist(subject);
       }
     }
   }

zeppelin-zengine/src/main/java/org/apache/zeppelin/notebook/Note.java

@@ -17,6 +17,8 @@
 
 package org.apache.zeppelin.notebook;
 
+import static java.lang.String.format;
+
 import java.io.IOException;
 import java.io.Serializable;
 import java.util.HashMap;
@@ -172,6 +174,28 @@ public class Note implements Serializable, ParagraphJobListener {
     }
   }
 
+  public void initializeJobListenerForParagraph(Paragraph paragraph) {
+    final Note paragraphNote = paragraph.getNote();
+    if (paragraphNote.getId().equals(this.getId())) {
+      throw new IllegalArgumentException(format("The paragraph %s from note %s " +
+              "does not belong to note %s", paragraph.getId(), paragraphNote.getId(),
+              this.getId()));
+    }
+
+    boolean foundParagraph = false;
+    for (Paragraph ownParagraph : paragraphs) {
+      if (paragraph.getId().equals(ownParagraph.getId())) {
+        paragraph.setListener(this.jobListenerFactory.getParagraphJobListener(this));
+        foundParagraph = true;
+      }
+    }
+
+    if (!foundParagraph) {
+      throw new IllegalArgumentException(format("Cannot find paragraph %s " +
+                      "from note %s", paragraph.getId(), paragraphNote.getId()));
+    }
+  }
+
   void setJobListenerFactory(JobListenerFactory jobListenerFactory) {
     this.jobListenerFactory = jobListenerFactory;
   }
@@ -484,7 +508,7 @@ public class Note implements Serializable, ParagraphJobListener {
         logger.debug("New paragraph: {}", pText);
         p.setEffectiveText(pText);
       } else {
-        String intpExceptionMsg = String.format("%s",
+        String intpExceptionMsg = format("%s",
           p.getJobName()
           + "'s Interpreter "
           + requiredReplName + " not found"