Update from upstream repo aspose-pdf/Aspose.Pdf-for-Java@master

.github/instructions/docs-style.instructions.md

@@ -0,0 +1,35 @@
+---
+description: "Use when editing Markdown documentation to keep structure, tone, and links consistent across project docs."
+name: "Docs Markdown Style"
+applyTo: "{README.md,docs/**/*.md}"
+---
+# Docs Markdown Style
+
+## Scope and Priority
+
+- Treat this as a cross-doc style baseline.
+- When editing [README.md](../../README.md), also follow [readme-maintenance.instructions.md](./readme-maintenance.instructions.md) for technical accuracy.
+
+## Structure
+
+- Keep heading hierarchy sequential (`##` after `#`, avoid skipping levels).
+- Prefer short, scannable sections with clear titles.
+- Use tables only when they improve comparison; otherwise prefer bullet lists.
+
+## Writing Style
+
+- Keep language concise, factual, and task-oriented.
+- Avoid marketing-heavy rewrites unless explicitly requested.
+- Preserve existing terminology for product, package, and feature names.
+
+## Links and Examples
+
+- Prefer repository-relative links for local files and stable canonical links for external docs.
+- Keep code snippets short and directly relevant to the section.
+- When possible, point to runnable examples in `examples/documentation/src/main/java/com/aspose/pdf/examples` instead of embedding long snippets.
+
+## Safe Editing Boundaries
+
+- Avoid broad formatting-only rewrites that hide meaningful diffs.
+- Keep changes scoped to the requested doc area.
+- Do not change support or legal links unless explicitly requested.

.github/instructions/java-examples.instructions.md

@@ -0,0 +1,47 @@
+---
+description: "Use when creating or modifying Java example classes for Aspose.PDF examples, including runners, category orchestration, file path usage, and sample-data folder alignment."
+name: "Java Examples Conventions"
+applyTo: "examples/documentation/src/main/java/com/aspose/pdf/examples/**/*.java"
+---
+# Java Examples Conventions
+
+## Follow Existing Structure
+
+- Keep classes in package paths under examples/documentation/src/main/java/com/aspose/pdf/examples.
+- Use final utility-style classes with a private constructor for example groups.
+- Keep the category runner pattern:
+  - runAllExamples(String licensePath)
+  - main(String[] args)
+
+## Required Runtime Flow
+
+1. Resolve or pass through license path with ExampleConfig.
+2. Call ExampleConfig.setLicense(licensePath).
+3. Initialize category data directories with ExampleConfig.initializeDataDir("category_name").
+4. Wrap each example operation with ExampleRunner.run("Operation name", () -> ...).
+
+## File and Data Path Rules
+
+- Use java.nio.file.Path for local file handling.
+- Convert to String only where Aspose APIs require it.
+- Keep sample-data category names aligned with code intent:
+  - examples/documentation/sample-data/<category>/input
+  - examples/documentation/sample-data/<category>/output
+
+## Resource Safety
+
+- Always close com.aspose.pdf.Document instances.
+- Prefer try-with-resources where possible; otherwise use try/finally.
+
+## Agent Guardrails
+
+- Keep examples small and runnable as standalone methods.
+- Do not add new frameworks or dependencies unless the task explicitly requires it.
+- Preserve existing console output style used by ExampleRunner.
+- If adding a new category runner, ensure examples/documentation/tools/run-all-examples scripts are updated when appropriate.
+
+## References
+
+- [AGENTS.md](../../AGENTS.md)
+- [ExampleConfig.java](../../examples/documentation/src/main/java/com/aspose/pdf/examples/ExampleConfig.java)
+- [ExampleRunner.java](../../examples/documentation/src/main/java/com/aspose/pdf/examples/ExampleRunner.java)

.github/instructions/readme-maintenance.instructions.md

