#1875: BeanHelper.java

Utilidad integral de introspección y reflexión de JavaBeans. Infraestructura central para la capa de integración ORM/Wicket de ProjectForge — proporciona resolución de nombres de propiedades a partir de métodos getter/setter, búsqueda de métodos getter/setter con amplio almacenamiento en caché (cinco cachés internas para rendimiento), descubrimiento de anotaciones en campos, acceso a propiedades anidadas/indexadas, copia de propiedades con detección de diferencias e instanciación de objetos basada en reflexión. Ampliamente utilizado en todos los módulos de ProjectForge para ordenación de listas en Wicket, enlace de formularios y conversión DO a DTO.

Importaciones

• org.apache.commons.lang3.ArrayUtils — Concatenación de arreglos para recolección de campos/métodos en la jerarquía de clases
• org.apache.commons.lang3.StringUtils — Manipulación de cadenas (capitalizar, descapitalizar, dividir)
• java.lang.annotation.Annotation — Descubrimiento de anotaciones en campos
• java.lang.reflect.* — API de reflexión central de Java: Field, Method, Constructor, Modifier, Array, InvocationTargetException
• java.util.* — Colecciones, iteradores, mapas hash para almacenamiento en caché
• org.slf4j.Logger — Registro de errores para fallos de reflexión

Arquitectura de almacenamiento en caché interno

BeanHelper utiliza cinco cachés sincronizadas estáticas para evitar llamadas de reflexión repetidas, que son costosas en Java. Esto es crítico para las páginas de listas de Wicket donde se llama a BeanHelper para cada celda en una tabla de datos ordenable.

Caché	Clave	Valor	Beneficio
declaredFieldsCache	Class	Field[]	Evita volver a escanear la jerarquía de clases en busca de campos
declaredMethodsCache	Class	Method[]	Evita volver a escanear la jerarquía de clases en busca de métodos
declaredFieldAnnotationsCache	"clase:nombrecampo"	Annotation[]	Evita volver a resolver campos anotados (crítico para la ordenación de columnas en Wicket)
getterMethodsCache	"clase:nombrecampo"	Method	Evita volver a buscar métodos getter
declaredGetterMethodsCache	String	Method[]	Declarado pero parece no usarse en el código proporcionado — puede poblarse en otro lugar

Operaciones clave

Resolución de nombres de propiedades

• determinePropertyName(Method) — Elimina el prefijo get/set/is/has y convierte a minúscula el primer carácter
• determineGetter(Class, nombrecampo, soloGetterPublico) — Encuentra el método getter (getX(), isX() para booleanos, hasX() para booleanos), maneja métodos puente (no devuelve métodos sintéticos puente)
• determineSetter(Class, nombrecampo) — Encuentra el setter con un solo parámetro
• determinePropertyType(Class, nombrecampo) — Obtiene el tipo de retorno del getter (tipo de propiedad)

Acceso a anotaciones

getDeclaredAnnotations(Class, nombrecampo) soporta rutas de propiedades anidadas (separadas por puntos, ej., "direccion.ciudad.nombre") recorriendo la cadena de campos a través de la reflexión para encontrar las anotaciones del campo terminal. Esto es esencial para las tablas de datos de Wicket que muestran propiedades de objetos anidados con columnas ordenables.

Acceso a propiedades (anidadas + indexadas)

• getProperty(Object, String) — Invoca el getter en un bean
• setProperty(Object, String, Object) — Invoca el setter
• getIndexedProperty(Object, "prop[3]") — Soporta acceso indexado a colecciones/arreglos
• getNestedProperty(Object, "a.b.c") — Recorre la ruta de propiedades separadas por puntos, manejando nulos de forma segura (devuelve null si algún intermedio es nulo)

Copia de propiedades (copyProperties)

Copia las propiedades especificadas del objeto origen al destino, devolviendo true si alguna propiedad realmente cambió. Soporta:

• Comparación de colecciones: Verificación de igualdad elemento por elemento (sensible al orden, usando iteradores)
• Comparación de arreglos: Usa Arrays.equals()
• Comparación escalar: Usa Objects.equals() (seguro para nulos)
• Modo WhitespaceEqualsNull: Trata cadenas vacías/ausentes como equivalentes (solo copia si ambas no están vacías y son diferentes)

Utilidades de reflexión

• getAllDeclaredFields(Class) — Devuelve todos los campos, incluidos los heredados, recorriendo la cadena de superclases
• getAllDeclaredMethods(Class) — Devuelve todos los métodos, incluidos los heredados
• getDeclaredPropertyFields(Class) — Devuelve solo campos no transitorios, no estáticos y no finales (propiedades persistentes reales)
• getFieldValue(Object, Class/String, nombrecampo) — Lee el valor del campo mediante reflexión (setAccessible para campos privados)
• newInstance(Class, ...) — Múltiples sobrecargas para construcción reflexiva de objetos con varias firmas de constructores
• invoke(Object, Method, args) — Invocación genérica de métodos con manejo de errores

Característica de modo de prueba

La bandera TEST_MODE (controlada por enterTestMode()/exitTestMode()) suprime el registro de errores durante la ejecución de pruebas. Esto permite que las pruebas intenten operaciones de reflexión que se espera que fallen sin contaminar los registros de prueba con trazas de pila. Los métodos logInstantiationException() respetan esta bandera.

Decisiones de diseño

1. Almacenamiento en caché agresivo: Existen cinco cachés porque la reflexión es lenta y se llama a BeanHelper en rutas críticas (representación y ordenación de tablas de datos de Wicket)
2. Filtrado de métodos puente: determineGetter() omite los métodos puente (métodos sintéticos creados por el compilador para la eliminación de tipos genéricos) para devolver el método real implementado
3. Recorrido seguro para nulos: getNestedProperty() devuelve null en cualquier punto de la cadena donde un valor intermedio sea nulo, en lugar de lanzar NPE
4. Accesibilidad del constructor: newInstance() llama a constructor.setAccessible(true) para instanciar clases con constructores privados
5. Sin biblioteca de beans externa: A pesar de depender de commons-beanutils en la compilación de Gradle, BeanHelper implementa su propia resolución de propiedades en lugar de usar Apache BeanUtils directamente — probablemente para control de rendimiento y almacenamiento en caché

868d6abb7 2025 -> 2026
63081666f Encabezados de archivos fuente: 2024 -> 2025.
a73905c14 Corrección de errores tipográficos en directorios projectforge*/ Encontrados mediante codespell
694987647 Migración en progreso... (todas las pruebas de todos los paquetes: OK).
ae50b2522 BeanHelper.getProperty ahora soporta propiedades anidadas usando simplemente new PropertyUtils.
b6092df09 Copyright 2023 -> 2024
ab45d51fa Copyright 2001-2022 -> 2001-2023.
0203e3261 AbstractListPage: consultas de larga duración: el cambio de orden de clasificación muestra la lista de resultados sin el botón de búsqueda. BeanHelper: muchas cachés para una clasificación más rápida en las listas de resultados de Wicket.