Merge branch 'main' into java-27

Author: jrodolfo

AGENTS.md

@@ -0,0 +1,4 @@
+# User preferences
+
+- Whenever you change any files, include a suggested Git commit message written entirely in lowercase in your final response. This also applies to changes to this file.
+- Providing a commit message does not authorize staging, committing, or pushing changes.

scripts/use-java-26-linux.sh

@@ -1,76 +1,83 @@
 #!/usr/bin/env bash
 
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+# Sourcing uses the caller's shell, regardless of the shebang.
+if { [[ -n "${BASH_VERSION:-}" ]] && [[ "${BASH_SOURCE[0]}" == "$0" ]]; } ||
+   { [[ -n "${ZSH_VERSION:-}" ]] && [[ "${ZSH_EVAL_CONTEXT:-}" != *:file ]]; }; then
   echo "This script must be sourced so it can update the current shell:"
   echo "  source scripts/use-java-26-linux.sh [JAVA_26_HOME]"
   exit 1
 fi
 
-set_java_home_candidate() {
-  local candidate="$1"
+use_java_26_linux() {
+  local candidate java_bin remaining entry new_path
 
-  if [[ -z "$candidate" ]]; then
-    return 1
-  fi
+  # Discover in a subshell so glob options and helper functions stay local.
+  candidate="$(
+    if [[ -n "${ZSH_VERSION:-}" ]]; then
+      setopt NULL_GLOB
+    else
+      shopt -s nullglob
+    fi
 
-  if [[ -x "$candidate/bin/java" ]]; then
-    local version_output
-    version_output="$("$candidate/bin/java" --version 2>&1 | head -n 1)"
+    set_java_home_candidate() {
+      local candidate="$1" version_output
+      local version_pattern='^(openjdk|java)[[:space:]]26([[:space:].+-]|$)'
 
-    if [[ "$version_output" =~ ^(openjdk|java)[[:space:]]26([[:space:].]|$) ]]; then
-      export JAVA_HOME="$candidate"
-      export PATH="$JAVA_HOME/bin:$PATH"
-      echo "JAVA_HOME=$JAVA_HOME"
-      java --version
-      return 0
-    fi
-  fi
+      [[ -n "$candidate" && -x "$candidate/bin/java" && -x "$candidate/bin/javac" ]] || return 1
+      version_output="$("$candidate/bin/java" --version 2>&1)" || return 1
+      [[ "$version_output" =~ $version_pattern ]] || return 1
+      # Keep JAVA_HOME valid after changing directories.
+      (cd -- "$candidate" && pwd -P)
+    }
 
-  return 1
-}
+    if [[ -n "${1:-}" ]]; then
+      set_java_home_candidate "$1" && exit 0
+      echo "The supplied path is not a valid JDK 26 home: $1" >&2
+      exit 1
+    fi
 
-java_home_arg="${1:-}"
+    for candidate in \
+      "${JAVA26_HOME:-}" \
+      "${JDK26_HOME:-}" \
+      /usr/lib/jvm/*26* \
+      /opt/jdk-26* \
+      /opt/java/jdk-26* \
+      /usr/local/jdk-26* \
+      "${SDKMAN_CANDIDATES_DIR:-${SDKMAN_DIR:-$HOME/.sdkman}/candidates}"/java/26*
+    do
+      if set_java_home_candidate "$candidate"; then
+        exit 0
+      fi
+    done
 
-if [[ -n "$java_home_arg" ]]; then
-  if set_java_home_candidate "$java_home_arg"; then
-    return 0
-  fi
+    echo "Could not find a JDK 26 installation." >&2
+    echo "Pass the JDK path explicitly, or set JAVA26_HOME or JDK26_HOME first." >&2
+    exit 1
+  )" || return 1
 
-  echo "The supplied path is not a valid JDK 26 home: $java_home_arg"
-  return 1
-fi
+  # Move the selected bin directory to the front without duplicating it.
+  java_bin="$candidate/bin"
+  remaining="$PATH"
+  new_path="$java_bin"
+  while true; do
+    entry="${remaining%%:*}"
+    if [[ "$entry" != "$java_bin" ]]; then
+      new_path="$new_path:$entry"
+    fi
+    [[ "$remaining" == *:* ]] || break
+    remaining="${remaining#*:}"
+  done
 
-if set_java_home_candidate "${JAVA26_HOME:-}"; then
-  return 0
-fi
+  export JAVA_HOME="$candidate"
+  export PATH="$new_path"
+  echo "JAVA_HOME=$JAVA_HOME"
+  java --version
+}
 
-if set_java_home_candidate "${JDK26_HOME:-}"; then
+if use_java_26_linux "$@"; then
+  unset -f use_java_26_linux
   return 0
+else
+  unset -f use_java_26_linux
+  return 1
 fi
-
-shopt -s nullglob
-for candidate in \
-  /usr/lib/jvm/*26* \
-  /opt/jdk-26* \
-  /opt/java/jdk-26* \
-  /usr/local/jdk-26* \
-  "$HOME"/.sdkman/candidates/java/*26*
-do
-  if set_java_home_candidate "$candidate"; then
-    shopt -u nullglob
-    return 0
-  fi
-done
-shopt -u nullglob
-
-echo "Could not find a JDK 26 installation."
-echo "Pass the JDK path explicitly, or set JAVA26_HOME or JDK26_HOME first."
-echo "Checked common Linux locations:"
-echo "  /usr/lib/jvm/*26*"
-echo "  /opt/jdk-26*"
-echo "  /opt/java/jdk-26*"
-echo "  /usr/local/jdk-26*"
-echo "  $HOME/.sdkman/candidates/java/*26*"
-echo "Example:"
-echo "  source scripts/use-java-26-linux.sh /usr/lib/jvm/jdk-26.0.2.1"
-return 1

src/main/java/net/jrodolfo/java_evolution/java01/javabeans/README.md

@@ -17,8 +17,17 @@ JavaBeans defined conventions such as no-argument constructors, getter/setter pr
 - a no-argument constructor makes the component easy for tools to create
 - `getName` and `setName` define a `name` property
 - `isActive` and `setActive` define a boolean `active` property
-- `addProjectListener` and `removeProjectListener` define an event-set convention
-- `Introspector` exposes this metadata through descriptors
+- matching `addProjectListener(ProjectListener)` and
+  `removeProjectListener(ProjectListener)` methods tell JavaBeans that the bean
+  publishes events to `ProjectListener` objects
+- an "event set" means this relationship between an event source and its
+  listener type; it does not mean `java.util.Set`
+- `Introspector` examines JavaBeans naming conventions and returns `BeanInfo`
+- `BeanInfo` exposes the information through descriptors such as
+  `PropertyDescriptor`, `MethodDescriptor`, and `EventSetDescriptor`
+
+A descriptor is simply an object that describes one part of a bean, such as a
+property, method, or event set.
 
 The point is not the amount of code in the bean. The point is that tools can discover properties and events without each component implementing a custom metadata API.