@@ -0,0 +1,26 @@
+---
+description: "Use when editing the repository README to keep technical claims and quick-start guidance aligned with the codebase."
+name: "README Maintenance Conventions"
+applyTo: "README.md"
+---
+# README Maintenance Conventions
+
+## Accuracy First
+
+- Verify version statements against [pom.xml](../../pom.xml) before updating text.
+- Prefer repository-truth commands (`mvn clean compile`, runner commands, and scripts in [examples/documentation/tools](../../examples/documentation/tools)).
+- If a statement conflicts with source-of-truth files, update the README to match code and build configuration.
+
+## Keep Documentation Lean
+
+- Link to canonical references instead of duplicating long instructions:
+  - [Aspose.PDF Java Docs](https://docs.aspose.com/pdf/java/)
+  - [API Reference](https://apireference.aspose.com/pdf/java)
+  - [AGENTS.md](../../AGENTS.md)
+- Keep examples concise and representative; avoid large code blocks unless requested.
+
+## Consistency Rules
+
+- Keep naming and paths consistent with repository layout (for example `examples/documentation/src/main/java/com/aspose/pdf/examples` and `examples/documentation/sample-data`).
+- Preserve existing support/product links unless the task explicitly asks for link changes.
+- Use Markdown tables and headings with the existing README style; avoid unrelated formatting rewrites.

.github/prompts/add-example-category.prompt.md

@@ -0,0 +1,40 @@
+---
+description: "Create a new Aspose.PDF Java example category with package, runner class, operation stubs, sample-data folders, and optional script registration. Use when adding a new feature area."
+name: "Add Example Category"
+argument-hint: "Category package name + sample-data folder name + operation list"
+agent: "agent"
+---
+Create a new example category in this repository.
+
+Input format:
+- category package name: lower-case package segment, for example workingwithforms
+- sample-data folder name: snake_case folder, for example working_with_forms
+- optional operation names: comma-separated, for example CreateFormExample, FillFormExample
+- optional register-runner: yes or no
+
+Tasks:
+1. Inspect existing patterns in:
+   - [AGENTS.md](../../AGENTS.md)
+   - [ExampleConfig.java](../../examples/documentation/src/main/java/com/aspose/pdf/examples/ExampleConfig.java)
+   - [ExampleRunner.java](../../examples/documentation/src/main/java/com/aspose/pdf/examples/ExampleRunner.java)
+   - [BasicOperationsExamples.java](../../examples/documentation/src/main/java/com/aspose/pdf/examples/basicoperations/BasicOperationsExamples.java)
+2. Create package folder under examples/documentation/src/main/java/com/aspose/pdf/examples/<category package name>.
+3. Create a category runner class named in PascalCase with Examples suffix.
+4. Add operation example classes (if provided), each with:
+   - static example methods
+   - runAllExamples(String licensePath)
+   - main(String[] args)
+5. Ensure runner and operation classes use:
+   - ExampleConfig.setLicense
+   - ExampleConfig.initializeDataDir("<sample-data folder name>")
+   - ExampleRunner.run for each operation
+6. Create sample-data directories:
+   - examples/documentation/sample-data/<sample-data folder name>/input
+   - examples/documentation/sample-data/<sample-data folder name>/output
+7. If register-runner is yes, add the new runner to examples/documentation/tools scripts that execute all runners.
+8. Run a compile check and report any failures.
+
+Output:
+- List of created or modified files
+- Any assumptions made
+- Follow-up actions needed for missing input sample PDFs

.github/prompts/update-readme.prompt.md

@@ -0,0 +1,25 @@
+---
+description: "Audit and update README.md for technical accuracy and command consistency with this repository. Use when asked to refresh, fix, or modernize README content."
+name: "Update README"
+argument-hint: "Scope of changes, for example: Java version section, quick-start commands, or links"
+agent: "agent"
+---
+Update [README.md](../../README.md) with the requested scope while keeping the document aligned with repository truth.
+
+Tasks:
+1. Read and compare:
+   - [README.md](../../README.md)
+   - [pom.xml](../../pom.xml)
+   - [examples/documentation/pom.xml](../../examples/documentation/pom.xml)
+   - [AGENTS.md](../../AGENTS.md)
+   - [examples/documentation/tools/run-all-examples.ps1](../../examples/documentation/tools/run-all-examples.ps1)
+   - [examples/documentation/tools/run-all-examples.sh](../../examples/documentation/tools/run-all-examples.sh)
+2. Correct outdated technical claims (versions, commands, paths) to match current files.
+3. Preserve existing README structure and product messaging unless the prompt explicitly asks for restructuring.
+4. Prefer links to canonical docs over long embedded explanations.
+5. Keep edits focused to the requested scope and avoid unrelated rewrites.
+
+Output:
+- Summary of what changed
+- Any assumptions made
+- Follow-up items that need repository maintainer confirmation

.github/skills/example-validation/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: example-validation
+description: 'Validate Aspose.PDF Java example changes by compiling, running example runners, and checking expected output files. Use when editing example classes, adding new categories, or reviewing regressions.'
+argument-hint: 'Runner class, license path, expected output files'
+user-invocable: true
+---
+# Example Validation Workflow
+
+Use this skill after changing Java examples to confirm they still compile and produce expected output files.
+
+## When to Use
+
+- After modifying files in examples/documentation/src/main/java/com/aspose/pdf/examples
+- After adding a new category runner or operation class
+- Before opening a PR for examples changes
+
+## Inputs
+
+- Runner class (optional): fully qualified class name, for example com.aspose.pdf.examples.basicoperations.BasicOperationsExamples
+- License path (optional): absolute path to Aspose.PDF license file
+- Expected outputs (optional): output filenames relative to examples/documentation/sample-data/<category>/output
+
+## Procedure
+
+1. Confirm Java toolchain and compile:
+   - mvn -f examples/documentation/pom.xml clean compile
+2. Run the selected runner if provided:
+   - cd examples/documentation
+   - mvn -DskipTests exec:java "-Dexec.mainClass=<runner class>"
+3. If no runner is provided, run the repository-wide script:
+   - Windows PowerShell:
+     - examples/documentation/tools/run-all-examples.ps1
+     - examples/documentation/tools/run-all-examples.ps1 -LicensePath "<license path>"
+   - Bash:
+     - examples/documentation/tools/run-all-examples.sh
+     - examples/documentation/tools/run-all-examples.sh --license <license path>
+4. Check output artifacts:
+   - Verify expected files exist under examples/documentation/sample-data/<category>/output
+   - Flag missing files and list them explicitly
+5. Summarize validation status:
+   - compile: pass or fail
+   - run: pass or fail
+   - outputs: pass or fail
+   - blockers and next actions
+
+## Validation Notes
+
+- JDK 25 or newer is required; builds fail on older versions.
+- If no license is provided, examples may run in evaluation mode.
+- initializeDataDir creates directories automatically, so missing folders alone do not prove success.
+
+## References
+
+- [AGENTS.md](../../../AGENTS.md)
+- [pom.xml](../../../pom.xml)
+- [examples/documentation/pom.xml](../../../examples/documentation/pom.xml)
+- [run-all-examples.ps1](../../../examples/documentation/tools/run-all-examples.ps1)
+- [run-all-examples.sh](../../../examples/documentation/tools/run-all-examples.sh)

.gitignore

@@ -37,3 +37,4 @@ Out/
 Out*/
 *.lic
 Data/*Out*
+*out*

.java-version

@@ -0,0 +1 @@
+25

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "java.configuration.updateBuildConfiguration": "interactive"
+}

AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md
+
+This file helps AI coding agents work effectively in this repository.
+
+## Scope and Goal
+
+- Repository type: Java Maven examples and plugin integrations for Aspose.PDF.
+- Primary goal: add and maintain runnable documentation example code under `examples/documentation/src/main/java/com/aspose/pdf/examples` and matching sample data under `examples/documentation/sample-data`.
+- Plugin integrations live under `plugins/<plugin-name>` and should keep plugin-specific code, sample data, tools, and README content isolated.
+
+## Environment and Build
+
+- Required Java version: JDK 25 or newer (enforced by Maven Enforcer in `examples/documentation/pom.xml`).
+- Build all Maven modules from the repository root: `mvn clean compile`.
+- Build documentation examples only: `mvn -f examples/documentation/pom.xml clean compile`.
+- Run one example runner:
+  - `cd examples/documentation`
+  - `mvn -DskipTests exec:java "-Dexec.mainClass=com.aspose.pdf.examples.basicoperations.BasicOperationsExamples"`
+- Run all registered runners:
+  - PowerShell: `examples/documentation/tools/run-all-examples.ps1 [-LicensePath "C:\path\Aspose.PDF.lic"] [-StopOnFailure]`
+  - Bash: `examples/documentation/tools/run-all-examples.sh [--license /path/Aspose.PDF.lic] [--stop-on-failure]`
+
+## License Handling
+
+- License can be provided in this precedence order (see `ExampleConfig`):
+  - CLI argument: `--license=/path/to/Aspose.PDF.lic`
+  - JVM property: `-Daspose.pdf.license=/path/to/Aspose.PDF.lic`
+  - Environment variable: `ASPOSE_PDF_LICENSE`
+- If no license is provided, examples still run but may operate in evaluation mode.
+
+## Code Layout and Patterns
+
+- Shared helpers:
+  - `ExampleConfig`: license resolution + sample-data directory initialization.
+  - `ExampleDataDirs`: input/output path helper.
+  - `ExampleRunner`: wraps examples and logs success/failure per operation.
+- Current implemented category: `basicoperations`.
+- Naming convention:
+  - Category runner class: `XxxExamples` with `runAllExamples(String licensePath)` and `main(String[] args)`.
+  - Operation classes follow the same `*Examples` suffix.
+- When adding a new category runner, register its fully qualified main class in both `examples/documentation/tools/run-all-examples.ps1` (`$exampleClasses`) and `examples/documentation/tools/run-all-examples.sh` (`EXAMPLE_CLASSES`); unregistered runners will not be executed by the run-all scripts.
+- Typical flow inside `runAllExamples`:
+  1. `ExampleConfig.setLicense(licensePath)`
+  2. `ExampleConfig.initializeDataDir("category_name")`
+  3. `ExampleRunner.run("Operation name", () -> ...)` per operation
+
+## Data Directory Convention
+
+- Keep source and sample-data category names aligned:
+  - Java package: `...examples.<categorypackage>`
+  - Sample data folder: `examples/documentation/sample-data/<category_folder>/input` and `examples/documentation/sample-data/<category_folder>/output`
+- `initializeDataDir` creates missing directories automatically.
+
+## Editing Guidance for Agents
+
+- Keep examples simple, runnable, and focused on one feature each.
+- Prefer `Path` (`java.nio.file.Path`) for file paths and convert to string only at Aspose API boundaries.
+- Always close `Document` objects (try-with-resources or try/finally).
+- Preserve existing output logging style (`Success:` / `Failed:`) via `ExampleRunner`.
+- Do not add heavyweight frameworks; keep dependencies minimal and Maven-based.
+
+## README Update Guidance
+
+- For `README.md` changes, keep runtime/version claims synchronized with `pom.xml` (for example Java and dependency versions).
+- Keep quick-start commands runnable and aligned with repository scripts in `examples/documentation/tools/`.
+- Prefer linking to canonical docs (`docs.aspose.com`, API reference, and repository files) instead of duplicating long procedural content.
+- Preserve existing product positioning and support/resource links unless the task explicitly requests branding or navigation changes.
+- If README examples are changed, prefer short snippets and point to runnable examples under `examples/documentation/src/main/java/com/aspose/pdf/examples`.
+
+## Known Pitfalls
+
+- JDK older than 25 will fail build due to the enforcer rule.
+- Many category directories are placeholders; treat a category as a placeholder only when `examples/documentation/src/main/java/com/aspose/pdf/examples/<category>` contains no `.java` files, and check for file presence before assuming examples already exist there.
+- Input files are assumed to exist in `examples/documentation/sample-data/<category>/input`; add missing sample files when introducing new examples.
+- Before submitting, verify that every input path referenced by new example code has a corresponding committed file under `examples/documentation/sample-data/<category>/input`. If a sample file is generated programmatically instead, document that in the example's Javadoc.
+
+## Useful References
+
+- Project overview: [README.md](README.md)
+- Build/tooling: [pom.xml](pom.xml), [examples/documentation/pom.xml](examples/documentation/pom.xml)
+- Scripted execution: [examples/documentation/tools/run-all-examples.ps1](examples/documentation/tools/run-all-examples.ps1), [examples/documentation/tools/run-all-examples.sh](examples/documentation/tools/run-all-examples.sh)
+- Docs style instruction: [.github/instructions/docs-style.instructions.md](.github/instructions/docs-style.instructions.md)
+- README-focused instruction: [.github/instructions/readme-maintenance.instructions.md](.github/instructions/readme-maintenance.instructions.md)
+- README-focused prompt: [.github/prompts/update-readme.prompt.md](.github/prompts/update-readme.prompt.md)
+- Aspose docs: <https://docs.aspose.com/pdf/java/>
+- API reference: <https://apireference.aspose.com/pdf/java>