#1875: BeanHelper.java

Комплексная утилита для интроспекции и рефлексии JavaBeans. Базовая инфраструктура для уровня интеграции ORM/Wicket в ProjectForge — обеспечивает разрешение имён свойств из методов getter/setter, поиск методов getter/setter с обширным кэшированием (пять внутренних кэшей для производительности), обнаружение аннотаций полей, доступ к вложенным/индексированным свойствам, копирование свойств с обнаружением различий и создание объектов на основе рефлексии. Широко используется во всех модулях ProjectForge для сортировки списков Wicket, привязки форм и преобразования DO в DTO.

Импорты

• org.apache.commons.lang3.ArrayUtils — Конкатенация массивов для сбора полей/методов по иерархии классов
• org.apache.commons.lang3.StringUtils — Манипуляции со строками (capitalize, uncapitalize, split)
• java.lang.annotation.Annotation — Обнаружение аннотаций на полях
• java.lang.reflect.* — Основной API рефлексии Java: Field, Method, Constructor, Modifier, Array, InvocationTargetException
• java.util.* — Коллекции, итераторы, хэш-карты для кэширования
• org.slf4j.Logger — Логирование ошибок при сбоях рефлексии

Внутренняя архитектура кэширования

BeanHelper использует пять статических синхронизированных кэшей для избежания повторных вызовов рефлексии, которые дороги в Java. Это критически важно для страниц списков Wicket, где BeanHelper вызывается для каждой ячейки в сортируемой таблице данных.

Кэш	Ключ	Значение	Преимущество
declaredFieldsCache	Class	Field[]	Избегает повторного сканирования иерархии классов для полей
declaredMethodsCache	Class	Method[]	Избегает повторного сканирования иерархии классов для методов
declaredFieldAnnotationsCache	"класс:имяполя"	Annotation[]	Избегает повторного разрешения аннотированных полей (критично для сортировки колонок Wicket)
getterMethodsCache	"класс:имяполя"	Method	Избегает повторного поиска методов getter
declaredGetterMethodsCache	String	Method[]	Объявлен, но, похоже, не используется в предоставленном коде — может заполняться в другом месте

Ключевые операции

Разрешение имени свойства

• determinePropertyName(Method) — Удаляет префикс get/set/is/has и приводит первый символ к нижнему регистру
• determineGetter(Class, имяполя, onlyPublicGetter) — Находит метод getter (getX(), isX() для boolean, hasX() для boolean), обрабатывает bridge-методы (не возвращает синтетические bridge-методы)
• determineSetter(Class, имяполя) — Находит setter с одним параметром
• determinePropertyType(Class, имяполя) — Получает возвращаемый тип getter (тип свойства)

Доступ к аннотациям

getDeclaredAnnotations(Class, имяполя) поддерживает пути к вложенным свойствам (разделённые точкой, например, "address.city.name") путём обхода цепочки полей через рефлексию для поиска аннотаций конечного поля. Это необходимо для таблиц данных Wicket, которые отображают вложенные свойства объектов с сортируемыми колонками.

Доступ к свойствам (вложенные + индексированные)

• getProperty(Object, String) — Вызывает getter для bean
• setProperty(Object, String, Object) — Вызывает setter
• getIndexedProperty(Object, "prop[3]") — Поддерживает индексированный доступ к коллекциям/массивам
• getNestedProperty(Object, "a.b.c") — Обходит путь свойства, разделённый точками, корректно обрабатывая null (возвращает null, если любой промежуточный элемент равен null)

Копирование свойств (copyProperties)

Копирует указанные свойства из исходного объекта в целевой, возвращая true, если какое-либо свойство фактически изменилось. Поддерживает:

• Сравнение коллекций: Поэлементная проверка равенства (с учётом порядка, с использованием итераторов)
• Сравнение массивов: Использует Arrays.equals()
• Сравнение скаляров: Использует Objects.equals() (безопасно для null)
• Режим WhitespaceEqualsNull: Считает пустые/отсутствующие строки эквивалентными (копирует только если обе строки непустые и разные)

Утилиты рефлексии

• getAllDeclaredFields(Class) — Возвращает все поля, включая унаследованные, обходя цепочку суперклассов
• getAllDeclaredMethods(Class) — Возвращает все методы, включая унаследованные
• getDeclaredPropertyFields(Class) — Возвращает только нетранзиентные, нестатические, нефинальные поля (фактические постоянные свойства)
• getFieldValue(Object, Class/String, имяполя) — Читает значение поля через рефлексию (setAccessible для приватных полей)
• newInstance(Class, ...) — Несколько перегрузок для рефлексивного создания объектов с различными сигнатурами конструкторов
• invoke(Object, Method, args) — Общий вызов метода с обработкой ошибок

Функция тестового режима

Флаг TEST_MODE (управляется enterTestMode()/exitTestMode()) подавляет логирование ошибок во время выполнения тестов. Это позволяет тестам выполнять операции рефлексии, которые, как ожидается, завершатся ошибкой, не засоряя журналы тестов трассировками стека. Методы logInstantiationException() учитывают этот флаг.

Проектные решения

1. Агрессивное кэширование: Существует пять кэшей, потому что рефлексия медленна, а BeanHelper вызывается на горячих путях (рендеринг и сортировка таблиц данных Wicket)
2. Фильтрация bridge-методов: determineGetter() пропускает bridge-методы (синтетические методы, создаваемые компилятором для стирания обобщённых типов), чтобы вернуть фактически реализованный метод
3. Безопасный обход null: getNestedProperty() возвращает null в любой точке цепочки, где промежуточное значение равно null, вместо выброса NPE
4. Доступность конструкторов: newInstance() вызывает constructor.setAccessible(true) для создания экземпляров классов с приватными конструкторами
5. Отсутствие внешней библиотеки bean: Несмотря на зависимость от commons-beanutils в сборке Gradle, BeanHelper реализует собственное разрешение свойств вместо прямого использования Apache BeanUtils — вероятно, для контроля производительности и кэширования

868d6abb7 2025 -> 2026
63081666f Заголовки исходных файлов: 2024 -> 2025.
a73905c14 Исправление опечаток в каталогах projectforge*/ Найдено с помощью codespell
694987647 Миграция в процессе... (все тесты всех пакетов: OK).
ae50b2522 BeanHelper.getProperty теперь поддерживает вложенные свойства с помощью нового PropertyUtils.
b6092df09 Авторское право 2023 -> 2024
ab45d51fa Авторское право 2001-2022 -> 2001-2023.
0203e3261 AbstractListPage: длительные запросы: изменение порядка сортировки показывает список результатов без кнопки поиска. BeanHelper: множество кэшей для более быстрой сортировки в списках результатов Wicket.