<!--
  Copyright (c) 2009-2026 ASN Lab
  All rights reserved.
-->

# ASN.1 Java Compiler Guide

The ASN.1 Java Compiler (`asnjc`) generates Java source code from ASN.1
modules. Generated types are placed in packages derived from module names
and work with the `asnrt` Java runtime library for encoding and decoding.

## Compiler Options

| Field                        | Type    | Default      | Description |
|------------------------------|---------|--------------|-------------|
| `output-folder`              | string  | `"java"`     | Output directory for generated Java sources. |
| `mapping.integer`            | ENUM    | `automatic`  | See [Integer Mapping](#integer-mapping). |
| `mapping.enumerated`         | ENUM    | `enum-type`  | See [Enumerated Mapping](#enumerated-mapping). |
| `mapping.real`               | ENUM    | `double`     | `automatic`, `float`, `double`. |
| `mapping.list`               | ENUM    | `automatic`  | See [List Mapping](#list-mapping). |
| `lower-case-package`         | BOOLEAN | TRUE         | Convert module names to lower case for Java package names. |
| `package-prefix`             | string  | `""`         | Prefix prepended to every generated package name. |
| `generate.setters-getters`   | BOOLEAN | FALSE        | Generate JavaBean-style setters and getters. |
| `generate.clones`            | BOOLEAN | FALSE        | Generate `clone()` methods. |
| `generate.equals`            | BOOLEAN | FALSE        | Generate `equals()` and `hashCode()` methods. |
| `generate.prints`            | BOOLEAN | FALSE        | Generate `toString()` methods. |

## Integer Mapping

Controls how ASN.1 INTEGER is mapped to Java types:

| Option         | Java type |
|----------------|-----------|
| `automatic`    | `BigInteger` when unconstrained; smallest `long`/`int`/`short` that fits otherwise. |
| `integer`      | `long` (legacy alias for `long`). |
| `long`         | `long`. |
| `xlong`        | `long`. |
| `big-integer`  | `BigInteger`. |

## Real Mapping

| Option      | Java type |
|-------------|-----------|
| `automatic` | `double`. |
| `float`     | `float`. |
| `double`    | `double`. |

## Enumerated Mapping

Controls how ASN.1 ENUMERATED is represented:

| Option       | Description |
|--------------|-------------|
| `automatic`  | `enum-type` for extensible ENUMERATED, `enums` for non-extensible. |
| `enum-type`  | A Java class with `public static final` named constants. Supports extensibility through the runtime type system. |
| `enums`      | A Java `enum`. Simpler but does not support extension additions. |
| `singleton`  | A singleton class with named constants. |

## List Mapping

Controls how ASN.1 SEQUENCE OF / SET OF is represented:

| Option        | Java type |
|---------------|-----------|
| `automatic`   | `Vector` for CHOICE/SET lists, `ArrayList` otherwise. |
| `array`       | Java array (`T[]`). |
| `array-list`  | `ArrayList<T>`. |
| `linked-list` | `LinkedList<T>`. |
| `vector`      | `Vector<T>`. |

## Project Configuration Example

```asn1
compilers {
    {
        language "java",
        options {
            output-folder "java",
            mapping {
                integer automatic,
                enumerated automatic,
                real double,
                list automatic
            },
            lower-case-package TRUE,
            package-prefix "com.example",
            generate {
                setters-getters FALSE,
                clones FALSE,
                equals FALSE,
                prints FALSE
            }
        }
    }
}
```

## Runtime Integration

Add the `asnrt` JAR to your project's classpath. The generated code depends on
`org.asnlab.asndt.runtime` types for encoding and decoding. Encoding is done
through the generated type's `encode` / `decode` methods, which accept an
`EncodingRules` constant (BER, DER, UPER, APER, OER, XER, JER).

## Generated Output

With `output "build"` and `java.output-folder "java"`, output is written
under `build/java/` with a package structure derived from each ASN.1 module
name. For example, module `MyModule` with `package-prefix "com.example"`
produces classes under `com/example/mymodule/`.
