ATLAS-5218: Add command-line utility to run Gremlin queries

distro/pom.xml

@@ -277,6 +277,7 @@ atlas.graph.storage.hbase.regions-per-server=1
                                         <descriptor>src/main/assemblies/classification-updater.xml</descriptor>
                                         <descriptor>src/main/assemblies/notification-analyzer.xml</descriptor>
                                         <descriptor>src/main/assemblies/atlas-trino-extractor.xml</descriptor>
+                                        <descriptor>src/main/assemblies/atlas-gremlin-cli.xml</descriptor>
                                     </descriptors>
                                     <finalName>apache-atlas-${project.version}</finalName>
                                     <tarLongFileMode>gnu</tarLongFileMode>

distro/src/main/assemblies/atlas-gremlin-cli.xml

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+<assembly xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
+          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
+    <formats>
+        <format>tar.gz</format>
+    </formats>
+    <id>atlas-gremlin-cli</id>
+    <baseDirectory>atlas-gremlin-cli</baseDirectory>
+    <fileSets>
+        <fileSet>
+            <directory>../tools/atlas-gremlin-cli</directory>
+            <outputDirectory>.</outputDirectory>
+            <includes>
+                <include>README*</include>
+            </includes>
+        </fileSet>
+        <fileSet>
+            <directory>../tools/atlas-gremlin-cli/scripts</directory>
+            <outputDirectory>.</outputDirectory>
+            <includes>
+                <include>*.sh</include>
+            </includes>
+            <fileMode>0755</fileMode>
+            <directoryMode>0755</directoryMode>
+        </fileSet>
+        <fileSet>
+            <directory>../tools/atlas-gremlin-cli/src/main/resources</directory>
+            <outputDirectory>.</outputDirectory>
+            <includes>
+                <include>atlas-logback.xml</include>
+            </includes>
+        </fileSet>
+        <fileSet>
+            <directory>../tools/atlas-gremlin-cli/target</directory>
+            <outputDirectory>/lib</outputDirectory>
+            <includes>
+                <include>atlas-gremlin-cli-tool-*.jar</include>
+            </includes>
+        </fileSet>
+    </fileSets>
+
+</assembly>

pom.xml

@@ -71,6 +71,7 @@
         <module>repository</module>
         <module>server-api</module>
         <module>test-tools</module>
+        <module>tools/atlas-gremlin-cli</module>
         <module>tools/atlas-index-repair</module>
         <module>tools/classification-updater</module>
         <module>tools/notification-analyzer</module>

tools/atlas-gremlin-cli/README

@@ -0,0 +1,40 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+Introduction
+  atlas-gremlin-cli is a small command-line utility to run Gremlin queries against Atlas' embedded JanusGraph backend.
+
+  It uses Atlas' normal configuration loading, so it requires:
+    -Datlas.conf=/path/to/atlas/conf
+
+Setup
+  - Extract the tarball from distro/target/apache-atlas-<version>-atlas-gremlin-cli.tar.gz
+  - Set the ATLAS_CONF environment variable to the path to the Atlas configuration directory.
+  - Set the ATLAS_CLASSPATH environment variable to the path to the dependency jars.
+  - Run the atlas-gremlin-cli.sh script.
+
+Run
+  export ATLAS_CONF=/etc/atlas/conf
+  export ATLAS_CLASSPATH="/path/to/dependency/jars/*"
+  ./atlas-gremlin-cli.sh -q "g.V().limit(5).valueMap(true).toList()"
+  or
+  ./atlas-gremlin-cli.sh -f /path/to/query.groovy
+
+Notes
+  - Default behavior is to rollback the transaction (safe for read-only). Use --commit to persist mutations.
+  - For best output, end queries with .toList() or .next() or similar materialization.

