Merge pull request #725 from echicoine-esac/709_JavaDoc_CqlOptions

#709: Added JavaDoc entries to CqlTranslatorOptions

Src/java/cql-to-elm/OVERVIEW.md

@@ -108,3 +108,30 @@ The CQL-to-ELM Translator is designed as a component that can be incorporated in
 |debug||A combination option that is equivalent to specifying all of annotations, locators, and result-types|
 |validate-units||Indicates that the translator should validate UCUM units in quantity literals|
 |stdout||Indicates that the translator should write output to the console instead of a file|
+
+## CqlTranslatorOptions
+
+The class CqlTranslatorOptions provides use of cql-options files in directories with the translator.  A JSON schema file that documents the class' structure can be found
+at clinical_quality_language\Src\java\cql-to-elm\src\test\resources\org\cqframework\cql\cql2elm\json. 
+
+An instance of the class with default options can be accessed through defaultOptions(), and returns the following translator options:
+     - EnableAnnotations
+     - EnableLocators
+     - DisableListDemotion
+     - DisableListPromotion
+     - ErrorSeverity.Info
+     - SignatureLevel.None
+     - Format.XML
+
+Several constructors exist allowing user control of specified options, such as:
+     - CqlTranslatorOptions(CqlTranslator.Options... options) 
+     - CqlTranslatorOptions(CqlTranslatorException.ErrorSeverity errorLevel, LibraryBuilder.SignatureLevel signatureLevel, CqlTranslator.Options... options)
+     - CqlTranslatorOptions(CqlTranslator.Format format, boolean dateRangeOptimizations,
+                                boolean annotations, boolean locators, boolean resultTypes, boolean verifyOnly,
+                                boolean detailedErrors, CqlTranslatorException.ErrorSeverity errorLevel,
+                                boolean disableListTraversal, boolean disableListDemotion, boolean disableListPromotion,
+                                boolean enableIntervalDemotion, boolean enableIntervalPromotion,
+                                boolean disableMethodInvocation, boolean requireFromKeyword, boolean validateUnits,
+                                LibraryBuilder.SignatureLevel signatureLevel, String compatibilityLevel)
+
+toString() has been overridden to provide an easy-to-read breakdown of existing options within an instance of this class.

Src/java/cql-to-elm/build.gradle

@@ -12,6 +12,8 @@ dependencies {
     compile group: 'com.fasterxml.jackson.module', name: 'jackson-module-jaxb-annotations', version: '2.10.1'
     compile group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.10.1'
     compile group: 'org.glassfish', name: 'javax.json', version: '1.1.4'
+    testCompile group: 'com.github.reinert', name: 'jjschema', version: '1.16'
+
     runtime project(':quick')
     runtime project(':qdm')
 }

Src/java/cql-to-elm/src/main/java/org/cqframework/cql/cql2elm/CqlTranslatorOptions.java

@@ -1,5 +1,6 @@
 package org.cqframework.cql.cql2elm;
 
+
 import java.util.ArrayList;
 import java.util.EnumSet;
 import java.util.List;
