feat(forward): provide Java 8 client and packaged examples

Author: moonyue-w

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+mvnw text eol=lf
+mvnw.cmd text eol=crlf

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @moonyue-w

.github/config/main-ruleset.json

@@ -0,0 +1,71 @@
+{
+  "name": "Protect main",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "exclude": [],
+      "include": [
+        "~DEFAULT_BRANCH"
+      ]
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "required_linear_history"
+    },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": true,
+        "allowed_merge_methods": [
+          "squash"
+        ]
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": true,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          {
+            "context": "check (Java 8)",
+            "integration_id": 15368
+          },
+          {
+            "context": "check (Java 11)",
+            "integration_id": 15368
+          },
+          {
+            "context": "check (Java 17)",
+            "integration_id": 15368
+          },
+          {
+            "context": "check (Java 21)",
+            "integration_id": 15368
+          },
+          {
+            "context": "check (Java 25)",
+            "integration_id": 15368
+          },
+          {
+            "context": "quality",
+            "integration_id": 15368
+          }
+        ]
+      }
+    }
+  ],
+  "bypass_actors": []
+}

.github/config/release-branch.json

@@ -0,0 +1 @@
+{"name": "main", "type": "branch"}

.github/config/release-environment.json

@@ -0,0 +1,6 @@
+{
+  "wait_timer": 0,
+  "prevent_self_review": false,
+  "reviewers": [{"type": "User", "id": 300878504}],
+  "deployment_branch_policy": {"protected_branches": false, "custom_branch_policies": true}
+}

.github/config/tag-ruleset.json

@@ -0,0 +1,25 @@
+{
+  "name": "protect-release-tags",
+  "target": "tag",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "exclude": [],
+      "include": [
+        "refs/tags/v*"
+      ]
+    }
+  },
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "update"
+    }
+  ],
+  "bypass_actors": []
+}

.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## Change
+
+Describe the problem and resulting public behavior. For a new API, identify its contract source and the Forward coverage entry.
+
+Describe any Go / Python / TypeScript behavior impact, or explain why this change is Java-specific.
+For incompatible changes, describe the previous behavior and the required migration.
+
+## Validation
+
+- [ ] SDK build, tests and Javadoc pass.
+- [ ] Independent examples consume the installed JAR and pass.
+- [ ] Java 8 package check passes; changed runtime behavior is checked on the relevant JDKs.
+- [ ] Documentation and changelog reflect public behavior changes.
+- [ ] `make quality` passes on JDK 17+ (format, versions, changelog and local links).
+- [ ] Any version change updates both POMs and the matching changelog entry.
+
+List actual JDKs and commands, and any live scenarios run. Explain failures or untested scope; mock tests are not live verification. Keep tokens, SA Keys and signed URLs out of this PR.
+
+For a QA candidate, record source SHA, artifact SHA-256 and the run/report link.
+State skipped or unexecuted scenarios separately from passing tests. Human QA approval is separate from automated results.

