"""UKO Layer 3: Java-specific vocabulary (``uko-java:``).

Extends the Layer 2 Object-Oriented paradigm (``uko-oo:``) with
Java-specific semantic refinements:

Classes:
- ``JavaClass``             -- Java class (extends ``uko-oo:Class``)
- ``JavaInterface``         -- Java interface (extends ``uko-oo:Interface``)
- ``JavaMethod``            -- Java method (extends ``uko-oo:Method``)
- ``JavaAnnotation``        -- Java annotation entry
- ``JavaCheckedException``  -- Checked exception declaration

Java extends at the SIGNATURES level with:
- Package visibility
- ``final``/``abstract``/``sealed`` modifiers
- Annotation lists (``@Override``, ``@Deprecated``)
- Checked exceptions

Based on ``docs/specification.md`` ~lines 44405-44420.
"""

from __future__ import annotations

from cleveragents.acms.uko.vocabulary import (
    OO_EFFECTIVE_LEVELS,
    UKO_CODE_IRI,
    UKO_OO_IRI,
    Layer2Dependency,
    UKOClass,
    UKOProperty,
    UKOVocabulary,
    build_detail_level_map,
)

__all__: list[str] = [
    "JAVA_DETAIL_LEVELS",
    "JAVA_VOCABULARY",
    "JavaAnnotation",
    "JavaCheckedException",
    "JavaClass",
    "JavaInterface",
    "JavaMethod",
]

# ---------------------------------------------------------------------------
# Namespace constants
# ---------------------------------------------------------------------------

UKO_JAVA_IRI = "https://cleveragents.ai/ontology/uko/java#"
UKO_JAVA_PREFIX = "uko-java:"


# ---------------------------------------------------------------------------
# OWL Class definitions
# ---------------------------------------------------------------------------

JavaClass = UKOClass(
    uri=f"{UKO_JAVA_IRI}JavaClass",
    label="JavaClass",
    comment=(
        "A Java class definition — extends uko-oo:Class. "
        "Includes final/abstract/sealed modifiers and annotations."
    ),
    subclass_of=(f"{UKO_OO_IRI}Class",),
)

JavaInterface = UKOClass(
    uri=f"{UKO_JAVA_IRI}JavaInterface",
    label="JavaInterface",
    comment=(
        "A Java interface — extends uko-oo:Interface. "
        "Includes sealed permits and default method support."
    ),
    subclass_of=(f"{UKO_OO_IRI}Interface",),
)

JavaMethod = UKOClass(
    uri=f"{UKO_JAVA_IRI}JavaMethod",
    label="JavaMethod",
    comment=(
        "A Java method — extends uko-oo:Method. "
        "Includes annotations, checked exceptions, and modifiers."
    ),
    subclass_of=(f"{UKO_OO_IRI}Method",),
)

# NOTE: Models annotation *application* (@Override on a method), not
# annotation *definition* (@interface Override). TypeDefinition is a
# partial fit because Java annotations ARE types (@interface).
JavaAnnotation = UKOClass(
    uri=f"{UKO_JAVA_IRI}JavaAnnotation",
    label="JavaAnnotation",
    comment=(
        "A Java annotation entry (@Override, @Deprecated, custom). "
        "Records annotation name and parameters."
    ),
    subclass_of=(f"{UKO_CODE_IRI}TypeDefinition",),
)

# NOTE: subclasses uko-code:TypeDefinition as a pragmatic approximation.
# Throws-clause entries reference existing exception types, not define new ones.
# Pending uko-code:Declaration base class (see #576 review).
JavaCheckedException = UKOClass(
    uri=f"{UKO_JAVA_IRI}JavaCheckedException",
    label="JavaCheckedException",
    comment=(
        "A checked exception declaration in a method's throws clause. "
        "Records the exception class and any conditions."
    ),
    subclass_of=(f"{UKO_CODE_IRI}TypeDefinition",),
)


# ---------------------------------------------------------------------------
# OWL Property definitions
# ---------------------------------------------------------------------------

_java_package_visibility = UKOProperty(
    uri=f"{UKO_JAVA_IRI}packageVisibility",
    label="packageVisibility",
    comment=(
        "Package-level visibility modifier: 'public', 'protected', "
        "'package-private' (default), 'private'."
    ),
    domain=(
        f"{UKO_JAVA_IRI}JavaClass",
        f"{UKO_JAVA_IRI}JavaInterface",
        f"{UKO_JAVA_IRI}JavaMethod",
    ),
    range_uri="xsd:string",
    is_object_property=False,
)

_java_is_final = UKOProperty(
    uri=f"{UKO_JAVA_IRI}isFinal",
    label="isFinal",
    comment="Whether this class/method is marked 'final'.",
    domain=(f"{UKO_JAVA_IRI}JavaClass", f"{UKO_JAVA_IRI}JavaMethod"),
    range_uri="xsd:boolean",
    is_object_property=False,
)

