UML Doclet

https://github.com/talsma-ict/umldoclet
Admin
UML Doclet is a Javadoc doclet that automatically generates UML diagrams from Java code and embeds...
Tokens:49,699
Snippets:331
Trust Score:7.2
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### FileUtils Usage Examples

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/util.md

Demonstrates common usage of FileUtils for calculating relative paths, ensuring directory existence, and checking file extensions.

```java
File from = new File("apidocs/com/acme/Order.html");
File to   = new File("apidocs/uml-images/Order.svg.png"); // note: extension handled separately
String rel = FileUtils.relativePath(from, to);            // "../uml-images/Order.svg.png"
FileUtils.ensureParentDir(to);
boolean svg = FileUtils.hasExtension(to, "svg");
```

--------------------------------

### TypeName and Reference usage example

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

Shows how to create TypeName and Reference objects and print their canonical forms. The TypeName example demonstrates generic type construction and array creation. The Reference example shows how to build a reference with source, arrow, target, and label, and prints its canonical representation.

```java
import nl.talsmasoftware.umldoclet.uml.*;

TypeName list = new TypeName("java.util", "List", "java.util.List",
        new TypeName("java.lang", "String", "java.lang.String"));
System.out.println(list);                            // List<String>
System.out.println(list.getQualified("::"));         // java.util::List
System.out.println(TypeName.Array.of(list));         // List<String>[]

Reference ref = new Reference(
        Reference.from("com.acme.orders.OrderLine", "*"),
        "-->",
        Reference.to("com.acme.core.Product", "0..1"),
        "product");
System.out.println(ref.canonical()); // writes: "*" com.acme.orders.OrderLine --> "0..1" com.acme.core.Product : product
```

--------------------------------

### Reference Usage Example

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

Example of creating and using Reference objects to represent UML relationships.

```APIDOC
## Reference Usage Example

### Description
Example of creating and using Reference objects to represent UML relationships.

### Code Example
```java
import nl.talsmasoftware.umldoclet.uml.*;

Reference ref = new Reference(
        Reference.from("com.acme.orders.OrderLine", "*"),
        "-->",
        Reference.to("com.acme.core.Product", "0..1"),
        "product");
System.out.println(ref.canonical()); // writes: "*" com.acme.orders.OrderLine --> "0..1" com.acme.core.Product : product
```
```

--------------------------------

### Custom Configuration implementation

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/configuration.md

Shows how to implement the Configuration interface for custom integrations. The example overrides plantumlServerUrl() to always use a local server at http://localhost:8080/ and delegates other methods to a DocletConfig.

```java
import nl.talsmasoftware.umldoclet.configuration.*;

public final class CustomConfig implements Configuration {
    // ... implement all methods, e.g. delegating to a DocletConfig for most,
    // but override plantumlServerUrl() to always use a local server:
    @Override
    public Optional<String> plantumlServerUrl() {
        return Optional.of("http://localhost:8080/");
    }
    // remaining methods omitted for brevity
}
```

--------------------------------

### TypeName Usage Example

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

Example of creating and using TypeName objects to represent generic types.

```APIDOC
## TypeName Usage Example

### Description
Example of creating and using TypeName objects to represent generic types.

### Code Example
```java
import nl.talsmasoftware.umldoclet.uml.*;

TypeName list = new TypeName("java.util", "List", "java.util.List",
        new TypeName("java.lang", "String", "java.lang.String"));
System.out.println(list);                            // List<String>
System.out.println(list.getQualified("::"));         // java.util::List
System.out.println(TypeName.Array.of(list));         // List<String>[]
```
```

--------------------------------

### Example usage of UriUtils.addPathComponent and addHttpParam

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/util.md

Demonstrates building an external type link by appending a path component and an HTTP parameter. The resulting URI is https://docs.example.com/java/java/time/LocalDate.html?is-external=true.

```java
URI base = URI.create("https://docs.example.com/java/");
URI pkg = UriUtils.addPathComponent(base, "java/time");
URI type = UriUtils.addPathComponent(pkg, "LocalDate.html");
URI linked = UriUtils.addHttpParam(type, "is-external", "true");
// https://docs.example.com/java/java/time/LocalDate.html?is-external=true
```

--------------------------------

### Error Handling Examples

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

Examples of error handling when constructing Field and Reference objects with invalid input.

```APIDOC
## Error Handling Examples

### Description
Examples of error handling when constructing Field and Reference objects with invalid input.

### Code Example
```java
// Empty member names are rejected at construction time:
try {
    new Field(type, "  ", stringType); // NPE if type/name handling... actually:
} catch (IllegalArgumentException iae) {
    // "Member name is empty."
}
// Reference types must be non-empty:
new Reference(Reference.from("a", null), "", Reference.to("b", null));
// -> IllegalArgumentException("Reference type is empty.")
```
```

--------------------------------

### Run local plantuml-server with Docker

Source: https://github.com/talsma-ict/umldoclet/blob/main/usage.md

