From 620f772a52b2c96b50fe70e1e89df376533d0f6e Mon Sep 17 00:00:00 2001 From: Sky Brewer Date: Wed, 9 Oct 2024 16:41:24 +0200 Subject: [PATCH 1/3] add a maven wrapper --- .mvn/wrapper/maven-wrapper.properties | 19 ++ README.md | 18 +- mvnw | 259 ++++++++++++++++++++++++++ mvnw.cmd | 149 +++++++++++++++ 4 files changed, 436 insertions(+), 9 deletions(-) create mode 100644 .mvn/wrapper/maven-wrapper.properties create mode 100755 mvnw create mode 100644 mvnw.cmd diff --git a/.mvn/wrapper/maven-wrapper.properties b/.mvn/wrapper/maven-wrapper.properties new file mode 100644 index 0000000..d58dfb7 --- /dev/null +++ b/.mvn/wrapper/maven-wrapper.properties @@ -0,0 +1,19 @@ +# 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. +wrapperVersion=3.3.2 +distributionType=only-script +distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip diff --git a/README.md b/README.md index 4890f84..9a26de9 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Collected installation recipes and notes may be found on [wiki pages](https://gi * Build ``` # Debian 10 -sudo apt-get install openjdk-17-jdk maven git curl wget +sudo apt-get install openjdk-17-jdk git curl wget wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.2.0-amd64.deb sudo dpkg -i elasticsearch-8.2.0-amd64.deb sudo systemctl start elasticsearch @@ -53,7 +53,7 @@ sudo systemctl start elasticsearch #### Checkout and build ChannelFinder service source git clone https://github.com/ChannelFinder/ChannelFinderService.git cd ChannelFinderService -mvn clean install +.\mvnw clean install ``` @@ -62,7 +62,7 @@ mvn clean install * Using spring boot via Maven ``` -mvn spring-boot:run +.\mvnw spring-boot:run ``` * or using the jar @@ -123,7 +123,7 @@ $ curl --basic -u admin:1234 --fail-with-body -X DELETE \ You can start the channelfinder service with your own applications.properties file as follows: ``` -mvn spring-boot:run -Dspring.config.location=file:./application.properties +.\mvnw spring-boot:run -Dspring.config.location=file:./application.properties ``` or ``` @@ -138,8 +138,8 @@ java -jar target/ChannelFinder-4.7.*.jar --cleanup=1 ``` ``` -mvn spring-boot:run -Dspring-boot.run.arguments="--demo-data=1" -mvn spring-boot:run -Dspring-boot.run.arguments="--cleanup=1" +.\mvnw spring-boot:run -Dspring-boot.run.arguments="--demo-data=1" +.\mvnw spring-boot:run -Dspring-boot.run.arguments="--cleanup=1" ``` #### Integration tests with Docker containers @@ -156,7 +156,7 @@ There are tests for properties, tags and channels separately and in combination. Integration tests can be run in IDE and via Maven. ``` -mvn failsafe:integration-test -DskipITs=false +.\mvnw failsafe:integration-test -DskipITs=false ``` See @@ -188,12 +188,12 @@ Create a sonatype account and update the maven settings.xml file with your sonat ``` **Prepare the release** -`mvn release:prepare` +`.\mvnw release:prepare` In this step will ensure there are no uncommitted changes, ensure the versions number are correct, tag the scm, etc.. A full list of checks is documented [here](https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html): **Perform the release** -`mvn release:perform` +`.\mvnw release:perform` Checkout the release tag, build, sign and push the build binaries to sonatype. **Publish** diff --git a/mvnw b/mvnw new file mode 100755 index 0000000..19529dd --- /dev/null +++ b/mvnw @@ -0,0 +1,259 @@ +#!/bin/sh +# ---------------------------------------------------------------------------- +# 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. +# ---------------------------------------------------------------------------- + +# ---------------------------------------------------------------------------- +# Apache Maven Wrapper startup batch script, version 3.3.2 +# +# Optional ENV vars +# ----------------- +# JAVA_HOME - location of a JDK home dir, required when download maven via java source +# MVNW_REPOURL - repo url base for downloading maven distribution +# MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven +# MVNW_VERBOSE - true: enable verbose log; debug: trace the mvnw script; others: silence the output +# ---------------------------------------------------------------------------- + +set -euf +[ "${MVNW_VERBOSE-}" != debug ] || set -x + +# OS specific support. +native_path() { printf %s\\n "$1"; } +case "$(uname)" in +CYGWIN* | MINGW*) + [ -z "${JAVA_HOME-}" ] || JAVA_HOME="$(cygpath --unix "$JAVA_HOME")" + native_path() { cygpath --path --windows "$1"; } + ;; +esac + +# set JAVACMD and JAVACCMD +set_java_home() { + # For Cygwin and MinGW, ensure paths are in Unix format before anything is touched + if [ -n "${JAVA_HOME-}" ]; then + if [ -x "$JAVA_HOME/jre/sh/java" ]; then + # IBM's JDK on AIX uses strange locations for the executables + JAVACMD="$JAVA_HOME/jre/sh/java" + JAVACCMD="$JAVA_HOME/jre/sh/javac" + else + JAVACMD="$JAVA_HOME/bin/java" + JAVACCMD="$JAVA_HOME/bin/javac" + + if [ ! -x "$JAVACMD" ] || [ ! -x "$JAVACCMD" ]; then + echo "The JAVA_HOME environment variable is not defined correctly, so mvnw cannot run." >&2 + echo "JAVA_HOME is set to \"$JAVA_HOME\", but \"\$JAVA_HOME/bin/java\" or \"\$JAVA_HOME/bin/javac\" does not exist." >&2 + return 1 + fi + fi + else + JAVACMD="$( + 'set' +e + 'unset' -f command 2>/dev/null + 'command' -v java + )" || : + JAVACCMD="$( + 'set' +e + 'unset' -f command 2>/dev/null + 'command' -v javac + )" || : + + if [ ! -x "${JAVACMD-}" ] || [ ! -x "${JAVACCMD-}" ]; then + echo "The java/javac command does not exist in PATH nor is JAVA_HOME set, so mvnw cannot run." >&2 + return 1 + fi + fi +} + +# hash string like Java String::hashCode +hash_string() { + str="${1:-}" h=0 + while [ -n "$str" ]; do + char="${str%"${str#?}"}" + h=$(((h * 31 + $(LC_CTYPE=C printf %d "'$char")) % 4294967296)) + str="${str#?}" + done + printf %x\\n $h +} + +verbose() { :; } +[ "${MVNW_VERBOSE-}" != true ] || verbose() { printf %s\\n "${1-}"; } + +die() { + printf %s\\n "$1" >&2 + exit 1 +} + +trim() { + # MWRAPPER-139: + # Trims trailing and leading whitespace, carriage returns, tabs, and linefeeds. + # Needed for removing poorly interpreted newline sequences when running in more + # exotic environments such as mingw bash on Windows. + printf "%s" "${1}" | tr -d '[:space:]' +} + +# parse distributionUrl and optional distributionSha256Sum, requires .mvn/wrapper/maven-wrapper.properties +while IFS="=" read -r key value; do + case "${key-}" in + distributionUrl) distributionUrl=$(trim "${value-}") ;; + distributionSha256Sum) distributionSha256Sum=$(trim "${value-}") ;; + esac +done <"${0%/*}/.mvn/wrapper/maven-wrapper.properties" +[ -n "${distributionUrl-}" ] || die "cannot read distributionUrl property in ${0%/*}/.mvn/wrapper/maven-wrapper.properties" + +case "${distributionUrl##*/}" in +maven-mvnd-*bin.*) + MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ + case "${PROCESSOR_ARCHITECTURE-}${PROCESSOR_ARCHITEW6432-}:$(uname -a)" in + *AMD64:CYGWIN* | *AMD64:MINGW*) distributionPlatform=windows-amd64 ;; + :Darwin*x86_64) distributionPlatform=darwin-amd64 ;; + :Darwin*arm64) distributionPlatform=darwin-aarch64 ;; + :Linux*x86_64*) distributionPlatform=linux-amd64 ;; + *) + echo "Cannot detect native platform for mvnd on $(uname)-$(uname -m), use pure java version" >&2 + distributionPlatform=linux-amd64 + ;; + esac + distributionUrl="${distributionUrl%-bin.*}-$distributionPlatform.zip" + ;; +maven-mvnd-*) MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ ;; +*) MVN_CMD="mvn${0##*/mvnw}" _MVNW_REPO_PATTERN=/org/apache/maven/ ;; +esac + +# apply MVNW_REPOURL and calculate MAVEN_HOME +# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-,maven-mvnd--}/ +[ -z "${MVNW_REPOURL-}" ] || distributionUrl="$MVNW_REPOURL$_MVNW_REPO_PATTERN${distributionUrl#*"$_MVNW_REPO_PATTERN"}" +distributionUrlName="${distributionUrl##*/}" +distributionUrlNameMain="${distributionUrlName%.*}" +distributionUrlNameMain="${distributionUrlNameMain%-bin}" +MAVEN_USER_HOME="${MAVEN_USER_HOME:-${HOME}/.m2}" +MAVEN_HOME="${MAVEN_USER_HOME}/wrapper/dists/${distributionUrlNameMain-}/$(hash_string "$distributionUrl")" + +exec_maven() { + unset MVNW_VERBOSE MVNW_USERNAME MVNW_PASSWORD MVNW_REPOURL || : + exec "$MAVEN_HOME/bin/$MVN_CMD" "$@" || die "cannot exec $MAVEN_HOME/bin/$MVN_CMD" +} + +if [ -d "$MAVEN_HOME" ]; then + verbose "found existing MAVEN_HOME at $MAVEN_HOME" + exec_maven "$@" +fi + +case "${distributionUrl-}" in +*?-bin.zip | *?maven-mvnd-?*-?*.zip) ;; +*) die "distributionUrl is not valid, must match *-bin.zip or maven-mvnd-*.zip, but found '${distributionUrl-}'" ;; +esac + +# prepare tmp dir +if TMP_DOWNLOAD_DIR="$(mktemp -d)" && [ -d "$TMP_DOWNLOAD_DIR" ]; then + clean() { rm -rf -- "$TMP_DOWNLOAD_DIR"; } + trap clean HUP INT TERM EXIT +else + die "cannot create temp dir" +fi + +mkdir -p -- "${MAVEN_HOME%/*}" + +# Download and Install Apache Maven +verbose "Couldn't find MAVEN_HOME, downloading and installing it ..." +verbose "Downloading from: $distributionUrl" +verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName" + +# select .zip or .tar.gz +if ! command -v unzip >/dev/null; then + distributionUrl="${distributionUrl%.zip}.tar.gz" + distributionUrlName="${distributionUrl##*/}" +fi + +# verbose opt +__MVNW_QUIET_WGET=--quiet __MVNW_QUIET_CURL=--silent __MVNW_QUIET_UNZIP=-q __MVNW_QUIET_TAR='' +[ "${MVNW_VERBOSE-}" != true ] || __MVNW_QUIET_WGET='' __MVNW_QUIET_CURL='' __MVNW_QUIET_UNZIP='' __MVNW_QUIET_TAR=v + +# normalize http auth +case "${MVNW_PASSWORD:+has-password}" in +'') MVNW_USERNAME='' MVNW_PASSWORD='' ;; +has-password) [ -n "${MVNW_USERNAME-}" ] || MVNW_USERNAME='' MVNW_PASSWORD='' ;; +esac + +if [ -z "${MVNW_USERNAME-}" ] && command -v wget >/dev/null; then + verbose "Found wget ... using wget" + wget ${__MVNW_QUIET_WGET:+"$__MVNW_QUIET_WGET"} "$distributionUrl" -O "$TMP_DOWNLOAD_DIR/$distributionUrlName" || die "wget: Failed to fetch $distributionUrl" +elif [ -z "${MVNW_USERNAME-}" ] && command -v curl >/dev/null; then + verbose "Found curl ... using curl" + curl ${__MVNW_QUIET_CURL:+"$__MVNW_QUIET_CURL"} -f -L -o "$TMP_DOWNLOAD_DIR/$distributionUrlName" "$distributionUrl" || die "curl: Failed to fetch $distributionUrl" +elif set_java_home; then + verbose "Falling back to use Java to download" + javaSource="$TMP_DOWNLOAD_DIR/Downloader.java" + targetZip="$TMP_DOWNLOAD_DIR/$distributionUrlName" + cat >"$javaSource" <<-END + public class Downloader extends java.net.Authenticator + { + protected java.net.PasswordAuthentication getPasswordAuthentication() + { + return new java.net.PasswordAuthentication( System.getenv( "MVNW_USERNAME" ), System.getenv( "MVNW_PASSWORD" ).toCharArray() ); + } + public static void main( String[] args ) throws Exception + { + setDefault( new Downloader() ); + java.nio.file.Files.copy( java.net.URI.create( args[0] ).toURL().openStream(), java.nio.file.Paths.get( args[1] ).toAbsolutePath().normalize() ); + } + } + END + # For Cygwin/MinGW, switch paths to Windows format before running javac and java + verbose " - Compiling Downloader.java ..." + "$(native_path "$JAVACCMD")" "$(native_path "$javaSource")" || die "Failed to compile Downloader.java" + verbose " - Running Downloader.java ..." + "$(native_path "$JAVACMD")" -cp "$(native_path "$TMP_DOWNLOAD_DIR")" Downloader "$distributionUrl" "$(native_path "$targetZip")" +fi + +# If specified, validate the SHA-256 sum of the Maven distribution zip file +if [ -n "${distributionSha256Sum-}" ]; then + distributionSha256Result=false + if [ "$MVN_CMD" = mvnd.sh ]; then + echo "Checksum validation is not supported for maven-mvnd." >&2 + echo "Please disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2 + exit 1 + elif command -v sha256sum >/dev/null; then + if echo "$distributionSha256Sum $TMP_DOWNLOAD_DIR/$distributionUrlName" | sha256sum -c >/dev/null 2>&1; then + distributionSha256Result=true + fi + elif command -v shasum >/dev/null; then + if echo "$distributionSha256Sum $TMP_DOWNLOAD_DIR/$distributionUrlName" | shasum -a 256 -c >/dev/null 2>&1; then + distributionSha256Result=true + fi + else + echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available." >&2 + echo "Please install either command, or disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2 + exit 1 + fi + if [ $distributionSha256Result = false ]; then + echo "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised." >&2 + echo "If you updated your Maven version, you need to update the specified distributionSha256Sum property." >&2 + exit 1 + fi +fi + +# unzip and move +if command -v unzip >/dev/null; then + unzip ${__MVNW_QUIET_UNZIP:+"$__MVNW_QUIET_UNZIP"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -d "$TMP_DOWNLOAD_DIR" || die "failed to unzip" +else + tar xzf${__MVNW_QUIET_TAR:+"$__MVNW_QUIET_TAR"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -C "$TMP_DOWNLOAD_DIR" || die "failed to untar" +fi +printf %s\\n "$distributionUrl" >"$TMP_DOWNLOAD_DIR/$distributionUrlNameMain/mvnw.url" +mv -- "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" "$MAVEN_HOME" || [ -d "$MAVEN_HOME" ] || die "fail to move MAVEN_HOME" + +clean || : +exec_maven "$@" diff --git a/mvnw.cmd b/mvnw.cmd new file mode 100644 index 0000000..b150b91 --- /dev/null +++ b/mvnw.cmd @@ -0,0 +1,149 @@ +<# : batch portion +@REM ---------------------------------------------------------------------------- +@REM Licensed to the Apache Software Foundation (ASF) under one +@REM or more contributor license agreements. See the NOTICE file +@REM distributed with this work for additional information +@REM regarding copyright ownership. The ASF licenses this file +@REM to you under the Apache License, Version 2.0 (the +@REM "License"); you may not use this file except in compliance +@REM with the License. You may obtain a copy of the License at +@REM +@REM http://www.apache.org/licenses/LICENSE-2.0 +@REM +@REM Unless required by applicable law or agreed to in writing, +@REM software distributed under the License is distributed on an +@REM "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +@REM KIND, either express or implied. See the License for the +@REM specific language governing permissions and limitations +@REM under the License. +@REM ---------------------------------------------------------------------------- + +@REM ---------------------------------------------------------------------------- +@REM Apache Maven Wrapper startup batch script, version 3.3.2 +@REM +@REM Optional ENV vars +@REM MVNW_REPOURL - repo url base for downloading maven distribution +@REM MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven +@REM MVNW_VERBOSE - true: enable verbose log; others: silence the output +@REM ---------------------------------------------------------------------------- + +@IF "%__MVNW_ARG0_NAME__%"=="" (SET __MVNW_ARG0_NAME__=%~nx0) +@SET __MVNW_CMD__= +@SET __MVNW_ERROR__= +@SET __MVNW_PSMODULEP_SAVE=%PSModulePath% +@SET PSModulePath= +@FOR /F "usebackq tokens=1* delims==" %%A IN (`powershell -noprofile "& {$scriptDir='%~dp0'; $script='%__MVNW_ARG0_NAME__%'; icm -ScriptBlock ([Scriptblock]::Create((Get-Content -Raw '%~f0'))) -NoNewScope}"`) DO @( + IF "%%A"=="MVN_CMD" (set __MVNW_CMD__=%%B) ELSE IF "%%B"=="" (echo %%A) ELSE (echo %%A=%%B) +) +@SET PSModulePath=%__MVNW_PSMODULEP_SAVE% +@SET __MVNW_PSMODULEP_SAVE= +@SET __MVNW_ARG0_NAME__= +@SET MVNW_USERNAME= +@SET MVNW_PASSWORD= +@IF NOT "%__MVNW_CMD__%"=="" (%__MVNW_CMD__% %*) +@echo Cannot start maven from wrapper >&2 && exit /b 1 +@GOTO :EOF +: end batch / begin powershell #> + +$ErrorActionPreference = "Stop" +if ($env:MVNW_VERBOSE -eq "true") { + $VerbosePreference = "Continue" +} + +# calculate distributionUrl, requires .mvn/wrapper/maven-wrapper.properties +$distributionUrl = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionUrl +if (!$distributionUrl) { + Write-Error "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties" +} + +switch -wildcard -casesensitive ( $($distributionUrl -replace '^.*/','') ) { + "maven-mvnd-*" { + $USE_MVND = $true + $distributionUrl = $distributionUrl -replace '-bin\.[^.]*$',"-windows-amd64.zip" + $MVN_CMD = "mvnd.cmd" + break + } + default { + $USE_MVND = $false + $MVN_CMD = $script -replace '^mvnw','mvn' + break + } +} + +# apply MVNW_REPOURL and calculate MAVEN_HOME +# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-,maven-mvnd--}/ +if ($env:MVNW_REPOURL) { + $MVNW_REPO_PATTERN = if ($USE_MVND) { "/org/apache/maven/" } else { "/maven/mvnd/" } + $distributionUrl = "$env:MVNW_REPOURL$MVNW_REPO_PATTERN$($distributionUrl -replace '^.*'+$MVNW_REPO_PATTERN,'')" +} +$distributionUrlName = $distributionUrl -replace '^.*/','' +$distributionUrlNameMain = $distributionUrlName -replace '\.[^.]*$','' -replace '-bin$','' +$MAVEN_HOME_PARENT = "$HOME/.m2/wrapper/dists/$distributionUrlNameMain" +if ($env:MAVEN_USER_HOME) { + $MAVEN_HOME_PARENT = "$env:MAVEN_USER_HOME/wrapper/dists/$distributionUrlNameMain" +} +$MAVEN_HOME_NAME = ([System.Security.Cryptography.MD5]::Create().ComputeHash([byte[]][char[]]$distributionUrl) | ForEach-Object {$_.ToString("x2")}) -join '' +$MAVEN_HOME = "$MAVEN_HOME_PARENT/$MAVEN_HOME_NAME" + +if (Test-Path -Path "$MAVEN_HOME" -PathType Container) { + Write-Verbose "found existing MAVEN_HOME at $MAVEN_HOME" + Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD" + exit $? +} + +if (! $distributionUrlNameMain -or ($distributionUrlName -eq $distributionUrlNameMain)) { + Write-Error "distributionUrl is not valid, must end with *-bin.zip, but found $distributionUrl" +} + +# prepare tmp dir +$TMP_DOWNLOAD_DIR_HOLDER = New-TemporaryFile +$TMP_DOWNLOAD_DIR = New-Item -Itemtype Directory -Path "$TMP_DOWNLOAD_DIR_HOLDER.dir" +$TMP_DOWNLOAD_DIR_HOLDER.Delete() | Out-Null +trap { + if ($TMP_DOWNLOAD_DIR.Exists) { + try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null } + catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" } + } +} + +New-Item -Itemtype Directory -Path "$MAVEN_HOME_PARENT" -Force | Out-Null + +# Download and Install Apache Maven +Write-Verbose "Couldn't find MAVEN_HOME, downloading and installing it ..." +Write-Verbose "Downloading from: $distributionUrl" +Write-Verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName" + +$webclient = New-Object System.Net.WebClient +if ($env:MVNW_USERNAME -and $env:MVNW_PASSWORD) { + $webclient.Credentials = New-Object System.Net.NetworkCredential($env:MVNW_USERNAME, $env:MVNW_PASSWORD) +} +[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 +$webclient.DownloadFile($distributionUrl, "$TMP_DOWNLOAD_DIR/$distributionUrlName") | Out-Null + +# If specified, validate the SHA-256 sum of the Maven distribution zip file +$distributionSha256Sum = (Get-Content -Raw "$scriptDir/.mvn/wrapper/maven-wrapper.properties" | ConvertFrom-StringData).distributionSha256Sum +if ($distributionSha256Sum) { + if ($USE_MVND) { + Write-Error "Checksum validation is not supported for maven-mvnd. `nPlease disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." + } + Import-Module $PSHOME\Modules\Microsoft.PowerShell.Utility -Function Get-FileHash + if ((Get-FileHash "$TMP_DOWNLOAD_DIR/$distributionUrlName" -Algorithm SHA256).Hash.ToLower() -ne $distributionSha256Sum) { + Write-Error "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised. If you updated your Maven version, you need to update the specified distributionSha256Sum property." + } +} + +# unzip and move +Expand-Archive "$TMP_DOWNLOAD_DIR/$distributionUrlName" -DestinationPath "$TMP_DOWNLOAD_DIR" | Out-Null +Rename-Item -Path "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" -NewName $MAVEN_HOME_NAME | Out-Null +try { + Move-Item -Path "$TMP_DOWNLOAD_DIR/$MAVEN_HOME_NAME" -Destination $MAVEN_HOME_PARENT | Out-Null +} catch { + if (! (Test-Path -Path "$MAVEN_HOME" -PathType Container)) { + Write-Error "fail to move MAVEN_HOME" + } +} finally { + try { Remove-Item $TMP_DOWNLOAD_DIR -Recurse -Force | Out-Null } + catch { Write-Warning "Cannot remove $TMP_DOWNLOAD_DIR" } +} + +Write-Output "MVN_CMD=$MAVEN_HOME/bin/$MVN_CMD" From 8f19604cfcc9b9a6c5aa3366bb5983b36e274127 Mon Sep 17 00:00:00 2001 From: Sky Brewer Date: Thu, 24 Oct 2024 09:36:38 +0200 Subject: [PATCH 2/3] Update the README --- README.md | 235 ++++++++++++++++++++++++++---------------------------- 1 file changed, 111 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index 9a26de9..c9232bd 100644 --- a/README.md +++ b/README.md @@ -1,200 +1,187 @@ -### Channel Finder +# Channel Finder -#### A simple directory service +ChannelFinder is a directory server, implemented as a REST style web service. +Its intended use is for control systems, namely the EPICS Control system. - ChannelFinder is a directory server, implemented as a REST style web service. -Its intended use is within control systems, namely the EPICS Control system, for which it has been written. +- [Documentation](https://channelfinder.readthedocs.io/en/latest/) +- [Releases](https://github.com/ChannelFinder/ChannelFinderService/releases) +- [Docker Containers](https://github.com/ChannelFinder/ChannelFinderService/pkgs/container/channelfinderservice) -* Motivation and Objectives +## Description - High level applications tend to prefer an hierarchical view of the control system name space. They group channel names by location or physical function. The name space of the EPICS Channel Access protocol, on the other hand, is flat. A good and thoroughly enforced naming convention may solve the problem of creating unique predictable names. It does not free every application from being configured explicitly, so that it knows all channel names it might be interested in beforehand. +* **Motivation and Objectives** - ChannelFinder tries to overcome this limitation by implementing a generic directory service, which applications can query for a list of channels that match certain conditions, such as physical functionality or location. It also provides mechanisms to create channel name aliases, allowing for different perspectives of the same set of channel names. + High level applications tend to prefer a hierarchical view of the control system name space. They group channel names + by location or physical function. The name space of the EPICS Channel Access protocol, on the other hand, is flat. A + good and thoroughly enforced naming convention may solve the problem of creating unique predictable names. It does not + free every application from being configured explicitly, so that it knows all channel names it might be interested in + beforehand. -* Directory Data Structure + ChannelFinder tries to overcome this limitation by implementing a generic directory service, which applications can + query for a list of channels that match certain conditions, such as physical functionality or location. It also + provides mechanisms to create channel name aliases, allowing for different perspectives of the same set of channel + names. - Each directory entry consists of a channel ``, an arbitrary set of `` (name-value pairs), and an arbitrary set of `` (names). +* **Directory Data Structure** -* Basic Operation + Each directory entry consists of a channel ``, an arbitrary set of `` (name-value pairs), and an + arbitrary set of `` (names). - An application sends an HTTP query to the service, specifying an expression that references tags, properties and their values, or channel names. The service returns a list of matching channels with their properties and tags, as JSON documents. +* **Basic Operation** + An application sends an HTTP query to the service, specifying an expression that references tags, properties and their + values, or channel names. The service returns a list of matching channels with their properties and tags, as JSON + documents. -#### API reference guide +## Installation -https://channelfinder.readthedocs.io/en/latest/ +ChannelFinder is a Java EE5 REST-style web service. The directory data is held in a ElasticSearch index. -#### Installation +### Docker Compose -ChannelFinder is a Java EE5 REST-style web service. The directory data is held in a ElasticSearch index. +For using docker containers there is a barebones [docker compose file](./docker-compose.yml). -Collected installation recipes and notes may be found on [wiki pages](https://github.com/ChannelFinder/ChannelFinder-SpringBoot/wiki). +### Manual Installation * Prerequisites - * JDK 17 - * Elastic version 8.2.x - * LDAP server, e.g. OpenLDAP - -* setup elastic search - **Install** - Download and install elasticsearch (verision 8.2.0) from [elastic.com](https://www.elastic.co/downloads/past-releases/elasticsearch-8-2-0) - following the instructions for your platform.\ - Install the elastic server from your distribution using a package manager. - -* Build -``` -# Debian 10 -sudo apt-get install openjdk-17-jdk git curl wget -wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-8.2.0-amd64.deb -sudo dpkg -i elasticsearch-8.2.0-amd64.deb -sudo systemctl start elasticsearch + * JDK 17 + * Elastic version 8.11.x + * **For authN/authZ using LDAP:** LDAP server, e.g. OpenLDAP -#### Checkout and build ChannelFinder service source -git clone https://github.com/ChannelFinder/ChannelFinderService.git -cd ChannelFinderService -.\mvnw clean install +#### Setup Elasticsearch -``` +Options: -#### Start the service +- Download and install elasticsearch (version 8.11.0) + from [elastic.com](https://www.elastic.co) following the instructions for + your platform. +- Install the elastic server from your distribution using a package manager. +- Run Elasticsearch in a [docker container](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html) -* Using spring boot via Maven +#### Running -``` -.\mvnw spring-boot:run -``` +```bash +sudo apt-get install openjdk-17-jre git curl wget +sudo systemctl start elasticsearch # Or other command to run elastic search -* or using the jar +# Replace verison with the release you want +wget https://github.com/ChannelFinder/ChannelFinderService/releases/download/ChannelFinder-{version}/ChannelFinder-{version}.jar +java -jar target/ChannelFinder-*.jar +``` -``` -java -jar target/ChannelFinder-4.7.0.jar +Other installation recipes can be found +on [the wiki pages](https://github.com/ChannelFinder/ChannelFinder-SpringBoot/wiki). + +### Configuration + +By default, the channelfinder service will start on port 8080 with the default settings. To start with a +different `application.properties` file: + +```bash +java -Dspring.config.location=file:./application.properties -jar ChannelFinder-*.jar ``` -The above command will start the channelfinder service on port 8080 with the default settings, -which use embedded ldap server with users and roles defined in the [`cf.ldif`](src/main/resources/cf.ldif) file. +The default authentication includes an embedded ldap server with users and roles defined in +the [`cf.ldif`](src/main/resources/cf.ldif) file. Note that `cf.ldif` contains **default credentials** and should only be used during testing and evaluation. -#### Verification +### Verification -To check that the server is running correctly. +To check that the server is running correctly, visit [the default homepage](http://localhost:8080/). -``` -$ curl --fail-with-body http://localhost:8080/ChannelFinder -{ - "name" : "ChannelFinder Service", - "version" : "4.7.0", - "elastic" : { - "status" : "Connected", - "clusterName" : "elasticsearch", - "clusterUuid" : "sA2L_cpoRD-H46c_Mya3mA", - "version" : "8.2.0" - } -} - - -# Verify by creating a simple Channel using the demo auth -$ curl --location -u admin:adminPass --request PUT 'http://localhost:7070/ChannelFinder/resources/channels/test_channel' \ ---header 'Content-Type: application/json' \ ---data '{ - "name": "test_channel", - "owner": "admin" - }' - -$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/channels - -... -$ curl --basic -u admin:adminPass --fail-with-body -H 'Content-Type: application/json' \ - -X PUT -d '{"name":"foo", "owner":"admin"}' \ - http://localhost:8080/ChannelFinder/resources/tags/foo - -$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/tags - -... -$ curl --fail-with-body http://localhost:8080/ChannelFinder/resources/tags -[{"name":"foo","owner":"admin","channels":[]}] - -$ curl --basic -u admin:1234 --fail-with-body -X DELETE \ - http://localhost:8080/ChannelFinder/resources/tags/foo -``` +## Development -#### Start up options +It's strongly encouraged to use a modern IDE such as [Intelij](https://www.jetbrains.com/idea/) and [Eclipse](https://eclipseide.org/). -You can start the channelfinder service with your own applications.properties file as follows: +* Prerequisites -``` -.\mvnw spring-boot:run -Dspring.config.location=file:./application.properties -``` -or -``` -java -Dspring.config.location=file:./application.properties -jar ChannelFinder-4.7.0.jar -``` + * JDK 17 + * Maven (via package manager or via the wrapper `./mvnw`) (version specified in [the wrapper properties](./.mvn/wrapper/maven-wrapper.properties)) -You can also start up channelfinder with demo data using the command line argument `demo-data` followed by an integer number `n`. For example, `--demo-data=n`. With this argument, `n*1500` channels will be created to simulate some of the most common types of devices found in accelerators like magnets, power supplies, etc... +For the following commands `mvn` can be interchangeably used instead via `./mvnw` +To build: + +```bash +mvn clean install ``` -java -jar target/ChannelFinder-4.7.*.jar --demo-data=1 -java -jar target/ChannelFinder-4.7.*.jar --cleanup=1 -``` - + +To test: + +```bash +mvn test ``` -.\mvnw spring-boot:run -Dspring-boot.run.arguments="--demo-data=1" -.\mvnw spring-boot:run -Dspring-boot.run.arguments="--cleanup=1" + +To run the server in development (you need a running version of Elasticsearch) + +```bash +mvn spring-boot:run ``` -#### Integration tests with Docker containers +### Integration tests with Docker containers Purpose is to have integration tests for ChannelFinder API with Docker. See `src/test/java` and package + * `org.phoebus.channelfinder.docker` -Integration tests start docker containers for ChannelFinder and Elasticsearch and run http requests (GET) and curl commands (POST, PUT, DELETE) towards the application to test behavior (read, list, query, create, update, remove) and replies are received and checked if content is as expected. +Integration tests start docker containers for ChannelFinder and Elasticsearch and run http requests (GET, POST, PUT, DELETE) towards the application to test behavior (read, list, query, create, update, remove) and +replies are received and checked if content is as expected. There are tests for properties, tags and channels separately and in combination. Integration tests can be run in IDE and via Maven. ``` -.\mvnw failsafe:integration-test -DskipITs=false +mvn failsafe:integration-test -DskipITs=false ``` -See +See also + * [How to run Integration test with Docker](src/test/resources/INTEGRATIONTEST_DOCKER_RUN.md) * [Tutorial for Integration test with Docker](src/test/resources/INTEGRATIONTEST_DOCKER_TUTORIAL.md) -#### ChannelFinder data managment - -The [cf-manager](https://github.com/ChannelFinder/cf-manager) project provides tools to perform operations on large queries ( potentially the entire directory ). -Some examples of these operations include running checks to validate the pv names or producing reports about the number of active PVs, a list of IOC names, etc.. - ### Release ChannelFinder Server binaries to maven central -The Phoebus ChannelFinder service uses the maven release plugin to prepare the publish the ChannelFinder server binaries to maven central +The Phoebus ChannelFinder service uses the maven release plugin to prepare the publish the ChannelFinder server binaries +to maven central using the sonatype repositories. -**Setup** +#### Setup Create a sonatype account and update the maven settings.xml file with your sonatype credentials -``` +```xml phoebus-releases - shroffk + username ******* ``` -**Prepare the release** -`.\mvnw release:prepare` +#### Prepare the release + +```bash +mvn release:prepare +``` In this step will ensure there are no uncommitted changes, ensure the versions number are correct, tag the scm, etc.. -A full list of checks is documented [here](https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html): +A full list of checks is +documented [here](https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html): + +#### Perform the release + + +```bash +mvn release:perform +``` -**Perform the release** -`.\mvnw release:perform` Checkout the release tag, build, sign and push the build binaries to sonatype. -**Publish** -Open the staging repository in [sonatype](https://s01.oss.sonatype.org/#stagingRepositories) and hit the *publish* button +#### Publish + +Open the staging repository in [sonatype](https://s01.oss.sonatype.org/#stagingRepositories) and hit the *publish* +button From 194fcb78752421c780d1f76d38d40a2512e21214 Mon Sep 17 00:00:00 2001 From: Sky Brewer Date: Thu, 21 Nov 2024 09:36:30 +0100 Subject: [PATCH 3/3] Add link for the swagger api docs --- README.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index c9232bd..6ccdc9d 100644 --- a/README.md +++ b/README.md @@ -88,16 +88,19 @@ Note that `cf.ldif` contains **default credentials** and should only be used dur ### Verification -To check that the server is running correctly, visit [the default homepage](http://localhost:8080/). +To check that the server is running correctly, visit [the default homepage](http://localhost:8080/). For more +information on the api see the [swagger docs endpoint](http://localhost:8080/swagger-ui/index.html). ## Development -It's strongly encouraged to use a modern IDE such as [Intelij](https://www.jetbrains.com/idea/) and [Eclipse](https://eclipseide.org/). +It's strongly encouraged to use a modern IDE such as [Intelij](https://www.jetbrains.com/idea/) +and [Eclipse](https://eclipseide.org/). * Prerequisites - * JDK 17 - * Maven (via package manager or via the wrapper `./mvnw`) (version specified in [the wrapper properties](./.mvn/wrapper/maven-wrapper.properties)) + * JDK 17 + * Maven (via package manager or via the wrapper `./mvnw`) (version specified + in [the wrapper properties](./.mvn/wrapper/maven-wrapper.properties)) For the following commands `mvn` can be interchangeably used instead via `./mvnw` @@ -127,7 +130,8 @@ See `src/test/java` and package * `org.phoebus.channelfinder.docker` -Integration tests start docker containers for ChannelFinder and Elasticsearch and run http requests (GET, POST, PUT, DELETE) towards the application to test behavior (read, list, query, create, update, remove) and +Integration tests start docker containers for ChannelFinder and Elasticsearch and run http requests (GET, POST, PUT, +DELETE) towards the application to test behavior (read, list, query, create, update, remove) and replies are received and checked if content is as expected. There are tests for properties, tags and channels separately and in combination. @@ -154,13 +158,13 @@ using the sonatype repositories. Create a sonatype account and update the maven settings.xml file with your sonatype credentials ```xml - - - phoebus-releases - username - ******* - - + + + phoebus-releases + username + ******* + + ``` #### Prepare the release @@ -168,13 +172,13 @@ Create a sonatype account and update the maven settings.xml file with your sonat ```bash mvn release:prepare ``` + In this step will ensure there are no uncommitted changes, ensure the versions number are correct, tag the scm, etc.. A full list of checks is documented [here](https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html): #### Perform the release - ```bash mvn release:perform ```