# NamedEntity

## Purpose

`NamedEntity` appears to provide a shared base for domain objects that need a human-readable `name` in addition to the inherited database identifier from `BaseEntity`. It centralizes the `name` field, validation rule, and string representation so subclasses such as `Pet`, `PetType`, and `Specialty` can reuse the same behavior instead of duplicating it.

## Design

This class is a **JPA mapped superclass** and a small domain-model building block. It is not meant to be instantiated on its own; instead, it supplies common persistence mapping and simple JavaBean accessors to concrete entity types.

Because it extends `BaseEntity`, it also participates in the shared entity identity pattern used throughout the model layer.

## Key Methods

### `getName() -> String`

Returns the current value of the `name` property.

- **Parameters:** none
- **Returns:** the current `String` value of the entity name, or `null` if it has not been assigned yet
- **Side effects:** none

This method is the primary read path for the shared display name across subclasses.

### `setName(String name) -> void`

Assigns a new value to the `name` property.

- **Parameters:** `name` - the name to store on the entity
- **Returns:** nothing
- **Side effects:** mutates the in-memory state of the entity instance

The field is annotated with `@NotBlank`, so this setter may accept a value that later fails validation if it is `null`, empty, or only whitespace.

### `toString() -> String`

Returns a textual representation of the entity based on its name.

- **Parameters:** none
- **Returns:** the current name, or `"<null>"` when `getName()` returns `null`
- **Side effects:** none

This appears to be a defensive implementation meant to avoid returning `null` from `toString()`. That makes logging and debugging safer, especially when the entity is only partially populated.

## Relationships

`NamedEntity` sits in the model inheritance chain between `BaseEntity` and several concrete domain types.

- **Depends on `BaseEntity`** for the shared identifier (`id`) and persistence identity behavior.
- **Used by `Pet`**, `PetType`, and `Specialty` as a superclass so they inherit the common `name` field and methods.
- **Annotated with `@MappedSuperclass`** so its mapping is inherited by subclasses rather than stored in a separate table.

### Relationship diagram

```mermaid
flowchart TD
BaseEntity["BaseEntity"]
NamedEntity["NamedEntity"]
Pet["Pet"]
PetType["PetType"]
Specialty["Specialty"]
BaseEntity --> NamedEntity
NamedEntity --> Pet
NamedEntity --> PetType
NamedEntity --> Specialty
```

## Usage Example

This class appears to be used as a reusable base for simple reference-data or display-oriented entities.

Typical usage looks like this:

1. A concrete subclass such as `PetType` inherits `name` from `NamedEntity`.
2. Application code assigns the value with `setName(String)`.
3. UI code, logging, or debugging calls `getName()` or `toString()` to display the entity.

For example, a service might create a new `PetType`, call `setName("dog")`, and later rely on `toString()` to produce a readable label in logs or selection lists.

## Notes for Developers

- `NamedEntity` is **stateful and mutable**. `setName(String)` changes the object in place.
- The class is **not immutable** and should not be assumed thread-safe.
- `@NotBlank` means the `name` is expected to be present and non-empty at validation time, even though the getter and setter themselves do not enforce that rule.
- `toString()` is intentionally null-safe and returns `"<null>"` rather than propagating a `null` reference.
- Because it is a `@MappedSuperclass`, there is no separate entity table for `NamedEntity`; its fields are inherited by subclasses.
- The class is best understood as a small shared domain abstraction rather than a rich behavior object.