.github/scripts/check_package.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Inspect the locally built SDK; no network access or publication."""
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import struct
+import xml.etree.ElementTree as ET
+import zipfile
+
+
+def require(condition, message):
+    if not condition:
+        raise ValueError(message)
+
+
+def check(root):
+    pom = root / "pom.xml"
+    xml = ET.parse(pom).getroot()
+    ns = {"m": "http://maven.apache.org/POM/4.0.0"}
+    artifact = xml.findtext("m:artifactId", namespaces=ns)
+    version = xml.findtext("m:version", namespaces=ns)
+    require(artifact == "qca-sdk" and version, "Unexpected SDK coordinates")
+    target = root / "target"
+    jars = [target / (artifact + "-" + version + suffix + ".jar")
+            for suffix in ("", "-sources", "-javadoc")]
+    for jar in jars:
+        require(jar.is_file(), "Missing package: " + jar.name)
+    with zipfile.ZipFile(jars[0]) as jar:
+        names = jar.namelist()
+        classes = [name for name in names if name.endswith(".class")]
+        require(classes, "SDK JAR has no classes")
+        require("com/qoder/cloudagents/ForwardClient.class" in names, "Missing Forward client")
+        require(jar.read("META-INF/LICENSE") == (root / "LICENSE").read_bytes(), "License differs")
+        properties = jar.read("com/qoder/cloudagents/version.properties").decode("utf-8")
+        require("version=" + version in properties.splitlines(), "Embedded version differs from POM")
+        for name in classes:
+            require(name.startswith("com/qoder/cloudagents/") and "/examples/" not in name,
+                    "Bundled dependency or example class: " + name)
+            data = jar.read(name)
+            require(data[:4] == b"\xca\xfe\xba\xbe" and struct.unpack(">H", data[6:8])[0] == 52,
+                    "Class does not target Java 8: " + name)
+        require(not any(name.startswith(("src/test/", "test-results/", "artifacts/"))
+                        or Path(name).name.startswith(".env") for name in names),
+                "Unexpected local or test data in SDK JAR")
+    with zipfile.ZipFile(jars[1]) as jar:
+        require("com/qoder/cloudagents/ForwardClient.java" in jar.namelist(), "Missing source attachment")
+    with zipfile.ZipFile(jars[2]) as jar:
+        require("com/qoder/cloudagents/ForwardClient.html" in jar.namelist(), "Missing Javadoc attachment")
+        require(not any(name.startswith("com/qoder/cloudagents/core/internal/") for name in jar.namelist()),
+                "Internal implementation leaked into public Javadoc")
+    files = jars + [pom]
+    digests = {str(path.relative_to(root)): hashlib.sha256(path.read_bytes()).hexdigest() for path in files}
+    report = {"artifact_id": artifact, "version": version, "class_count": len(classes),
+              "class_major_version": 52, "sha256": digests}
+    (target / "package-check.json").write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+    (target / "SHA256SUMS").write_text("".join(digest + "  " + name + "\n" for name, digest in digests.items()), encoding="utf-8")
+    print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[2])
+    try:
+        check(parser.parse_args().root.resolve())
+    except (ValueError, KeyError, OSError, zipfile.BadZipFile, ET.ParseError) as error:
+        raise SystemExit("Package check failed: " + str(error))

.github/scripts/check_repository.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Verify Maven versions, changelog and local documentation links; never publish."""
+import argparse
+from pathlib import Path
+import re
+import sys
+import urllib.parse
+import xml.etree.ElementTree as ET
+
+import release_notes
+
+ROOT = Path(__file__).resolve().parents[2]
+NS = {"m": "http://maven.apache.org/POM/4.0.0"}
+
+
+def check_versions(root):
+    pom = ET.parse(root / "pom.xml").getroot()
+    version = pom.findtext("m:version", namespaces=NS)
+    if not version or not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?", version):
+        raise ValueError("Use an explicit SDK version in pom.xml")
+    if pom.findtext("m:groupId", namespaces=NS) != "com.qoder" or pom.findtext("m:artifactId", namespaces=NS) != "qca-sdk":
+        raise ValueError("Unexpected Maven coordinates")
+    consumer = ET.parse(root / "examples/pom.xml").getroot()
+    deps = [d for d in consumer.findall("m:dependencies/m:dependency", NS)
+            if d.findtext("m:groupId", namespaces=NS) == "com.qoder"
+            and d.findtext("m:artifactId", namespaces=NS) == "qca-sdk"]
+    if len(deps) != 1 or deps[0].findtext("m:version", namespaces=NS) != version:
+        raise ValueError("examples SDK dependency must match the root POM")
+    if consumer.findtext("m:version", namespaces=NS) != version:
+        raise ValueError("examples project version must match the root POM")
+    props = (root / "src/main/resources/com/qoder/cloudagents/version.properties").read_text()
+    if "version=${project.version}" not in props.splitlines():
+        raise ValueError("Embedded version must be filtered from project.version")
+    entries = release_notes.parse_changelog((root / "CHANGELOG.md").read_text())
+    if not version.endswith("-SNAPSHOT") and version not in entries:
+        raise ValueError("Non-SNAPSHOT version requires its own changelog entry")
+    return version
+
+
+def check_links(root):
+    paths = [root / name for name in ("README.md", "CONTRIBUTING.md", "CHANGELOG.md",
+                                     "examples/README.md", ".github/pull_request_template.md")]
+    paths += list((root / "docs").rglob("*.md"))
+    count = 0
+    for path in paths:
+        visible = "\n".join(release_notes.outside_fences(path.read_text()))
+        for match in re.finditer(r"\[[^\]]*\]\(([^\s)]+)(?:\s+[^)]*)?\)", visible):
+            target = match[1].strip("<>")
+            url = urllib.parse.urlsplit(target)
+            if url.scheme or url.netloc or not url.path:
+                continue
+            resolved = (path.parent / urllib.parse.unquote(url.path)).resolve()
+            if not resolved.is_relative_to(root.resolve()) or not resolved.exists():
+                raise ValueError(f"{path.relative_to(root)}: invalid local link {target}")
+            count += 1
+    return count
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=ROOT)
+    args = parser.parse_args()
+    version = check_versions(args.root)
+    links = check_links(args.root)
+    print(f"Repository checks passed: version {version}, {links} local links")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (ValueError, OSError, ET.ParseError) as error:
+        sys.exit(str(error))

.github/scripts/format_java.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Check/apply the repository's pinned Java format using JDK 17+."""
+import argparse
+import hashlib
+import os
+from pathlib import Path
+import subprocess
+import urllib.request
+
+VERSION = "1.25.2"
+SHA256 = "25157797a0a972c2290b5bc71530c4f7ad646458025e3484412a6e5a9b8c9aa6"
+URL = ("https://repo.maven.apache.org/maven2/com/google/googlejavaformat/"
+       f"google-java-format/{VERSION}/google-java-format-{VERSION}-all-deps.jar")
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--apply", action="store_true")
+    args = parser.parse_args()
+    jar = ROOT / "target/tools" / f"google-java-format-{VERSION}.jar"
+    if not jar.exists():
+        with urllib.request.urlopen(URL, timeout=60) as response:
+            data = response.read()
+        if hashlib.sha256(data).hexdigest() != SHA256:
+            raise ValueError("Formatter download checksum mismatch")
+        jar.parent.mkdir(parents=True, exist_ok=True)
+        jar.write_bytes(data)
+    if hashlib.sha256(jar.read_bytes()).hexdigest() != SHA256:
+        raise ValueError("Cached formatter checksum mismatch")
+    java = str(Path(os.environ["JAVA_HOME"]) / "bin/java") if os.environ.get("JAVA_HOME") else "java"
+    files = sorted(str(p.relative_to(ROOT)) for base in (ROOT / "src", ROOT / "examples/src")
+                   for p in base.rglob("*.java"))
+    command = [java, "-jar", str(jar)]
+    command += ["--replace"] if args.apply else ["--dry-run", "--set-exit-if-changed"]
+    subprocess.run(command + files, cwd=ROOT, check=True)
+    print(f"Java format {'applied' if args.apply else 'verified'}: {len(files)} files")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except subprocess.CalledProcessError:
+        raise SystemExit("Formatting differs; use make format on JDK 17+.")