[Enhancement] Split ClassUtils into per-concern classes and de-duplicate the cache-location switch

[nkuprins]

Search before asking

• I searched in the issues and found nothing similar.

Motivation

fesod-sheet/src/main/java/org/apache/fesod/sheet/util/ClassUtils.java is ~600 lines and holds three unrelated responsibilities in one class. It was really hard to navigate when tracing how a column or a cell format is resolved. Concretely:

1. Column-layout resolution - which declared fields become spreadsheet columns, and in what
order:

• declaredFields (L285), doDeclaredFields (L307), resortField (L394),
  buildSortedAllFieldMap (L449), declaredOneField (L472), FieldCacheKey (L572)
• caches: FIELD_CACHE (L76), FIELD_THREAD_LOCAL (L80)

2. Per-field formatting resolution - converter, date/number format and style, merged from the
head class and the row's actual runtime class:

• declaredExcelContentProperty (L114), getExcelContentProperty (L126),
  doGetExcelContentProperty (L149), combineExcelContentProperty (L168), buildKey (L193),
  declaredFieldContentMap (L197), doDeclaredFieldContentMap (L224), ContentPropertyKey (L565)
• caches: CONTENT_CACHE (L97), CONTENT_THREAD_LOCAL (L103), CLASS_CONTENT_CACHE (L85),
  CLASS_CONTENT_THREAD_LOCAL (L91)

3. getAllInterfaces (L530/L547) - a generic reflection helper unrelated to either of the
above. It is a trimmed copy of org.apache.commons.lang3.ClassUtils.getAllInterfaces, and its
only caller is FieldUtils.getField (FieldUtils.java:165).

On top of that, concerns (1) and (2) each cache their result per CacheLocationEnum
(THREAD_LOCAL / MEMORY / NONE), and the switch that dispatches on the cache location is
repeated three times - L128-146, L202-221 and L286-304.
The three differ only in the map and key types. The branch order, the lazy ThreadLocal init block and the
default: throw new UnsupportedOperationException("unsupported enum") are identical.

Solution

Split the file four ways within org.apache.fesod.sheet.util, as a pure move - no logic changes:

1. FieldCacheUtils - column-layout resolution: declaredFields, doDeclaredFields, resortField, buildSortedAllFieldMap, declaredOneField, FieldCacheKey, plus its two cache fields.

2. ExcelContentPropertyUtils - per-field formatting resolution: declaredExcelContentProperty, getExcelContentProperty, doGetExcelContentProperty, combineExcelContentProperty, buildKey, declaredFieldContentMap, doDeclaredFieldContentMap, ContentPropertyKey, plus its four cache fields.

3. CacheLocationUtils - one generic method replacing the three switches:

   static <K, V> V computeIfAbsent(
           CacheLocationEnum cacheLocation,
           ThreadLocal<Map<K, V>> threadLocalCache,
           Map<K, V> memoryCache,
           Supplier<K> keySupplier,
           Supplier<V> valueSupplier) { ... }

4. ClassUtils - trimmed to getAllInterfaces plus removeThreadLocalCache, kept as a public entry point so its two callers don't change.

The two clusters are almost disjoint: neither calls into the other and they share no private helper. The one exception is removeThreadLocalCache (L591), which clears all three ThreadLocals and so spans both clusters. It has two production callers (ExcelAnalyserImpl.java:298, WriteContextImpl.java:567), so it stays on ClassUtils as a delegate to a package-private clear method on each of the two new classes - that keeps both call sites untouched. Apart from that one method, the partition needs no duplication and no new coupling.

Alternatives

No response

Anything else?

One caveat. ClassUtils is a public utility class - some things to be moved are public static. If refactoring takes place, not sure if @Deprecated would be needed instead of just removing.

Are you willing to submit a PR?

• I'm willing to submit a PR!

[delei]

One caveat. ClassUtils is a public utility class - some things to be moved are public static. If refactoring takes place, not sure if @deprecated would be needed instead of just removing.

It should be noted that the utility class ClassUtils may also be called extensively by downstream users, rather than merely within fesod itself.
If it is split off, additional documentation may be required, and a transition period spanning several minor release versions may be necessary, or consideration may need to be given to compatibility.

Using @Deprecated and providing a compatible method is a viable solution.

[bengbengbalabalabeng]

I completely agree with the proposed refactoring to split ClassUtils by responsibility and optimize the caching logic. Breaking down the monolithic ClassUtils class delivers huge gains in code readability, maintainability, and separation of concerns.

Here are a few thoughts and technical suggestions regarding the refactoring design for further discussion:

