#832: AddressbookDO.kt

Architecture & Position in the System

Class Hierarchy

BaseDO
 └─ DefaultBaseDO
     └─ BaseUserGroupRightsDO        ← provides owner, user-rights, group-rights fields
         └─ AddressbookDO             ← this class
             also implements DisplayNameCapable

BaseUserGroupRightsDO is the critical parent: it adds columns for owner (a PFUserDO reference), along with the rights-assignment fields that let an address book be shared with individual users or entire groups. This parent-class design means every address book automatically participates in ProjectForge's multi-tenant visibility model.

JPA Mapping

Fields

Inherited Fields (from BaseUserGroupRightsDO)

These fields are defined in the parent class and inherited automatically; they are not redeclared in AddressbookDO but are present in the database table:

• owner — actually overridden here (see above)
• User-rights collection: which individual users have read/write access
• Group-rights collection: which groups have read/write access
• Standard BaseDO fields: id, created, lastUpdate, deleted

Hibernate Search Integration

The @Indexed marker, combined with @FullTextField on title and description, makes this entity discoverable through Hibernate Search. The HibernateSearchUsersGroupsTypeBinder (referenced in the source but not shown in the abridged content) bridges the user/group rights into the Lucene index so that search results respect the same visibility constraints as database queries — a user searching for address books will only see results they have permission to access.

DisplayNameCapable & UI Integration

The displayName property returns "$title", providing a consistent label for drop-downs, breadcrumbs, and history entries. The @PropertyInfo annotations feed into ProjectForge's automatic form-rendering system, which generates input fields, validation messages (e.g. "Title is required"), and column headers from the i18nKey lookups.

Equality Semantics

The class defines custom hashCode() and equals() methods. When the entity has been persisted (ID is non-null), equality is based on the database ID — two AddressbookDO instances with the same ID are considered equal. When the ID is null (a transient, not-yet-saved object), equality falls back to object identity (===). This is the standard Hibernate-recommended pattern that avoids problems with proxy objects and collections.

Git History

Design Rationale

Why extend BaseUserGroupRightsDO?

Address books are shared resources — a user creates one and may grant read or write access to other users or groups. The BaseUserGroupRightsDO superclass provides a uniform rights model (owner + per-user grants + per-group grants) that is reused across many ProjectForge entity types (address books, calendars, task lists, etc.). This avoids duplicating the same access-control schema in every entity and ensures consistent behaviour in the DAO and UI layers.

Why eager-load owner?

Address books are almost always displayed with their owner's name. If owner were lazily loaded, every list page would trigger N+1 additional queries. Eager fetching is a deliberate performance trade-off: it adds a JOIN to every address-book query but eliminates the N+1 problem in the common case. The @JsonSerialize(using = IdOnlySerializer::class) annotation ensures that when the entity is serialised to JSON (e.g. for REST APIs), only the owner's numeric ID is emitted, preventing deep object-graph serialisation and circular references.

Why Hibernate Search indexing?

ProjectForge provides a global search feature that spans multiple entity types. By annotating AddressbookDO with @Indexed and @FullTextField, the Lucene index is kept in sync with the database via Hibernate Search's automatic indexing on save/update/delete. The HibernateSearchUsersGroupsTypeBinder further ensures that access-control metadata is embedded in the search index, so the same user who cannot see an address book in a list view cannot find it via full-text search either — a critical security property.

Why implement DisplayNameCapable?

This interface (providing displayName: String) is a ProjectForge convention used by history/audit logging, UI breadcrumbs, and selection drop-downs. By implementing it, AddressbookDO plugs into these subsystems without every consumer needing to know that the display name is simply the title field.

Why Constants.LENGTH_TITLE instead of hard-coded lengths?

ProjectForge uses a shared Constants class to define standard column lengths. This ensures that all entities using "title" or "description" fields have consistent database column sizes, simplifying schema management and avoiding subtle bugs where one entity's title is 255 characters but another's is 1000.