Cone Search library

.github/workflows/gradle.yml

@@ -25,6 +25,9 @@ jobs:
 
     - name: build and test cadc-sia
       run: cd cadc-sia && ../gradlew --info clean build javadoc checkstyleMain install
+
+    - name: build and test cadc-conesearch
+      run: cd cadc-conesearch && ../gradlew --info clean build javadoc checkstyleMain install
 
     - name: build and test cadc-datalink
       run: cd cadc-datalink && ../gradlew --info clean build javadoc checkstyleMain install

cadc-conesearch/README.md

@@ -0,0 +1,68 @@
+# cadc-conesearch (1.0.0)
+
+Library containing logic to help implementors support the [Simple Cone Search Working Draft (1.1)](https://www.ivoa.net/documents/ConeSearch/20200828/WD-ConeSearch-1.1-20200828.html).
+
+## Building it
+
+Gradle 6 or higher is required.  The DAL repository comes with a Gradle Wrapper.
+
+```shell
+/workdir/dal $ ./gradlew -i -b cadc-conesearch/build.gradle clean build test
+```
+
+## Installing it
+
+Gradle 6 or higher is required.  The DAL repository comes with a Gradle Wrapper.
+
+```shell
+/workdir/dal $ ./gradlew -i -b cadc-conesearch/build.gradle clean build test install
+```
+
+## Implementing it
+
+Your `build.gradle` file should include it as a dependency from Maven Central:
+
+`build.gradle`:
+```groovy
+repositories {
+    mavenCentral()
+    mavenLocal()
+}
+
+dependencies {
+    implementation 'org.opencadc:cadc-conesearch:1.0.0'
+}
+```
+
+`${HOME}/config/cadc-conesearch.properties`:
+```properties
+tapURI = ivo://myhost.com/catalog_tap_service   # Or an absolute URL e.g. https://myhost.com/mytap
+positionColumnName = my_spatial_indexed_column  # Used to compare to the Cone's Center position.  Can also be a dynamic spatial object e.g. POINT('ICRS', RA_Source, DEC_Source)
+lowVerbositySelectList = obs_id, ra, dec        # Columns for VERB=1
+midVerbositySelectList = obs_id, ra, dec, s_region, frequency, bandwidth  # Columns for VERB=2
+highVerbositySelectList = *  # Columns for VERB=3
+```
+
+Capture the Cone Search parameters and translate to ADQL to be sent to a TAP service.
+
+```java
+final ConeSearchConfig coneSearchConfig = new ConeSearchConfig();  // Ensure the cadc-conesearch.properties exists.
+final TAPQueryGenerator tapQueryGenerator = new TAPQueryGenerator("mycatalog", coneSearchConfig.getLowVerbositySelectList(), 
+                                                                  coneSearchConfig.getMidVerbositySelectList(), 
+                                                                  coneSearchConfig.getHighVerbositySelectList());
+// Create TAP parameters
+final Map<String, Object> parameters =
+        tapQueryGenerator.getParameterMap(coneSearchConfig.getPositionColumnName(),
+        parameterExtractor.getParameters(job.getParameterList()));
+
+// Issue a Synchronous POST request to a TAP service.
+final URL tapSyncURL = new URL(coneSearchConfig.getTapBaseURL().toExternalForm() + "/sync");
+
+// POST ADQL query to TAP but do not follow redirect to execute it.
+final HttpPost post = new HttpPost(tapSyncURL, parameters, false);
+post.run();
+
+// Do something with the data.
+final URL redirectURL = post.getRedirectURL();  // In the case of a redirect
+final InputStream inputStream = post.getInputStream();  // Read the data
+```

cadc-conesearch/build.gradle

@@ -0,0 +1,30 @@
+plugins {
+    id 'java-library'
+    id 'maven'
+    id 'maven-publish'
+    id 'checkstyle'
+}
+
+repositories {
+    mavenCentral()
+    mavenLocal()
+}
+
+sourceCompatibility = 1.8
+group = 'org.opencadc'
+version = '1.0.0'
+
+description = 'OpenCADC Simple Cone Search Java API'
+def git_url = 'https://github.com/opencadc/dal.git'
+
+dependencies {
+    implementation 'org.opencadc:cadc-dali:[1.2.4,2.0)'
+    implementation 'org.opencadc:cadc-rest:[1.3.12,2.0)'
+    implementation 'org.opencadc:cadc-util:[1.6.4,2.0)'
+    implementation 'org.opencadc:cadc-vosi:[1.4.4,2.0)'
+
+    // Use JUnit test framework.
+    testImplementation 'junit:junit:4.13'
+}
+
+apply from: '../opencadc.gradle'

cadc-conesearch/src/main/java/org/opencadc/conesearch/NumberParameterValidator.java

@@ -0,0 +1,127 @@
+/*
+ ************************************************************************
+ *******************  CANADIAN ASTRONOMY DATA CENTRE  *******************
+ **************  CENTRE CANADIEN DE DONNÉES ASTRONOMIQUES  **************
+ *
+ *  (c) 2022.                            (c) 2022.
+ *  Government of Canada                 Gouvernement du Canada
+ *  National Research Council            Conseil national de recherches
+ *  Ottawa, Canada, K1A 0R6              Ottawa, Canada, K1A 0R6
+ *  All rights reserved                  Tous droits réservés
+ *
+ *  NRC disclaims any warranties,        Le CNRC dénie toute garantie
+ *  expressed, implied, or               énoncée, implicite ou légale,
+ *  statutory, of any kind with          de quelque nature que ce
+ *  respect to the software,             soit, concernant le logiciel,
+ *  including without limitation         y compris sans restriction
+ *  any warranty of merchantability      toute garantie de valeur
+ *  or fitness for a particular          marchande ou de pertinence
+ *  purpose. NRC shall not be            pour un usage particulier.
+ *  liable in any event for any          Le CNRC ne pourra en aucun cas
+ *  damages, whether direct or           être tenu responsable de tout
+ *  indirect, special or general,        dommage, direct ou indirect,
+ *  consequential or incidental,         particulier ou général,
+ *  arising from the use of the          accessoire ou fortuit, résultant
+ *  software.  Neither the name          de l'utilisation du logiciel. Ni
+ *  of the National Research             le nom du Conseil National de
+ *  Council of Canada nor the            Recherches du Canada ni les noms
+ *  names of its contributors may        de ses  participants ne peuvent
+ *  be used to endorse or promote        être utilisés pour approuver ou
+ *  products derived from this           promouvoir les produits dérivés
+ *  software without specific prior      de ce logiciel sans autorisation
+ *  written permission.                  préalable et particulière
+ *                                       par écrit.
+ *
+ *  This file is part of the             Ce fichier fait partie du projet
+ *  OpenCADC project.                    OpenCADC.
+ *
+ *  OpenCADC is free software:           OpenCADC est un logiciel libre ;
+ *  you can redistribute it and/or       vous pouvez le redistribuer ou le
+ *  modify it under the terms of         modifier suivant les termes de
+ *  the GNU Affero General Public        la “GNU Affero General Public
+ *  License as published by the          License” telle que publiée
+ *  Free Software Foundation,            par la Free Software Foundation
+ *  either version 3 of the              : soit la version 3 de cette
+ *  License, or (at your option)         licence, soit (à votre gré)
+ *  any later version.                   toute version ultérieure.
+ *
+ *  OpenCADC is distributed in the       OpenCADC est distribué
+ *  hope that it will be useful,         dans l’espoir qu’il vous
+ *  but WITHOUT ANY WARRANTY;            sera utile, mais SANS AUCUNE
+ *  without even the implied             GARANTIE : sans même la garantie
+ *  warranty of MERCHANTABILITY          implicite de COMMERCIALISABILITÉ
+ *  or FITNESS FOR A PARTICULAR          ni d’ADÉQUATION À UN OBJECTIF
+ *  PURPOSE.  See the GNU Affero         PARTICULIER. Consultez la Licence
+ *  General Public License for           Générale Publique GNU Affero
+ *  more details.                        pour plus de détails.
+ *
+ *  You should have received             Vous devriez avoir reçu une
+ *  a copy of the GNU Affero             copie de la Licence Générale
+ *  General Public License along         Publique GNU Affero avec
+ *  with OpenCADC.  If not, see          OpenCADC ; si ce n’est
+ *  <http://www.gnu.org/licenses/>.      pas le cas, consultez :
+ *                                       <http://www.gnu.org/licenses/>.
+ *
+ *
+ ************************************************************************
+ */
+
+package org.opencadc.conesearch;
+
+import ca.nrc.cadc.util.StringUtil;
+
+public class NumberParameterValidator {
+    private final boolean capValue;
+    private final int minValue;
+    private final int maxValue;
+    private final int defaultValue;
+
+
+    /**
+     * Constructor.
+     *
+     * @param capValue  Set to true to cap the upper value to the max
+     */
+    public NumberParameterValidator(final boolean capValue, final int minValue, final int maxValue,
+                                    final int defaultValue) {
+
+        if (minValue > maxValue) {
+            throw new IllegalArgumentException("Min value must be less than or equal to Max value.");
+        } else if (defaultValue > maxValue || defaultValue < minValue) {
+            throw new IllegalArgumentException("Default value does not fall between specified min and max values ("
+                                               + minValue + " and " + maxValue + ").");
+        }
+
+        this.capValue = capValue;
+        this.minValue = minValue;
+        this.maxValue = maxValue;
+        this.defaultValue = defaultValue;
+    }
+
+    public int validate(final String parameterNumberValue) {
+        final int integerValue;
+        if (StringUtil.hasText(parameterNumberValue)) {
+            try {
+                final int parsedValue = Integer.parseInt(parameterNumberValue);
+                if (parsedValue > maxValue && capValue) {
+                    integerValue = maxValue;
+                } else if (parsedValue < minValue && capValue) {
+                    integerValue = minValue;
+                } else {
+                    integerValue = parsedValue;
+                }
+            } catch (NumberFormatException numberFormatException) {
+                throw new IllegalArgumentException("Cannot parse number value (not a valid number)");
+            }
+
+            if (integerValue < minValue || integerValue > maxValue) {
+                throw new IllegalArgumentException(
+                        "Input MUST be a value between " + minValue + " and " + maxValue + ".");
+            }
+        } else {
+            integerValue = defaultValue;
+        }
+
+        return integerValue;
+    }
+}

cadc-conesearch/src/main/java/org/opencadc/conesearch/ParameterNames.java

@@ -0,0 +1,84 @@
+/*
+ ************************************************************************
+ *******************  CANADIAN ASTRONOMY DATA CENTRE  *******************
+ **************  CENTRE CANADIEN DE DONNÉES ASTRONOMIQUES  **************
+ *
+ *  (c) 2022.                            (c) 2022.
+ *  Government of Canada                 Gouvernement du Canada
+ *  National Research Council            Conseil national de recherches
+ *  Ottawa, Canada, K1A 0R6              Ottawa, Canada, K1A 0R6
+ *  All rights reserved                  Tous droits réservés
+ *
+ *  NRC disclaims any warranties,        Le CNRC dénie toute garantie
+ *  expressed, implied, or               énoncée, implicite ou légale,
+ *  statutory, of any kind with          de quelque nature que ce
+ *  respect to the software,             soit, concernant le logiciel,
+ *  including without limitation         y compris sans restriction
+ *  any warranty of merchantability      toute garantie de valeur
+ *  or fitness for a particular          marchande ou de pertinence
+ *  purpose. NRC shall not be            pour un usage particulier.
+ *  liable in any event for any          Le CNRC ne pourra en aucun cas
+ *  damages, whether direct or           être tenu responsable de tout
+ *  indirect, special or general,        dommage, direct ou indirect,
+ *  consequential or incidental,         particulier ou général,
+ *  arising from the use of the          accessoire ou fortuit, résultant
+ *  software.  Neither the name          de l'utilisation du logiciel. Ni
+ *  of the National Research             le nom du Conseil National de
+ *  Council of Canada nor the            Recherches du Canada ni les noms
+ *  names of its contributors may        de ses  participants ne peuvent
+ *  be used to endorse or promote        être utilisés pour approuver ou
+ *  products derived from this           promouvoir les produits dérivés
+ *  software without specific prior      de ce logiciel sans autorisation
+ *  written permission.                  préalable et particulière
+ *                                       par écrit.
+ *
+ *  This file is part of the             Ce fichier fait partie du projet
+ *  OpenCADC project.                    OpenCADC.
+ *
+ *  OpenCADC is free software:           OpenCADC est un logiciel libre ;
+ *  you can redistribute it and/or       vous pouvez le redistribuer ou le
+ *  modify it under the terms of         modifier suivant les termes de
+ *  the GNU Affero General Public        la “GNU Affero General Public
+ *  License as published by the          License” telle que publiée
+ *  Free Software Foundation,            par la Free Software Foundation
+ *  either version 3 of the              : soit la version 3 de cette
+ *  License, or (at your option)         licence, soit (à votre gré)
+ *  any later version.                   toute version ultérieure.
+ *
+ *  OpenCADC is distributed in the       OpenCADC est distribué
+ *  hope that it will be useful,         dans l’espoir qu’il vous
+ *  but WITHOUT ANY WARRANTY;            sera utile, mais SANS AUCUNE
+ *  without even the implied             GARANTIE : sans même la garantie
+ *  warranty of MERCHANTABILITY          implicite de COMMERCIALISABILITÉ
+ *  or FITNESS FOR A PARTICULAR          ni d’ADÉQUATION À UN OBJECTIF
+ *  PURPOSE.  See the GNU Affero         PARTICULIER. Consultez la Licence
+ *  General Public License for           Générale Publique GNU Affero
+ *  more details.                        pour plus de détails.
+ *
+ *  You should have received             Vous devriez avoir reçu une
+ *  a copy of the GNU Affero             copie de la Licence Générale
+ *  General Public License along         Publique GNU Affero avec
+ *  with OpenCADC.  If not, see          OpenCADC ; si ce n’est
+ *  <http://www.gnu.org/licenses/>.      pas le cas, consultez :
+ *                                       <http://www.gnu.org/licenses/>.
+ *
+ *
+ ************************************************************************
+ */
+
+package org.opencadc.conesearch;
+
+public enum ParameterNames {
+    DEC(true), RA(true), SR(true),
+    MAXREC(false), RESPONSEFORMAT(false), TIME(false), VERB(false);
+
+    private final boolean required;
+
+    ParameterNames(final boolean required) {
+        this.required = required;
+    }
+
+    public boolean isRequired() {
+        return required;
+    }
+}