1. Keep existing public methods on ClassUtils as a unified Facade API that delegates directly to the new internal resolvers underneath, without marking them as @Deprecated. Here is why:

• ClassUtils serves as a well-established entry point across the framework. Preserving its existing public method signatures ensures zero breaking changes for downstream users.
• ClassUtils naturally functions as a public-facing facade. Encapsulating complex parsing and caching details inside specialized resolvers while leaving ClassUtils solely responsible for routing is a clean, standard architectural design. There is no need to force users to migrate to internal classes.

2. The newly extracted classes should be scoped as package-private (accessible only to ClassUtils and other package-internal components) to avoid polluting the public API surface. Proposed naming:

• SheetHeadFieldResolver (equivalent to FieldCacheUtils): Responsible for column layout, field mappings (FieldCache), and index/order calculations for sheet headers.
• SheetContentPropertyResolver (equivalent to ExcelContentPropertyUtils): Responsible for cell content formatting (ExcelContentProperty), converters, and styling.

3. To eliminate duplicated branches and procedural boilerplate, we can replace the repetitive switch statements with an interface-based strategy pattern combined with an EnumMap:

Cache Strategy:

public interface MetadataCacheStrategy<K, V> {

    V get(K key, Function<K, V> mappingFunction);

    void clear();

    // In-memory cache
    class MemoryCache<K, V> implements MetadataCacheStrategy<K, V> {
        private final Map<K, V> cache;

        public MemoryCache() {
            this(new ConcurrentHashMap<>());
        }

        public MemoryCache(Map<K, V> cache) {
            this.cache = cache;
        }

        @Override
        public V get(K key, Function<K, V> mappingFunction) {
            return cache.computeIfAbsent(key, mappingFunction);
        }

        @Override
        public void clear() {
            cache.clear();
        }
    }

    // ThreadLocal cache
    class ThreadLocalCache<K, V> implements MetadataCacheStrategy<K, V> {
        // ......
    }

    // No-op cache
    class NoOpCache<K, V> implements MetadataCacheStrategy<K, V> {
        // ......
    }
}

Usage Example (taking SheetHeadFieldResolver as an example):

// Package-private
final class SheetHeadFieldResolver {

    private static final Map<CacheLocationEnum, MetadataCacheStrategy<FieldCacheKey, FieldCache>> CACHE_STRATEGIES;

    static {
        Map<CacheLocationEnum, MetadataCacheStrategy<FieldCacheKey, FieldCache>> map = new EnumMap<>(CacheLocationEnum.class);
        map.put(CacheLocationEnum.MEMORY, new MetadataCacheStrategy.MemoryCache<>());
        map.put(CacheLocationEnum.THREAD_LOCAL, new MetadataCacheStrategy.ThreadLocalCache<>());
        map.put(CacheLocationEnum.NONE, MetadataCacheStrategy.NoOpCache.instance());
        CACHE_STRATEGIES = Collections.unmodifiableMap(map);
    }

    public static FieldCache resolve(Class<?> clazz, ConfigurationHolder configurationHolder) {
        CacheLocationEnum location = configurationHolder.globalConfiguration().getFiledCacheLocation();
        MetadataCacheStrategy<FieldCacheKey, FieldCache> cache = CACHE_STRATEGIES.get(location);

        return cache.get(new FieldCacheKey(clazz, configurationHolder), key -> doResolve(clazz, configurationHolder));
    }

    private static FieldCache doResolve(Class<?> clazz, ConfigurationHolder configurationHolder) {
        // ......
    }

    // Clear ThreadLocal cache only by default
    public static void clearCache(boolean clearAll) {
        CACHE_STRATEGIES.get(CacheLocationEnum.THREAD_LOCAL).clear();
        if (clearAll) {
            CACHE_STRATEGIES.get(CacheLocationEnum.MEMORY).clear();
        }
    }
}

After refactoring:

public class ClassUtils {

    public static FieldCache declaredFields(Class<?> clazz, ConfigurationHolder configurationHolder) {
        return SheetHeadFieldResolver.resolve(clazz, configurationHolder);
    }

    public static ExcelContentProperty declaredExcelContentProperty(
            Map<?, ?> dataMap, Class<?> headClazz, String fieldName, ConfigurationHolder configurationHolder) {
        return SheetContentPropertyResolver.resolve(dataMap, headClazz, fieldName, configurationHolder);
    }

    // ......

    public static void removeThreadLocalCache() {
        SheetHeadFieldResolver.clearCache(false);
        SheetContentPropertyResolver.clearCache(false);
    }

    public static List<Class<?>> getAllInterfaces(final Class<?> cls) { ... }
}

Feedback and thoughts are welcome ：）