Starts a local plantuml-server on port 8080, which can be used with the -plantumlServerUrl option (e.g., -plantumlServerUrl http://localhost:8080/). Only HTTP and HTTPS URLs are supported.

```shell
docker run -d -p 8080:8080 plantuml/plantuml-server:latest
```

--------------------------------

### Fan out writes to buffer and file writer

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/writers.md

Demonstrates using StringBufferingWriter to write to both an internal buffer and a real output writer (stdout in this example). After write and flush, the buffer contains "hello world" and all writes have also reached the delegate.

```java
import nl.talsmasoftware.umldoclet.rendering.writers.*;

// Fan out one render pass to both a string buffer and a real output:
java.io.Writer fileWriter = new java.io.OutputStreamWriter(System.out);
StringBufferingWriter buffering = new StringBufferingWriter(fileWriter);

buffering.write("hello ".toCharArray(), 0, 6);
buffering.write("world".toCharArray(), 0, 5);
buffering.flush();

StringBuffer buffer = buffering.getBuffer();  // "hello world"
// All write() calls also reached fileWriter (here: stdout).
```

--------------------------------

### Generate diagram with PlantumlGenerator.getPlantumlGenerator

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/plantuml.md

Use the static factory to obtain a generator based on configuration, then generate a diagram from PlantUML source and write it to a file. The example writes an SVG to diagram.svg using FileFormat.SVG.

```java
PlantumlGenerator generator = PlantumlGenerator.getPlantumlGenerator(config);

try (OutputStream out = Files.newOutputStream(Path.of("diagram.svg"))) {
    generator.generatePlantumlDiagramFromSource("@startuml\nclass Foo\n@enduml",
            FileFormat.SVG, out);
}
```

--------------------------------

### Visibility parsing validation example

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/configuration.md

Shows the validation behavior for visibility parsing. The parser converts "package" to a set of visibility values and logs WARNING_UNKNOWN_VISIBILITY for unrecognized values, falling back to "protected".

```java
// DocletConfig.parseVisibility: "package" -> {PACKAGE_PRIVATE, PROTECTED, PUBLIC}
// Any unrecognized value logs WARNING_UNKNOWN_VISIBILITY and falls back to "protected".
```

--------------------------------

### Implement Logger interface

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/logging.md

Example implementation of the Logger interface, e.g. for tests or custom integrations. Overrides all methods, collecting errors and throwing on ERROR_UNSUPPORTED_DELEGATE_DOCLET.

```java
import nl.talsmasoftware.umldoclet.logging.Logger;
import nl.talsmasoftware.umldoclet.logging.Message;

public final class CollectingLogger implements Logger {
    private final java.util.List<String> errors = new java.util.ArrayList<>();

    @Override public String localize(Message key, Object... args) { return key.toString(); }
    @Override public void debug(Object message, Object... args) { /* ignore */ }
    @Override public void info(Message key, Object... args) { /* ignore */ }
    @Override public void warn(Message key, Object... args) { /* ignore */ }
    @Override public void error(Message key, Object... args) {
        errors.add(key.toString());
        if (key == Message.ERROR_UNSUPPORTED_DELEGATE_DOCLET) {
            throw new IllegalArgumentException("delegation not supported");
        }
    }
}
```

--------------------------------

### FileUtils Error Handling

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/util.md

Examples of handling exceptions thrown by FileUtils methods, specifically IllegalArgumentException for invalid directory paths and IOException for stream failures.

```java
try {
    FileUtils.relativePath(new File("someFile.txt"), new File("x"));
} catch (IllegalArgumentException iae) {
    // "Not a directory: someFile.txt" — from exists but is not a directory
}
try (Reader r = FileUtils.openReaderTo("apidocs", URI.create("https://example.org/package-list"), "UTF-8")) {
    // read...
} catch (IOException ioe) {
    // network or file open failure
}
```

--------------------------------

### Handle UMLDoclet failure

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umldoclet.md

Example of a failed execution when an unsupported -delegateDoclet value is provided, resulting in a diagnostic error message.

```bash
# An unsupported -delegateDoclet value makes run() return false with:
# "Terribly sorry, we don't support \"some.other.Doclet\" yet as a delegate doclet."
javadoc -docletpath umldoclet-2.x.jar -doclet nl.talsmasoftware.umldoclet.UMLDoclet \
    -delegateDoclet some.other.Doclet src
```

--------------------------------

### PackagenameValidator class and usage example

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/javadoc-support.md

PackagenameValidator implements Predicate<String> and validates candidate Java package names against the pattern ([a-zA-Z_]+(\.[a-zA-Z_]+)*)?. null and empty strings are valid because the whole pattern is optional. The example shows that dot-separated identifiers of letters/underscores pass, while a hyphenated identifier fails.

```java
public class PackagenameValidator implements Predicate<String> {
    public PackagenameValidator();
    @Override
    public boolean test(String candidatePackageName);
}
```

```java
PackagenameValidator validator = new PackagenameValidator();
validator.test("com.acme.api");   // true
validator.test("com.acme-1");     // false
validator.test(null);             // true (empty pattern matches)
```

--------------------------------

### Catch logged errors with a custom Logger

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/errors.md

Shows how to wrap the doclet's Logger in custom integration code to catch logged errors. The example checks for Message.ERROR_UNSUPPORTED_DELEGATE_DOCLET and notes that localization can be done via key.toString(locale) plus MessageFormat. Other methods (localize, debug, info, warn) are omitted.

```java
Logger logger = new Logger() {
    @Override public void error(Message key, Object... args) {
        if (key == Message.ERROR_UNSUPPORTED_DELEGATE_DOCLET) { /* handle */ }
        /* localize via key.toString(locale) + MessageFormat */
    }
    // omit: localize, debug, info, warn
};
```

--------------------------------

### Error handling for Field and Reference

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

Demonstrates error handling for empty member names and reference types. The first example shows that constructing a Field with an empty name throws IllegalArgumentException with message "Member name is empty.". The second example shows that constructing a Reference with an empty type throws IllegalArgumentException with message "Reference type is empty.".

```java
// Empty member names are rejected at construction time:
try {
    new Field(type, "  ", stringType); // NPE if type/name handling... actually:
} catch (IllegalArgumentException iae) {
    // "Member name is empty."
}
// Reference types must be non-empty:
new Reference(Reference.from("a", null), "", Reference.to("b", null));
// -> IllegalArgumentException("Reference type is empty.")
```

--------------------------------

### Validate RemotePlantumlGenerator constructor with unsupported URL

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/plantuml.md

Constructor validation example: passing a non-http base URL like ftp://example.com/ throws IllegalArgumentException with the message "Unsupported PlantUML server base url: [ftp://example.com/]."

```java
try {
    new RemotePlantumlGenerator("ftp://example.com/");
} catch (IllegalArgumentException iae) {
    // "Unsupported PlantUML server base url: [ftp://example.com/]."
}
```

--------------------------------

### Error handling example for invalid port

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/util.md

Shows that addPathComponent throws IllegalArgumentException when the URI has an invalid port, with a message like "Could not add path component \"x\" to http://localhost:99999: ...".

```java
try {
    UriUtils.addPathComponent(URI.create("http://localhost:99999"), "x"); // invalid port
} catch (IllegalArgumentException iae) {
    // "Could not add path component \"x\" to http://localhost:99999: ..."
}
```

--------------------------------

### Initialize and use UMLFactory programmatically

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umlfactory.md

Demonstrates how to instantiate UMLFactory with a configuration and environment, then iterate through included elements to generate and render package diagrams.

```java
import jdk.javadoc.doclet.DocletEnvironment;
import nl.talsmasoftware.umldoclet.javadoc.DocletConfig;
import nl.talsmasoftware.umldoclet.javadoc.UMLFactory;

DocletEnvironment env = /* ... */;
DocletConfig config = new DocletConfig();
config.init(java.util.Locale.ENGLISH, null);
UMLFactory factory = new UMLFactory(config, env);

env.getIncludedElements().stream()
    .filter(e -> e instanceof javax.lang.model.element.PackageElement)
    .forEach(pkg -> factory.createPackageDiagram((javax.lang.model.element.PackageElement) pkg)
                           .render()); // renders .puml / images per config
```

--------------------------------

### Display UML doclet options with javadoc --help

Source: https://github.com/talsma-ict/umldoclet/blob/main/usage.md

Run this command to display all options supported by the UML doclet, including its own options in addition to those of the Standard doclet.

```bash
javadoc --help -docletpath umldoclet-2.x.jar -doclet nl.talsmasoftware.umldoclet.UMLDoclet
```

--------------------------------

### Link class signature and methods

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

The Link class extends UMLNode and provides static factory methods for creating links to types and packages, a static thread-local method to set the base directory for relative links, and an override to render the link target. The forType method resolves a relative file: URI to a package path or module path when the file exists, otherwise uses the configured external link. forPackage looks for package-summary.html, falling back to module-summary.html, then external. linkFrom sets the base directory and returns whether it changed, used by Diagram.render() to detect re-render needs. writeTo renders [[relative-or-absolute-target]] when a target exists.

```java
public class Link extends UMLNode {
    public static Link forType(Type type);
    public static Link forPackage(Namespace namespace);
    public static boolean linkFrom(String basePath);
    @Override public IndentingWriter writeTo(IndentingWriter output);
}
```

--------------------------------

### Constructor: UMLFactory(Configuration, DocletEnvironment)

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umlfactory.md

Creates a UMLFactory instance with the given configuration and doclet environment. Both arguments must be non-null.

```APIDOC
## Constructor: UMLFactory(Configuration, DocletEnvironment)

### Description
Creates a UMLFactory instance with the given configuration and doclet environment. Both arguments must be non-null.

### Method
Constructor

### Signature
```java
public UMLFactory(Configuration config, DocletEnvironment env)
```

### Parameters
- **config** (Configuration) - Required - Doclet configuration (visibility filters, exclusions, JavaBean option).
- **env** (DocletEnvironment) - Required - Javadoc environment providing type utils, element utils and inclusion checks.

### Exceptions
- **NullPointerException** - If either argument is null.

### Notes
Initializes the type name cardinality function that detects Array/Iterable/Stream/Optional cardinalities.
```

--------------------------------

### Using DocletConfig to read settings and add image formats

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/docletconfig.md

Shows how to instantiate DocletConfig, initialize it with a locale and null reporter, read effective settings like image formats and custom PlantUML directives, and add additional image formats. The output comments indicate expected values.

```java
import jdk.javadoc.doclet.Doclet;
import nl.talsmasoftware.umldoclet.javadoc.DocletConfig;
import java.util.Set;

// Option parsing happens inside the doclet; a custom configuration consumer
// can still reuse DocletConfig as a POCO and read effective settings:
DocletConfig config = new DocletConfig();
config.init(Locale.ENGLISH, null);   // reporter prints to stdout when delegate is null
System.out.println("Images: " + config.images().formats());          // [SVG]
System.out.println("Text:   " + config.customPlantumlDirectives());  // [!pragma layout smetana]
config.images().addImageFormat("png,eps");
System.out.println("Images: " + config.images().formats());          // [SVG, PNG, EPS]
```

--------------------------------

### Detecting package dependencies and generating a diagram

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/dependencies.md

Demonstrates the complete flow from scanning included elements for dependencies to generating a dependency diagram and checking for cyclic dependencies.

```java
import jdk.javadoc.doclet.DocletEnvironment;
import nl.talsmasoftware.umldoclet.configuration.Configuration;
import nl.talsmasoftware.umldoclet.javadoc.dependencies.*;
import nl.talsmasoftware.umldoclet.uml.DependencyDiagram;

Set<PackageDependency> deps = new DependenciesElementScanner(docEnv, config)
        .scan(docEnv.getIncludedElements(), null);

// Cyclic-package verification (mirrors UMLDoclet.detectPackageDependencyCycles):
if (config.onCyclicPackageDependencies() != Configuration.Action.IGNORE) {
    Set<PackageDependencyCycle> cycles = PackageDependencyCycle.detectCycles(deps);
    cycles.forEach(cycle -> config.logger().warn(Message.WARNING_PACKAGE_DEPENDENCY_CYCLES, cycle));
}

DependencyDiagram diagram = new DependencyDiagram(config, null, "package-dependencies.puml");
deps.forEach(dep -> diagram.addPackageDependency(dep.fromPackage, dep.toPackage));
```

--------------------------------

### Run UMLDoclet via command line

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umldoclet.md

Use the standard javadoc command with the -docletpath and -doclet flags to generate UML diagrams for your source code.

```bash
javadoc -sourcepath src -classpath lib -d apidocs \
    -docletpath umldoclet-2.x.jar -doclet nl.talsmasoftware.umldoclet.UMLDoclet \
    com.foobar
```

--------------------------------

### init method for DocletConfig

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/docletconfig.md

Replaces the reporter with a new LocalizedReporter using the provided locale and reporter.

```java
public void init(Locale locale, Reporter reporter)
```

--------------------------------

### Static initialization sets java.awt.headless to true

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umldoclet.md

Static initializer that sets the system property 'java.awt.headless' to 'true' to ensure AWT runs headless, allowing PlantUML to render images on servers without a display.

```java
static {
    System.setProperty("java.awt.headless", "true");
}
```

--------------------------------

### Generate diagram with RemotePlantumlGenerator and explicit URL

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/plantuml.md

Create a RemotePlantumlGenerator with an explicit server URL and generate a PNG diagram. Requires a running plantuml/plantuml-server; passing null uses the central plantuml.com (discouraged). Catches RuntimeException for server down, non-http base URL, or encoding failure.

```java
PlantumlGenerator remote = new RemotePlantumlGenerator("http://localhost:8080/");
// or null-safe: new RemotePlantumlGenerator(null) -> central plantuml.com (discouraged)

try {
    remote.generatePlantumlDiagramFromSource("@startuml\nFoo --> Bar\n@enduml", FileFormat.PNG, out);
} catch (RuntimeException rte) {
    // "Error generating diagram: ..." — server down, non-http base url, or encoding failure
}
```

--------------------------------

### Basic javadoc command-line invocation with UMLDoclet

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/configuration.md

Basic command-line invocation of UMLDoclet with javadoc, specifying UML options like -umlImageFormat, -umlImageDirectory, -umlCyclicPackageDependencies, and -umlExcludedTypeReferences.

```bash
javadoc -sourcepath src -classpath lib -d apidocs \
    -docletpath umldoclet-2.x.jar -doclet nl.talsmasoftware.umldoclet.UMLDoclet \
    -umlImageFormat svg,eps \
    -umlImageDirectory uml-images \
    -umlCyclicPackageDependencies error \
    -umlExcludedTypeReferences java.lang.Object,java.lang.Enum,com.acme.internal \
    com.foobar
```

--------------------------------

### Assemble and render a dependency diagram

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml.md

Creates a DependencyDiagram for package dependencies, adds two package dependencies, and renders it. The render() method writes nothing for empty diagrams unless renderEmptyDiagrams() is true. The toString() output shows the resulting file path (e.g., .../package-dependencies.svg).

```java
import nl.talsmasoftware.umldoclet.configuration.Configuration;
import nl.talsmasoftware.umldoclet.uml.*;

// A dependency diagram can be assembled programmatically from any sources:
DependencyDiagram diagram = new DependencyDiagram(config, "com.acme", "package-dependencies.puml");
diagram.addPackageDependency("com.acme.orders", "com.acme.core");
diagram.addPackageDependency("com.acme.core", "com.acme.util");

// render() writes nothing for empty diagrams unless renderEmptyDiagrams() is true:
diagram.render();
System.out.println(diagram.toString()); // e.g. .../package-dependencies.svg
```

--------------------------------

### Namespace class declaration

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

Public API of the Namespace class, which extends UMLNode. It renders as 'package <name> { ... }' (empty names render as 'unnamed', bug #107). The contains() method checks if a type's qualified name starts with the namespace name plus a dot, and equality is based on the package name.

```java
public class Namespace extends UMLNode {
    public final String name;
    public Namespace(UMLNode parent, String name, String moduleName);
    public Optional<String> getModuleName();
    @Override public IndentingWriter writeTo(IndentingWriter output);
    public boolean contains(TypeName typeName);
    @Override public int hashCode();
    @Override public boolean equals(Object other);
}
```

--------------------------------

### Usage in UMLDoclet.java

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/dependencies.md

Shows how to instantiate DependenciesElementScanner with the doclet environment and configuration, scan all included elements, and retrieve the module name. This is the intended entry point used by UMLDoclet.generatePackageDependencyDiagram.

```java
// Used in UMLDoclet.java:147-152:
DependenciesElementScanner scanner = new DependenciesElementScanner(docEnv, config);
Set<PackageDependency> packageDependencies = scanner.scan(docEnv.getIncludedElements(), null);
String moduleName = scanner.getModuleName();
```

--------------------------------

### LocalizedReporter constructor and interface method signatures

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/javadoc-support.md

Shows the constructor and the method signatures that LocalizedReporter implements from the Logger and Reporter interfaces. The constructor takes a DocletConfig, a Reporter delegate, and a Locale. The Logger methods are public per the Logger interface, and the Reporter methods are overrides. The debug method only logs when config.verbose is true, and info, warn, and error map to NOTE, WARNING, and ERROR diagnostic kinds respectively.

```java
LocalizedReporter(DocletConfig config, Reporter delegate, Locale locale)

// Logger interface (public per Logger)
@Override public void debug(Object key, Object... args);
@Override public void info(Message key, Object... args);
@Override public void warn(Message key, Object... args);
@Override public void error(Message key, Object... args);
@Override public String localize(Message key, Object... args);

// Reporter interface
@Override public void print(Diagnostic.Kind kind, String msg);
@Override public void print(Diagnostic.Kind kind, DocTreePath path, String msg);
@Override public void print(Diagnostic.Kind kind, Element elem, String msg);
```

--------------------------------

### Handle rendering errors with UMLFactory

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umlfactory.md

Shows how to wrap the diagram rendering process in a try-catch block to handle potential IllegalStateException errors during I/O operations.

```java
try {
    factory.createClassDiagram(typeElement).render();
} catch (IllegalStateException ise) {
    // I/O error while rendering diagram files
}
```

--------------------------------

### Log through Configuration

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/logging.md

Common usage pattern: obtain the Logger from Configuration and call info/warn methods. The localize method returns the localized string for a Message key.

```java
import nl.talsmasoftware.umldoclet.configuration.Configuration;
import nl.talsmasoftware.umldoclet.logging.Message;

config.logger().info(Message.DOCLET_VERSION);                            // "UML Doclet ... version: 2.3.3-SNAPSHOT."
config.logger().warn(Message.WARNING_UNKNOWN_VISIBILITY, "unfathomable"); // localized + MessageFormat
String text = config.logger().localize(Message.ERROR_UNSUPPORTED_DELEGATE_DOCLET, "x.Y");
```

--------------------------------

### Gradle Kotlin DSL configuration with UMLDoclet options

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/configuration.md

Gradle (Kotlin DSL) configuration for UMLDoclet, adding the dependency and setting UML-specific options via StandardJavadocDocletOptions.

```kotlin
val umlDoclet: Configuration by configurations.creating
dependencies { umlDoclet("nl.talsmasoftware:umldoclet:2.0.15") }
tasks.javadoc {
    source = sourceSets.main.get().allJava
    val options = options as StandardJavadocDocletOptions
    options.docletpath = umlDoclet.files.toList()
    options.doclet = "nl.talsmasoftware.umldoclet.UMLDoclet"
    options.addStringOption("-umlCyclicPackageDependencies", "error")
    options.addStringOption("-umlJavaBeanPropertiesAsFields", "")
}
```

--------------------------------

### HtmlPostprocessor class declaration

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/html.md

Public API of the HTML postprocessor. The constructor requires a non-null Configuration. postProcessHtml() validates the destination directory, collects diagrams, processes HTML files, and always returns true; failures are thrown as IllegalStateException.

```java
public class HtmlPostprocessor {
    public HtmlPostprocessor(Configuration config);
    public boolean postProcessHtml();
}
```

--------------------------------

### HtmlPostprocessor.postProcessHtml()

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/html.md

Documentation for the HtmlPostprocessor.postProcessHtml() method, which post-processes HTML files in the destination directory after javadoc has run.

```APIDOC
## [POST] /postProcessHtml

### Description
Post-processes the generated HTML files in the destination directory, embedding UML diagrams as objects or images. This method is called after javadoc has run and UML images have been rendered.

### Method
POST

### Endpoint
/postProcessHtml

### Parameters
#### Request Body
- **config** (Configuration) - Required - The configuration object containing the destination directory and other settings.

### Request Example
```java
import nl.talsmasoftware.umldoclet.configuration.Configuration;
import nl.talsmasoftware.umldoclet.html.HtmlPostprocessor;

// After: javadoc ran, UML images were rendered into the destination directory:
HtmlPostprocessor postprocessor = new HtmlPostprocessor(config); // config.destinationDirectory() = "apidocs"
postprocessor.postProcessHtml();
```

### Response
#### Success Response (200)
- **boolean** (boolean) - Returns `true` unconditionally on success.

#### Response Example
```java
try {
    postprocessor.postProcessHtml();
} catch (IllegalStateException ise) {
    // Unreadable destination directory or an I/O error while rewriting HTML files;
    // message contains the destination dir / offending file path.
}
```

### Error Handling
- **IllegalStateException** - Thrown when the destination directory is unreadable or an I/O error occurs while rewriting HTML files. The message contains the destination directory or the offending file path.
```

--------------------------------

### Javadoc command line syntax

Source: https://github.com/talsma-ict/umldoclet/blob/main/usage.md

The basic syntax for the javadoc command line tool.

```bash
javadoc [packages|source-files] [options][@files]
```

--------------------------------

### init method signature

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umldoclet.md

Overrides the init method to initialize the Locale and Reporter used by the doclet. Delegates to config.init(locale, reporter) first, then to super.init(...). The locale drives message localization and the reporter is the sink for all Logger output.

```java
@Override
public void init(Locale locale, Reporter reporter)
```

--------------------------------

### Gradle Kotlin DSL configuration for UML doclet

Source: https://github.com/talsma-ict/umldoclet/blob/main/usage.md

Declare the UML doclet as a configuration and configure the javadoc task to use it. Replace the version with the latest release and adjust the additional option parameters as needed.

```kotlin
val umlDoclet: Configuration by configurations.creating

dependencies {
    umlDoclet("nl.talsmasoftware:umldoclet:2.0.15")
}

configurations {
    umlDoclet
}

tasks.javadoc {
    source = sourceSets.main.get().allJava
    val docletOptions = options as StandardJavadocDocletOptions
    docletOptions.docletpath = umlDoclet.files.toList()
    docletOptions.doclet = "nl.talsmasoftware.umldoclet.UMLDoclet"
    docletOptions.addStringOption("additionalParamName", "additionalParamValue")
}
```

--------------------------------

### PackageDependency API skeleton

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/dependencies.md

Declares a final fromPackage and toPackage, with a constructor and overridden hashCode, equals, and toString.

```java
public class PackageDependency {
    public final String fromPackage;
    public final String toPackage;
    public PackageDependency(String fromPackage, String toPackage);
    @Override public int hashCode();
    @Override public boolean equals(Object other);
    @Override public String toString(); // "fromPackage->toPackage"
}
```

--------------------------------

### Post-process HTML with HtmlPostprocessor

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/html.md

Use this snippet to post-process HTML files after javadoc has run and UML images have been rendered into the destination directory. The constructor takes a Configuration object whose destinationDirectory() should point to the 'apidocs' directory. Calling postProcessHtml() rewrites the HTML files to embed the UML diagrams.

```java
import nl.talsmasoftware.umldoclet.configuration.Configuration;
import nl.talsmasoftware.umldoclet.html.HtmlPostprocessor;

// After: javadoc ran, UML images were rendered into the destination directory:
HtmlPostprocessor postprocessor = new HtmlPostprocessor(config); // config.destinationDirectory() = "apidocs"
postprocessor.postProcessHtml();
```

--------------------------------

### Parameters class declaration

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

Public API of the Parameters class, which extends UMLNode. It supports fluent construction via add() and varargs(), and only accepts Parameter children. The writeChildrenTo method renders parameters in parentheses, and the inner Parameter class handles display based on MethodConfig.ParamNames.

```java
public class Parameters extends UMLNode {
    public Parameters(UMLNode parent);
    @Override public void addChild(UMLNode child); // only Parameters' inner Parameter accepted
    public Parameters add(String name, TypeName type);
    public Parameters varargs(boolean varargs);
    @Override public boolean isEmpty(); // always false
    @Override public IndentingWriter writeTo(IndentingWriter output);
    @Override public IndentingWriter writeChildrenTo(IndentingWriter output) throws IOException;
    void replaceParameterizedType(TypeName from, TypeName to);
    public class Parameter extends UMLNode { /* package-private constructor */ }
}
```

--------------------------------

### Constructor for DocletConfig

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/docletconfig.md

Public constructor that creates the internal UMLOptions, sets the reporter to a LocalizedReporter, and restores default field values.

```java
public DocletConfig()
```

--------------------------------

### Observing ExternalLink resolution and LocalizedReporter behavior

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/javadoc-support.md

Shows how to observe ExternalLink resolution via Configuration.resolveExternalLinkToType and LocalizedReporter behavior via config.logger().warn(). The -linkoffline option appends 'LocalDate.html' plus '?is-external=true' for http(s) targets. Quiet config suppresses note-level info() calls but never warnings/errors.

```java
// ExternalLink resolution can be observed through Configuration:
Optional<URI> link = config.resolveExternalLinkToType("java.time", "LocalDate");
// -> resolves via -linkoffline java.time <url>/package-list, appending
//    "LocalDate.html" plus "?is-external=true" for http(s) targets.

// LocalizedReporter behavior is reached through the Logger returned by config.logger():
config.logger().warn(Message.WARNING_PACKAGE_DEPENDENCY_CYCLES, " - a > b > a");
// quiet config suppresses the note-level info() calls but never warnings/errors.
```

--------------------------------

### Handling package dependency cycle errors

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/dependencies.md

Shows how to catch an IllegalArgumentException when attempting to create a PackageDependencyCycle that does not close the loop.

```java
try {
    new PackageDependencyCycle(deps.toArray(new PackageDependency[0]));
} catch (IllegalArgumentException iae) {
    // "Not a dependency cycle: ..." — the chain does not close the loop.
}
```

--------------------------------

### Gradle Groovy DSL configuration for UML doclet

Source: https://github.com/talsma-ict/umldoclet/blob/main/usage.md

Declare the UML doclet as a configuration and configure the javadoc task to use it. Replace the version '2.x' with the latest release and adjust the additional option parameters as needed.

```groovy
apply plugin: 'java'

configurations {
    umlDoclet
}

dependencies {
    umlDoclet "nl.talsmasoftware:umldoclet:2.x"
}

javadoc {
    source = sourceSets.main.allJava
    options.docletpath = configurations.umlDoclet.files.asType(List)
    options.doclet = "nl.talsmasoftware.umldoclet.UMLDoclet"
    options.addStringOption "additionalParamName", "additionalParamValue"
}
```

--------------------------------

### Diagram class API declaration

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml.md

Shows the public and protected API of the abstract Diagram class, including the constructor, writeTo, writeCustomDirectives, getConfiguration, getPlantUmlFile, render, and toString methods. The constructor requires a non-null Configuration and creates a PlantumlGenerator via strategy selection.

```java
public abstract class Diagram extends UMLNode {
    protected Diagram(Configuration config);
    @Override public IndentingWriter writeTo(IndentingWriter output);
    protected IndentingWriter writeCustomDirectives(List<String> customDirectives, IndentingWriter output) throws IOException;
    @Override public Configuration getConfiguration();
    protected abstract File getPlantUmlFile();
    public void render();
    @Override public String toString();
}
```

--------------------------------

### run method signature

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umldoclet.md

Overrides the run method, the main doclet functionality. Returns true on success, false on failure. It logs copyrights, resolves the delegate doclet, generates and renders diagrams, and post-processes HTML.

```java
@Override
public boolean run(DocletEnvironment environment)
```

--------------------------------

### showMembers method for DocletConfig

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/docletconfig.md

Applies the parsed visibility set to both fieldConfig.visibilities and methodConfig.visibilities.

```java
void showMembers(String value)
```

--------------------------------

### UmlPostProcessors.javaBeanPropertiesAsFieldsPostProcessor

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml-members.md

Returns a consumer that runs JavaBeanProperty.detectFrom(type).forEach(JavaBeanProperty::replaceGetterAndSetterByField).

```APIDOC
## UmlPostProcessors.javaBeanPropertiesAsFieldsPostProcessor

### Description
Returns a consumer that runs JavaBeanProperty.detectFrom(type).forEach(JavaBeanProperty::replaceGetterAndSetterByField).

### Method
public Consumer<Type> javaBeanPropertiesAsFieldsPostProcessor()

### Returns
Consumer<Type> - A consumer that processes types by replacing getter and setter methods with fields for detected JavaBean properties.
```

--------------------------------

### ImageConfig interface definition

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/configuration.md

Defines the configuration for image output, including the target directory and supported file formats.

```java
public interface ImageConfig {
    enum Format {
        SVG(".svg"), SVG_IMG(".svg"), PNG(".png"), EPS(".eps");
        public final String fileExtension;
        Format(String fileExtension) { this.fileExtension = fileExtension; }
    }
    Optional<String> directory();
    Collection<Format> formats();
}
```

--------------------------------

### Maven maven-javadoc-plugin configuration with UMLDoclet

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/configuration.md

Maven maven-javadoc-plugin configuration for UMLDoclet, specifying the doclet artifact and additional UML options like -umlImageFormat and -umlRenderEmptyDiagrams.

```xml
<configuration>
    <doclet>nl.talsmasoftware.umldoclet.UMLDoclet</doclet>
    <docletArtifact>
        <groupId>nl.talsmasoftware</groupId>
        <artifactId>umldoclet</artifactId>
        <version>2.x</version>
    </docletArtifact>
    <additionalOptions>
        <additionalOption>-umlImageFormat=png</additionalOption>
        <additionalOption>-umlRenderEmptyDiagrams=true</additionalOption>
    </additionalOptions>
</configuration>
```

--------------------------------

### FileUtils Class Definition

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/util.md

The FileUtils class provides static methods for file and path manipulation. It includes a private constructor that throws an UnsupportedOperationException to prevent instantiation.

```java
public final class FileUtils {
    private FileUtils(); // throws UnsupportedOperationException
    public static String relativePath(File from, File to);
    public static File ensureParentDir(File file);
    public static String fileNameOf(String path);
    public static String withoutExtension(String path);
    public static Reader openReaderTo(String basedir, URI uri, String charsetName) throws IOException;
    public static boolean hasExtension(Object file, String extension);
}
```

--------------------------------

### Configure maven-javadoc-plugin for UML Doclet

Source: https://github.com/talsma-ict/umldoclet/wiki/UML-Doclet-usage

Add this plugin configuration to your Maven project to enable UML diagram generation during the JavaDoc build process.

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.3</version>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                    <configuration>
                        <doclet>nl.talsmasoftware.umldoclet.UMLDoclet</doclet>
                        <docletArtifact>
                            <groupId>nl.talsmasoftware</groupId>
                            <artifactId>umldoclet</artifactId>
                            <version>...</version>
                        </docletArtifact>
                        <additionalParam>
                            ...
                        </additionalParam>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

--------------------------------

### Configuration interface definition

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/configuration.md

The core interface defining the contract for UML rendering configuration, including settings for PlantUML servers, file output, and diagram generation.

```java
public interface Configuration {
    enum Action { IGNORE, WARN, ERROR }
    Optional<String> plantumlServerUrl();
    @Deprecated(since = "2.0.21", forRemoval = true)
    Optional<String> delegateDocletName();
    Logger logger();
    Indentation indentation();
    String destinationDirectory();
    boolean renderPumlFile();
    ImageConfig images();
    FieldConfig fields();
    MethodConfig methods();
    List<String> excludedTypeReferences();
    List<String> excludedPackageDependencies();
    Action onCyclicPackageDependencies();
    Optional<URI> resolveExternalLinkToType(String packageName, String type);
    List<String> customPlantumlDirectives();
    Charset umlCharset();
    Charset htmlCharset();
    boolean excludePackageDiagrams();
    boolean excludePackageDependencies();
    boolean excludeClassDiagrams();
    boolean renderEmptyDiagrams();
}
```

--------------------------------

### UMLFactory constructor signature

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/umlfactory.md

Shows the constructor signature. Requires both arguments non-null, otherwise throws NullPointerException via requireNonNull. Initializes typeNameWithCardinality using TypeNameWithCardinality.function(env.getTypeUtils()).

```java
public UMLFactory(Configuration config, DocletEnvironment env)
```

--------------------------------

### RemotePlantumlGenerator class

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/plantuml.md

RemotePlantumlGenerator is an alternative PlantumlGenerator that sends PlantUML source to a remote server. The constructor accepts a baseUrl (null defaults to "https://www.plantuml.com/plantuml/"), throws IllegalArgumentException for non-http(s) URLs, and appends a trailing slash if missing. The generatePlantumlDiagramFromSource method encodes the source, requests `${baseUrl}<format-lowercase>/<encoded>`, and streams the response; any IOException or RuntimeException is wrapped in a RuntimeException "Error generating diagram: ...". The -umlTimeout option sets GlobalConfig.TIMEOUT_MS which the PlantUML client honors.

```java
@SuppressFBWarnings(value = "URLCONNECTION_SSRF_FD", justification = "We only allow http(s) urls.")
public class RemotePlantumlGenerator implements PlantumlGenerator {
    public static final Pattern HTTP_URLS = Pattern.compile("^https?://");
    public RemotePlantumlGenerator(final String baseUrl);
    @Override public void generatePlantumlDiagramFromSource(String plantumlSource, FileFormat format, OutputStream out);
}
```

--------------------------------

### generatePlantumlDiagramFromSource(String, FileFormat, OutputStream)

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/plantuml.md

Renders a PlantUML diagram from the given source text into the specified image format and writes the binary image data to the provided output stream. The format values used by the doclet are SVG, PNG, and EPS.

```APIDOC
## generatePlantumlDiagramFromSource(String, FileFormat, OutputStream)

### Description
Renders a PlantUML diagram from the given source text into the specified image format and writes the binary image data to the provided output stream. The format values used by the doclet are SVG, PNG, and EPS.

### Method
void generatePlantumlDiagramFromSource(String plantumlSource, FileFormat format, OutputStream out) throws IOException

### Parameters
- **plantumlSource** (String) - Required - The complete PlantUML source text, starting with @startuml.
- **format** (net.sourceforge.plantuml.FileFormat) - Required - The desired image format (SVG, PNG, EPS).
- **out** (java.io.OutputStream) - Required - The output stream that receives the binary image data.

### Throws
- **IOException** - If an I/O error occurs during rendering or writing.

### Example
```java
generator.generatePlantumlDiagramFromSource(source, FileFormat.SVG, outputStream);
```
```

--------------------------------

### UMLNode public methods

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/uml.md

Public methods of the abstract UMLNode class, which is the base for all renderable nodes in the UML model. These methods allow traversal and manipulation of the node tree.

```APIDOC
## UMLNode

### Description
Base of every renderable node. UMLNode objects form a tree (parent/children) and render themselves onto an IndentingWriter.

### Methods

#### getChildren()
- **Returns**: `List<UMLNode>` - Unmodifiable view of the children.

#### getChildren(Class<T> type)
- **Parameters**: `type` (Class<T>) - Required, non-null - The type to filter and cast children to.
- **Returns**: `List<T>` - Children filtered/cast to the given type.

#### addChild(UMLNode child)
- **Parameters**: `child` (UMLNode) - The node to attach.
- **Returns**: `void` - Appends and calls `child.setParent(this)`.

#### removeChildren(Predicate<? super UMLNode> condition)
- **Parameters**: `condition` (Predicate) - Children matching are removed.
- **Returns**: `boolean` - `true` if at least one child was removed.

#### isEmpty()
- **Returns**: `boolean` - `true` if all children are empty (overridden by leaf nodes).

#### getConfiguration()
- **Returns**: `Configuration` - Configuration of the nearest `Diagram` ancestor; **throws** `IllegalStateException` ("Cannot obtain configuration!") when there is no diagram ancestor.

#### writeChildrenTo(IndentingWriter output)
- **Parameters**: `output` (IndentingWriter) - Indenting writer.
- **Returns**: `IndentingWriter` - Writes every child; `throws IOException`.

#### toString()
- **Returns**: `String` - Renders the node into a string using the configured indentation (fallback `Indentation.TABS` when no configuration is reachable).
```

--------------------------------

### StringBufferingWriter class skeleton

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/writers.md

Shows the public API of StringBufferingWriter. It delegates to super(new StringWriter(), delegate), making position 0 the internal buffer and position 1 the real delegate. getBuffer() returns the internal StringBuffer.

```java
public class StringBufferingWriter extends DelegatingWriter {
    public StringBufferingWriter(Writer delegate);
    public StringBuffer getBuffer();
    @Override public String toString();
}
```

--------------------------------

### PackageDependencyCycle

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/dependencies.md

A list of PackageDependency objects that form a cycle. Provides a static method to detect cycles from a collection of dependencies.

```APIDOC
## PackageDependencyCycle

### Description
A list of PackageDependency objects that form a cycle. Provides a static method to detect cycles from a collection of dependencies.

### Constructor
`public PackageDependencyCycle(PackageDependency... dependencies)`

### Parameters
- **dependencies** (PackageDependency...) - Required - Ordered dependencies where each dependencies[i].toPackage equals dependencies[i+1].fromPackage (mod length). Throws IllegalArgumentException if empty or if the chain does not loop.

### Static Methods
- `public static Set<PackageDependencyCycle> detectCycles(Iterable<PackageDependency> dependencies)` - Grows dependency chains (skipping chains that would repeat a dependency) and returns every chain whose last toPackage equals its first fromPackage, as a LinkedHashSet<PackageDependencyCycle>.

### Instance Methods
- `public PackageDependency get(int index)` - Returns the dependency at the specified index.
- `public int size()` - Returns the number of dependencies in the cycle.
- `public String toString()` - Returns a string representation in the format "a > b > c > a".
```

--------------------------------

### FileUtils.ensureParentDir(File file)

Source: https://github.com/talsma-ict/umldoclet/blob/main/_autodocs/api-reference/util.md

Creates the parent directory of the given file if it does not exist. Returns the same file instance. Throws IllegalStateException if the directory cannot be created.

```APIDOC
## FileUtils.ensureParentDir(File file)

### Description
Creates the parent directory of the specified file if it is missing. Returns the same file instance.

### Method
static

### Signature
public static File ensureParentDir(File file)

### Parameters
- **file** (File) - Required - The target file whose parent directory should be ensured.

### Returns
- **File** - The same file instance.

### Exceptions
- **IllegalStateException** - If the parent directory cannot be created. Message: "Can't create directory ..."

### Example
```java
FileUtils.ensureParentDir(to);
```
```
Tokens:
Raw