_java_is_abstract = UKOProperty(
    uri=f"{UKO_JAVA_IRI}isAbstract",
    label="isAbstract",
    comment="Whether this class/method is marked 'abstract'.",
    domain=(f"{UKO_JAVA_IRI}JavaClass", f"{UKO_JAVA_IRI}JavaMethod"),
    range_uri="xsd:boolean",
    is_object_property=False,
)

_java_is_sealed = UKOProperty(
    uri=f"{UKO_JAVA_IRI}isSealed",
    label="isSealed",
    comment="Whether this class/interface is marked 'sealed'.",
    domain=(f"{UKO_JAVA_IRI}JavaClass", f"{UKO_JAVA_IRI}JavaInterface"),
    range_uri="xsd:boolean",
    is_object_property=False,
)

_java_has_annotation = UKOProperty(
    uri=f"{UKO_JAVA_IRI}hasAnnotation",
    label="hasAnnotation",
    comment="Links a class/method to its Java annotations.",
    domain=(
        f"{UKO_JAVA_IRI}JavaClass",
        f"{UKO_JAVA_IRI}JavaInterface",
        f"{UKO_JAVA_IRI}JavaMethod",
    ),
    range_uri=f"{UKO_JAVA_IRI}JavaAnnotation",
    is_object_property=True,
)

_java_annotation_name = UKOProperty(
    uri=f"{UKO_JAVA_IRI}annotationName",
    label="annotationName",
    comment=("The fully-qualified name of the annotation (e.g. 'java.lang.Override')."),
    domain=(f"{UKO_JAVA_IRI}JavaAnnotation",),
    range_uri="xsd:string",
    is_object_property=False,
)

_java_throws_exception = UKOProperty(
    uri=f"{UKO_JAVA_IRI}throwsException",
    label="throwsException",
    comment="Links a method to its checked exception declarations.",
    domain=(f"{UKO_JAVA_IRI}JavaMethod",),
    range_uri=f"{UKO_JAVA_IRI}JavaCheckedException",
    is_object_property=True,
)

_java_exception_class = UKOProperty(
    uri=f"{UKO_JAVA_IRI}exceptionClass",
    label="exceptionClass",
    comment="Fully-qualified class name of the checked exception.",
    domain=(f"{UKO_JAVA_IRI}JavaCheckedException",),
    range_uri="xsd:string",
    is_object_property=False,
)


# ---------------------------------------------------------------------------
# Layer 2 dependencies
# ---------------------------------------------------------------------------

_JAVA_LAYER2_DEPS = (
    Layer2Dependency(
        uri=f"{UKO_OO_IRI}Class",
        prefix="uko-oo:",
        description="OO class (JavaClass extends this).",
    ),
    Layer2Dependency(
        uri=f"{UKO_OO_IRI}Interface",
        prefix="uko-oo:",
        description="OO interface (JavaInterface extends this).",
    ),
    Layer2Dependency(
        uri=f"{UKO_OO_IRI}Method",
        prefix="uko-oo:",
        description="OO method (JavaMethod extends this).",
    ),
    Layer2Dependency(
        uri=f"{UKO_CODE_IRI}TypeDefinition",
        prefix="uko-code:",
        layer=1,
        description=(
            "General type definition (JavaAnnotation and "
            "JavaCheckedException extend this)."
        ),
    ),
)


# ---------------------------------------------------------------------------
# DetailLevelMap: extends uko-oo: at SIGNATURES level
# ---------------------------------------------------------------------------

# Java extends at SIGNATURES level — enriches the content at
# SIGNATURES depth with package visibility, final/abstract/sealed,
# annotations, checked exceptions.  No new depth levels are inserted.
_JAVA_INSERTIONS: tuple[tuple[str, int], ...] = ()

JAVA_DETAIL_LEVELS: tuple[tuple[str, int], ...] = build_detail_level_map(
    OO_EFFECTIVE_LEVELS, _JAVA_INSERTIONS
)


# ---------------------------------------------------------------------------
# Vocabulary definition
# ---------------------------------------------------------------------------

JAVA_VOCABULARY = UKOVocabulary(
    namespace=UKO_JAVA_IRI,
    prefix=UKO_JAVA_PREFIX,
    layer=3,
    label="Java Technology Vocabulary",
    comment=(
        "Layer 3 technology-specific vocabulary for Java. "
        "Extends uko-oo: with package visibility, "
        "final/abstract/sealed modifiers, annotation lists "
        "(@Override, @Deprecated), and checked exceptions."
    ),
    parent_prefixes=("uko-oo:",),
    classes=(
        JavaClass,
        JavaInterface,
        JavaMethod,
        JavaAnnotation,
        JavaCheckedException,
    ),
    properties=(
        _java_package_visibility,
        _java_is_final,
        _java_is_abstract,
        _java_is_sealed,
        _java_has_annotation,
        _java_annotation_name,
        _java_throws_exception,
        _java_exception_class,
    ),
    layer2_dependencies=_JAVA_LAYER2_DEPS,
    inserted_levels=(),
)