@@ -46,16 +47,50 @@ public static CqlTranslatorOptions defaultOptions() {
     public CqlTranslatorOptions() {
     }
 
+    /**
+     * Constructor with arbitrary number of options utilizing default ErrorSeverity (Info) and SignatureLevel (None)
+     * @param options
+     */
     public CqlTranslatorOptions(CqlTranslator.Options... options) {
         this(CqlTranslatorException.ErrorSeverity.Info, LibraryBuilder.SignatureLevel.None, options);
     }
 
+    /**
+     * Constructor with defined ErrorSeverity, SignatureLevel, and arbitrary number of options.
+     *
+     * @param errorLevel
+     * @param signatureLevel
+     * @param options
+     */
     public CqlTranslatorOptions(CqlTranslatorException.ErrorSeverity errorLevel, LibraryBuilder.SignatureLevel signatureLevel, CqlTranslator.Options... options) {
         this.setOptions(options);
         this.errorLevel = errorLevel;
         this.signatureLevel = signatureLevel;
     }
 
+    /**
+     * Constructor using defined Format, SignatureLevel, and Compatibility Level, boolean set to true denotes addition of predefined option
+     *
+     *
+     * @param format CqlTranslator.Format
+     * @param dateRangeOptimizations boolean
+     * @param annotations boolean
+     * @param locators boolean
+     * @param resultTypes boolean
+     * @param verifyOnly boolean
+     * @param detailedErrors boolean
+     * @param errorLevel boolean
+     * @param disableListTraversal boolean
+     * @param disableListDemotion boolean
+     * @param disableListPromotion boolean
+     * @param enableIntervalDemotion boolean
+     * @param enableIntervalPromotion boolean
+     * @param disableMethodInvocation boolean
+     * @param requireFromKeyword boolean
+     * @param validateUnits boolean
+     * @param signatureLevel LibraryBuilder.SignatureLevel
+     * @param compatibilityLevel String
+     */
     public CqlTranslatorOptions(CqlTranslator.Format format, boolean dateRangeOptimizations,
                                 boolean annotations, boolean locators, boolean resultTypes, boolean verifyOnly,
                                 boolean detailedErrors, CqlTranslatorException.ErrorSeverity errorLevel,
@@ -113,10 +148,19 @@ public CqlTranslatorOptions(CqlTranslator.Format format, boolean dateRangeOptimi
         }
     }
 
+    /**
+     * Returns instance of CqlTranslatorOptions options
+     * @return
+     */
+
     public EnumSet<CqlTranslator.Options> getOptions() {
         return this.options;
     }
 
+    /**
+     * Set arbitrary number of options
+     * @param options
+     */
     public void setOptions(CqlTranslator.Options... options) {
         if (options != null) {
             for (CqlTranslator.Options option : options) {
@@ -125,106 +169,212 @@ public void setOptions(CqlTranslator.Options... options) {
         }
     }
 
+    /**
+     * Return this instance of CqlTranslatorOptions using new collection of arbitrary number of options
+     * @param options
+     * @return
+     */
     public CqlTranslatorOptions withOptions(CqlTranslator.Options... options) {
         setOptions(options);
         return this;
     }
 
+    /**
+     * Returns instance of CqlTranslatorOptions formats
+     *
+     * @return
+     */
     public List<CqlTranslator.Format> getFormats() {
         return this.formats;
     }
 
+    /**
+     * Return this instance of CqlTranslatorOptions with addition of newly assigned format
+     * @param format
+     * @return
+     */
     public CqlTranslatorOptions withFormat(CqlTranslator.Format format) {
         formats.add(format);
         return this;
     }
 
+    /**
+     * Return instance of CqlTranslatorOptions compatibilityLevel
+     * @return
+     */
     public String getCompatibilityLevel() {
         return this.compatibilityLevel;
     }
 
+    /**
+     * Set new compatibilityLevel
+     * @param compatibilityLevel
+     */
     public void setCompatibilityLevel(String compatibilityLevel) {
         this.compatibilityLevel = compatibilityLevel;
     }
 
+    /**
+     *  Return this instance of CqlTranslatorOptions with addition of newly assigned compatibilityLevel
+     * @param compatibilityLevel
+     * @return
+     */
     public CqlTranslatorOptions withCompatibilityLevel(String compatibilityLevel) {
         setCompatibilityLevel(compatibilityLevel);
         return this;
     }
 
+    /**
+     * Return instance of CqlTranslatorOptions verifyOnly boolean
+     * @return
+     */
     public boolean getVerifyOnly() {
         return this.verifyOnly;
     }
 
+    /**
+     * Set new verifyOnly boolean
+     * @param verifyOnly
+     */
     public void setVerifyOnly(boolean verifyOnly) {
         this.verifyOnly = verifyOnly;
     }
 
+    /**
+     * Return this instance of CqlTranslatorOptions with addition of newly assigned verifyOnly boolean
+     * @param verifyOnly
+     * @return
+     */
     public CqlTranslatorOptions withVerifyOnly(boolean verifyOnly) {
         setVerifyOnly(verifyOnly);
         return this;
     }
 
+    /**
+     * Return instance of CqlTranslatorOptions validateUnits boolean
+     * @return
+     */
     public boolean getValidateUnits() {
         return this.validateUnits;
     }
 
+    /**
+     * Set new validateUnits boolean
+     * @param validateUnits
+     */
     public void setValidateUnits(boolean validateUnits) {
         this.validateUnits = validateUnits;
     }
 
+    /**
+     * Return this instance of CqlTranslatorOptions with addition of newly assigned validateUnits boolean
+     * @param validateUnits
+     * @return
+     */
     public CqlTranslatorOptions withValidateUnits(boolean validateUnits) {
         setValidateUnits(validateUnits);
         return this;
     }
 
+    /**
+     * Return instance of CqlTranslatorOptions errorLevel (CqlTranslatorException.ErrorSeverity)
+     * @return
+     */
     public CqlTranslatorException.ErrorSeverity getErrorLevel() {
         return this.errorLevel;
     }
 
+    /**
+     * Set new errorLevel (CqlTranslatorException.ErrorSeverity)
+     * @param errorLevel
+     */
     public void setErrorLevel(CqlTranslatorException.ErrorSeverity errorLevel) {
         this.errorLevel = errorLevel;
     }
 
+    /**
+     * Return this instance of CqlTranslatorOptions with addition of newly assigned errorLevel (CqlTranslatorException.ErrorSeverity)
+     * @param errorLevel
+     * @return
+     */
     public CqlTranslatorOptions withErrorLevel(CqlTranslatorException.ErrorSeverity errorLevel) {
         setErrorLevel(errorLevel);
         return this;
     }
 
+    /**
+     * Return instance of CqlTranslatorOptions signatureLevel (LibraryBuilder.SignatureLevel)
+     * @return
+     */
     public LibraryBuilder.SignatureLevel getSignatureLevel() {
         return this.signatureLevel;
     }
 
+    /**
+     * Set new signatureLevel (LibraryBuilder.SignatureLevel)
+     * @param signatureLevel
+     */
     public void setSignatureLevel(LibraryBuilder.SignatureLevel signatureLevel) {
         this.signatureLevel = signatureLevel;
     }
 
+    /**
+     * Return this instance of CqlTranslatorOptions with addition of newly assigned signatureLevel (LibraryBuilder.SignatureLevel)
+     * @param signatureLevel
+     * @return
+     */
     public CqlTranslatorOptions withSignatureLevel(LibraryBuilder.SignatureLevel signatureLevel) {
         setSignatureLevel(signatureLevel);
         return this;
     }
 
+    /**
+     * Return instance of CqlTranslatorOptions cllapseDataRequirements boolean
+     * @return
+     */
     public boolean getCollapseDataRequirements() {
         return this.collapseDataRequirements;
     }
 
+    /**
+     * Set new collapseDataRequirements boolean
+     * @param collapseDataRequirements
+     */
     public void setCollapseDataRequirements(boolean collapseDataRequirements) {
         this.collapseDataRequirements = collapseDataRequirements;
     }
 
+    /**
+     * Return this instance of CqlTranslatorOptions with addition of newly assigned collapseDataRequirements boolean
+     * @param collapseDataRequirements
+     * @return
+     */
     public CqlTranslatorOptions withCollapseDataRequirements(boolean collapseDataRequirements) {
         setCollapseDataRequirements(collapseDataRequirements);
         return this;
     }
 
+    /**
+     * Return instance of CqlTranslatorOptions analayzedDataRequirements boolean
+     * @return
+     */
     public boolean getAnalyzeDataRequirements() {
         return this.analyzeDataRequirements;
     }
 
+    /**
+     * Set new analyzeDataRequirements boolean
+     * @param analyzeDataRequirements
+     */
     public void setAnalyzeDataRequirements(boolean analyzeDataRequirements) {
         this.analyzeDataRequirements = analyzeDataRequirements;
     }
 
+    /**git 
+     * Return this instance of CqlTranslatorOptions with addition of newly assigned analyzedDataRequirements boolean
+     * @param analyzeDataRequirements
+     * @return
+     */
     public CqlTranslatorOptions withAnalyzeDataRequirements(boolean analyzeDataRequirements) {
         setAnalyzeDataRequirements(analyzeDataRequirements);
         return this;

Src/java/cql-to-elm/src/test/java/org/cqframework/cql/cql2elm/json/CqlTranslatorOptionsToJsonSchema.java

@@ -0,0 +1,45 @@
+package org.cqframework.cql.cql2elm.json;
+
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.github.reinert.jjschema.v1.JsonSchemaFactory;
+import com.github.reinert.jjschema.v1.JsonSchemaV4Factory;
+import org.testng.Assert;
+import org.testng.annotations.Test;
+
+import java.io.BufferedWriter;
+import java.io.File;
+import java.io.FileWriter;
+
+public class CqlTranslatorOptionsToJsonSchema {
+    private static final String separator = System.getProperty("file.separator");
+    private static final String JSON_LOC = "src" + separator + "test" + separator +
+            "resources" + separator + "org" + separator + "cqframework" + separator + "cql" + separator + "cql2elm" +
+            separator + "json" + separator + "CqlTranslatorOptions.json";
+
+    @Test
+    public void BuildJsonSchemaFromCqlTranslatorOptions() {
+        //delete file if exists:
+        try {
+            File jsonFile = new File(JSON_LOC);
+            if (jsonFile.exists()) {
+                jsonFile.delete();
+            }
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+        //verify output is valid:
+        try {
+            JsonSchemaFactory schemaFactory = new JsonSchemaV4Factory();
+            schemaFactory.setAutoPutDollarSchema(true);
+            BufferedWriter writer = new BufferedWriter(new FileWriter(JSON_LOC));
+            JsonNode jNode = schemaFactory.createSchema(org.cqframework.cql.cql2elm.CqlTranslatorOptions.class);
+            writer.write(jNode.toPrettyString());
+            writer.close();
+        } catch (Exception e) {
+            e.printStackTrace();
+            Assert.fail();
+        }
+    }
+
+}