tools/atlas-gremlin-cli/pom.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements.  See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership.  The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.apache.atlas</groupId>
+        <artifactId>apache-atlas</artifactId>
+        <version>3.0.0-SNAPSHOT</version>
+        <relativePath>../../</relativePath>
+    </parent>
+
+    <artifactId>atlas-gremlin-cli-tool</artifactId>
+    <packaging>jar</packaging>
+    <name>Apache Atlas Gremlin CLI Tool</name>
+    <description>Apache Atlas Gremlin CLI Tool (embedded JanusGraph)</description>
+
+    <dependencies>
+
+        <dependency>
+            <groupId>commons-cli</groupId>
+            <artifactId>commons-cli</artifactId>
+            <version>${commons-cli.version}</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.apache.atlas</groupId>
+            <artifactId>atlas-graphdb-janus</artifactId>
+            <version>${project.version}</version>
+            <scope>provided</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+</project>

tools/atlas-gremlin-cli/scripts/atlas-gremlin-cli.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+set -euo pipefail
+
+show_usage() {
+  cat <<'USAGE'
+Usage: atlas-gremlin-cli.sh [options] [-- gremlin-cli-args]
+
+Environment variables expected (set by user or system):
+  ATLAS_CONF            Path to Atlas config directory (required unless -h)
+  ATLAS_CLASSPATH       Optional classpath from an Atlas server (appended before tool jars)
+
+Examples:
+  ATLAS_CONF=/etc/atlas/conf ./atlas-gremlin-cli.sh -q "g.V().limit(5)"
+  ./atlas-gremlin-cli.sh --help
+USAGE
+}
+
+# quick -h/--help handling
+for arg in "$@"; do
+  if [[ "$arg" == "-h" || "$arg" == "--help" ]]; then
+    show_usage
+    exit 0
+  fi
+done
+
+# Find java binary
+if [ -n "${JAVA_HOME:-}" ]; then
+  JAVA_BIN="${JAVA_HOME}/bin/java"
+else
+  JAVA_BIN="$(command -v java || true)"
+fi
+
+if [ -z "${JAVA_BIN}" ] || [ ! -x "${JAVA_BIN}" ]; then
+  echo "java not found. Please set JAVA_HOME or ensure java is on PATH." >&2
+  exit 1
+fi
+
+# Require ATLAS_CONF by default (keeps behaviour same as original unless user requests help)
+if [ -z "${ATLAS_CONF:-}" ]; then
+  echo "ATLAS_CONF is not set. Example: export ATLAS_CONF=/etc/atlas/conf" >&2
+  echo "This script will set: -Datlas.conf=\$ATLAS_CONF" >&2
+  exit 2
+fi
+
+LOGFILE_DIR="${LOGFILE_DIR:-/tmp/}"
+LOGFILE_NAME="${LOGFILE_NAME:-atlas-gremlin-cli.log}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# In the distro tarball, the CLI jar is under ./lib next to this script.
+if [[ ! -d "${SCRIPT_DIR}/lib" ]]; then
+  echo "Could not locate ./lib next to this script. Are you running from the atlas-gremlin-cli tarball?" >&2
+  exit 3
+fi
+TOOL_CP="${SCRIPT_DIR}/lib/*"
+
+if [[ -n "${ATLAS_CLASSPATH:-}" ]]; then
+  CLASSPATH="${ATLAS_CLASSPATH}:${TOOL_CP}"
+else
+  CLASSPATH="${TOOL_CP}"
+fi
+
+LOGBACK_CFG="${SCRIPT_DIR}/atlas-logback.xml"
+if [[ ! -f "${LOGBACK_CFG}" ]]; then
+  echo "Could not locate ${LOGBACK_CFG}. Are you running from the atlas-gremlin-cli tarball?" >&2
+  exit 4
+fi
+exec "${JAVA_BIN}" \
+  -cp "${CLASSPATH}" \
+  -Dlogback.configurationFile="${LOGBACK_CFG}" \
+  -Datlas.log.dir="${LOGFILE_DIR}" \
+  -Datlas.log.file="${LOGFILE_NAME}" \
+  -Datlas.conf="${ATLAS_CONF}" \
+  org.apache.atlas.tools.GremlinCli "$@"
+