Remove temporary files. Make sure first sentence in JavaDoc ends with…

… period.
restful-api-description-language · Dec 5, 2015 · 8fd3ed0 · 8fd3ed0
1 parent f1fd250
commit 8fd3ed0
Show file tree

Hide file tree

Showing 12 changed files with 167 additions and 97 deletions.
diff --git a/java/core/gradle.properties b/java/core/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright (c) EMC Corporation. All rights reserved.
 #
 
-version = 1.0.51
+version = 1.0.52
diff --git a/java/core/src/main/java/radl/common/xml/Xml.java b/java/core/src/main/java/radl/common/xml/Xml.java
@@ -5,6 +5,7 @@
 
 import java.io.File;
 import java.io.FileInputStream;
+import java.io.FileWriter;
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.ArrayList;
@@ -18,11 +19,14 @@
 import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
 import javax.xml.parsers.ParserConfigurationException;
+import javax.xml.transform.OutputKeys;
 import javax.xml.transform.Result;
 import javax.xml.transform.Source;
 import javax.xml.transform.Transformer;
 import javax.xml.transform.TransformerConfigurationException;
 import javax.xml.transform.TransformerFactory;
+import javax.xml.transform.dom.DOMSource;
+import javax.xml.transform.stream.StreamResult;
 
 import org.w3c.dom.Attr;
 import org.w3c.dom.Document;
@@ -36,16 +40,18 @@
 import com.google.common.escape.Escaper;
 import com.google.common.escape.Escapers;
 
+import radl.core.xml.RadlFileAssembler;
+
 
 /**
  * Utility methods for working with XML.
  */
 public final class Xml {
 
-  private static final String NAMESPACE_ATTRIBUTE_PREFIX = "xmlns";
-
   public static final String XML_PROLOG = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
 
+  private static final String NAMESPACE_ATTRIBUTE_PREFIX = "xmlns";
+
   /*
    * Avoid expensive DocumentBuilderFactory provider lookup by reusing a static instance. The
    * documentation says nothing about the thread safety of a DocumentBuilderFactory, but in practice
@@ -580,4 +586,36 @@ private boolean isMissingSchemaError(SAXParseException exception) {
     }
   }
 
+  public static Document parseWithIncludes(File xml) throws XmlException {
+    try {
+      DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
+      factory.setNamespaceAware(true);
+      factory.setXIncludeAware(true);
+      factory.setFeature(RadlFileAssembler.XINCLUDE_FIXUP_BASE_URI, false);
+      factory.setFeature(RadlFileAssembler.XINCLUDE_FIXUP_LANGUAGE, false);
+      DocumentBuilder builder = factory.newDocumentBuilder();
+      if (!builder.isXIncludeAware()) {
+        throw new RuntimeException("The document builder does not support XInclude: " + builder);
+      }
+      return builder.parse(xml);
+    } catch (Exception e) {
+      throw new XmlException(e);
+    }
+  }
+
+  public static void identityTransform(Document source, File destination) throws XmlException {
+    try {
+      FileWriter writer = new FileWriter(destination, false);
+      try {
+        Transformer transformer = TransformerFactory.newInstance().newTransformer();
+        transformer.setOutputProperty(OutputKeys.INDENT, "yes");
+        transformer.transform(new DOMSource(source), new StreamResult(writer));
+      } finally {
+        writer.close();
+      }
+    } catch (Exception e) {
+      throw new XmlException(e);
+    }
+  }
+
 }
diff --git a/java/core/src/main/java/radl/common/xml/XmlException.java b/java/core/src/main/java/radl/common/xml/XmlException.java
@@ -0,0 +1,18 @@
+/*
+ * Copyright © EMC Corporation. All rights reserved.
+ */
+package radl.common.xml;
+
+
+public class XmlException extends Exception {
+
+  public XmlException(Exception cause) {
+    super(cause);
+  }
+
+  @Override
+  public String getMessage() {
+    return getCause().getMessage();
+  }
+
+}
diff --git a/java/core/src/main/java/radl/core/documentation/DocumentationGenerator.java b/java/core/src/main/java/radl/core/documentation/DocumentationGenerator.java
@@ -8,6 +8,7 @@
 import java.io.InputStream;
 import java.io.OutputStream;
 import java.net.URL;
+
 import javax.xml.transform.Transformer;
 import javax.xml.transform.TransformerFactory;
 import javax.xml.transform.dom.DOMSource;
@@ -113,13 +114,17 @@ private boolean isRadlFile(File configuration) {
   private void generateClientDocumentation(File radlFile, File docDir, File configuration, String cssSource) {
     File serviceDir = getServiceDir(radlFile, docDir);
     File assembledRadl = RadlFileAssembler.assemble(radlFile, docDir);
-    Document radlDocument = Xml.parse(assembledRadl);
-    new StateDiagramGenerator().generateFrom(radlDocument, serviceDir, configuration);
-    File localCssFile = normalizeCSSFile(docDir, cssSource);
     try {
-      generateClientDocumentation(radlDocument, getIndexFile(serviceDir), localCssFile.toURI().toString());
+      Document radlDocument = Xml.parse(assembledRadl);
+      new StateDiagramGenerator().generateFrom(radlDocument, serviceDir, configuration);
+      File localCssFile = normalizeCSSFile(docDir, cssSource);
+      try {
+        generateClientDocumentation(radlDocument, getIndexFile(serviceDir), localCssFile.toURI().toString());
+      } finally {
+        IO.delete(localCssFile);
+      }
     } finally {
-      IO.delete(localCssFile);
+      IO.delete(assembledRadl);
     }
   }
 

diff --git a/java/core/src/main/java/radl/core/validation/RadlValidator.java b/java/core/src/main/java/radl/core/validation/RadlValidator.java
@@ -13,6 +13,7 @@
 import java.util.Map.Entry;
 import java.util.TreeMap;
 
+import radl.common.io.IO;
 import radl.core.Log;
 import radl.core.cli.Application;
 import radl.core.cli.Arguments;
@@ -74,19 +75,27 @@ void validate(Arguments arguments, Validator validator, Map<String, Collection<I
     while (arguments.hasNext()) {
       File radlFile = arguments.file();
       File assembledRadl = RadlFileAssembler.assemble(radlFile, reportDir);
-      Log.info("-> Validating " + radlFile.getName() + " using " + validator);
-      Collection<Issue> issuesByFile = new ArrayList<Issue>();
-      issues.put(assembledRadl.getName(), issuesByFile);
       try {
-        InputStream stream = new FileInputStream(assembledRadl);
-        try {
-          validator.validate(stream, issuesByFile);
-        } finally {
-          stream.close();
-        }
-      } catch (IOException e) {
-        issuesByFile.add(new Issue(Validator.class, Level.ERROR, 0, 0, e.toString()));
+        Log.info("-> Validating " + radlFile.getName() + " using " + validator);
+        validate(assembledRadl, validator, issues);
+      } finally {
+        IO.delete(assembledRadl);
+      }
+    }
+  }
+
+  private void validate(File radl, Validator validator, Map<String, Collection<Issue>> issues) {
+    Collection<Issue> issuesByFile = new ArrayList<Issue>();
+    issues.put(radl.getName(), issuesByFile);
+    try {
+      InputStream stream = new FileInputStream(radl);
+      try {
+        validator.validate(stream, issuesByFile);
+      } finally {
+        stream.close();
       }
+    } catch (IOException e) {
+      issuesByFile.add(new Issue(Validator.class, Level.ERROR, 0, 0, e.toString()));
     }
   }
 

diff --git a/java/core/src/main/java/radl/core/xml/RadlFileAssembler.java b/java/core/src/main/java/radl/core/xml/RadlFileAssembler.java
@@ -5,56 +5,35 @@
 package radl.core.xml;
 
 import java.io.File;
-import java.io.FileWriter;
-
-import javax.xml.parsers.DocumentBuilder;
-import javax.xml.parsers.DocumentBuilderFactory;
-import javax.xml.transform.OutputKeys;
-import javax.xml.transform.Transformer;
-import javax.xml.transform.TransformerFactory;
-import javax.xml.transform.dom.DOMSource;
-import javax.xml.transform.stream.StreamResult;
-
-import org.w3c.dom.Document;
 
+import radl.common.xml.Xml;
+import radl.common.xml.XmlException;
 import radl.core.Log;
 
+
 public final class RadlFileAssembler {
 
   public static final String XINCLUDE_FIXUP_BASE_URI = "http://apache.org/xml/features/xinclude/fixup-base-uris";
   public static final String XINCLUDE_FIXUP_LANGUAGE = "http://apache.org/xml/features/xinclude/fixup-language";
 
   private RadlFileAssembler() {
+    // Utility class
   }
 
   public static File assemble(File radlFile, File targetDirectory) {
-    File fullRadlFile = createFullRadlFile(radlFile, targetDirectory);
+    File result = createOutputFile(radlFile, targetDirectory);
     try {
-      // merge RADL files into a single file using transformation
-      DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
-      factory.setNamespaceAware(true);
-      factory.setXIncludeAware(true);
-      factory.setFeature(XINCLUDE_FIXUP_BASE_URI, false);
-      factory.setFeature(XINCLUDE_FIXUP_LANGUAGE, false);
-      DocumentBuilder docBuilder = factory.newDocumentBuilder();
-      if (!docBuilder.isXIncludeAware()) {
-        throw new RuntimeException("The document builder does not support XInclude: " + docBuilder);
-      }
-      Document doc = docBuilder.parse(radlFile);
-      Transformer transformer = TransformerFactory.newInstance().newTransformer();
-      transformer.setOutputProperty(OutputKeys.INDENT, "yes");
-      StreamResult result = new StreamResult(new FileWriter(fullRadlFile, false));
-      DOMSource source = new DOMSource(doc);
-      transformer.transform(source, result);
-    } catch (Exception e) {
+      // Merge potentially several RADL files into a single file using identity transformation and XInclude-aware parser
+      Xml.identityTransform(Xml.parseWithIncludes(radlFile), result);
+    } catch (XmlException e) {
       Log.error("Failed to assemble RADL file: " + e.getMessage());
       return radlFile;
     }
 
-    return fullRadlFile;
+    return result;
   }
 
-  private static File createFullRadlFile(File radlFile, File targetDirectory) {
+  private static File createOutputFile(File radlFile, File targetDirectory) {
     String name = radlFile.getName();
     File dir = targetDirectory;
     if (dir == null) {
@@ -64,4 +43,5 @@ private static File createFullRadlFile(File radlFile, File targetDirectory) {
     }
     return new File(dir, name + ".out");
   }
+
 }
diff --git a/java/core/src/main/java/radl/java/generation/spring/FromRadlCodeGenerator.java b/java/core/src/main/java/radl/java/generation/spring/FromRadlCodeGenerator.java
@@ -57,10 +57,11 @@ public abstract class FromRadlCodeGenerator implements CodeGenerator {
   static final String TRANSITITION_CHECK_NAME = "allows";
   static final String TRANSITITION_DENY_NAME = "deny";
   private static final String STANDARD_MEDIA_TYPE = "application/";
+  private static final String PUNCTATION = ".!?";
 
   private String fileHeader;
   private String packagePrefix;
-  
+
   protected String getPackagePrefix() {
     return packagePrefix;
   }
@@ -167,8 +168,14 @@ protected void addConstants(Constants constants, JavaCode code) {
         Constant constant = iterator.next();
         if (constant.getComments().length > 0) {
           code.add("  /**");
+          boolean firstLine = true;
           for (String comment : constant.getComments()) {
-            code.add("   * %s", comment);
+            if (comment.isEmpty()) {
+              continue;
+            }
+            String line = ensurePunctuation(comment, firstLine);
+            code.add("   * %s", line);
+            firstLine = false;
           }
           code.add("   */");
         }
@@ -187,6 +194,17 @@ protected void addConstantsHeading(String heading, Code code) {
     code.add("");
   }
 
+  private String ensurePunctuation(String text, boolean firstLine) {
+    return firstLine ? ensurePunctuation(text) : text;
+  }
+
+  private String ensurePunctuation(String text) {
+    if (PUNCTATION.indexOf(text.charAt(text.length() - 1)) < 0) {
+      return text + '.';
+    }
+    return text;
+  }
+
   protected String getMediaTypeConstant(Constants mediaTypeConstants, String mediaType) {
     return API_TYPE + '.' + getLocalMediaTypeConstant(mediaTypeConstants, mediaType);
   }