Package com.ultikits.ultitools.config.convert

Class ConverterRegistry

java.lang.Object
com.ultikits.ultitools.config.convert.ConverterRegistry
@Internal public final class ConverterRegistry extends Object
Module-local converter lookup and pre-file type validation. Prepared registries are published after converter discovery; selected entities are checked separately. No cached value retains the module instance used as its weak key.
Since:
6.3.0

  • Field Details

  • Constructor Details

    • ConverterRegistry

      public ConverterRegistry(ConverterRegistry parent)
      Parameters:
      parent - the parent registry, or null for an independent root

  • Method Details

    • framework

      public static ConverterRegistry framework()
      Returns:
      the shared framework registry

    • registeredTypes

      public Set<Class<?>> registeredTypes()
      Returns:
      actual scalar registrations and implementation-owned generic factory categories

    • createFramework

      private static ConverterRegistry createFramework()

    • register

      public void register(Class<?> type, ConfigConverter<?> converter, boolean exact)
      Registers a converter without replacing an existing exact target registration.
      Parameters:
      type - the target class
      converter - the converter
      exact - whether subclass lookup is forbidden

    • resolve

      public ConfigConverter<?> resolve(Type type)
      Resolves local hierarchy first, then parent hierarchy, then generic and serializable hooks.
      Parameters:
      type - the full declared type
      Returns:
      the converter, or null if no supported conversion exists

    • registered

      private ConfigConverter<?> registered(Class<?> raw)

    • prepareModule

      public static ConverterRegistry prepareModule(UltiToolsPlugin plugin, String[] packages, ClassLoader loader)
      Discovers all converters before publishing the registry, without selecting config entities. Repeating the same package set is idempotent; extending it discovers the union atomically.
      Parameters:
      plugin - the module used only as a weak cache key
      packages - the complete package set for this preparation
      loader - the module class loader
      Returns:
      the prepared immutable registry

    • prepareSelectedConfigs

      public static Set<Class<?>> prepareSelectedConfigs(UltiToolsPlugin plugin, String[] packages, ClassLoader loader)
      Checks exactly the requested auto-registration batch before any entity is constructed. Discovery caching never skips selection or validation; empty config paths remain ignored.
      Parameters:
      plugin - the module selecting the batch
      packages - exactly the packages selected for this registration
      loader - the class loader used by the selected scan
      Returns:
      the selected config classes, all checked before the caller constructs any

    • discover

      private void discover(Class<?> converterClass)

    • hasModule

      public static boolean hasModule(UltiToolsPlugin plugin)
      Parameters:
      plugin - the module
      Returns:
      whether preparation has succeeded for it

    • forModule

      public static ConverterRegistry forModule(UltiToolsPlugin plugin)
      Parameters:
      plugin - the module
      Returns:
      its prepared registry, or the framework registry

    • checkEntityFields

      public void checkEntityFields(Class<?> entity, String module, String file)
      Checks every annotated field and every generic argument without reading or writing a file. A nondefault legacy parser owns conversion and is adapted separately.
      Parameters:
      entity - the config class, including inherited fields
      module - the module name
      file - the module-relative config file

    • missingType

      private Type missingType(Type type, Set<Type> visiting)

    • hasRegisteredAlias

      private static boolean hasRegisteredAlias(Class<?> raw)

    • describe

      private static String describe(Type type)

    • rawClass

      static Class<?> rawClass(Type type)

    • toPlain

      public Object toPlain(Object value, Type type, String file, List<String> path) throws ConversionException
      Converts a Java value and enforces the storage plain-data boundary even for custom output.
      Parameters:
      value - the Java value
      type - its declared type
      file - the module-relative file
      path - the whole keys
      Returns:
      plain data
      Throws:
      ConversionException - when conversion or plain-data validation fails

    • fromPlain

      public <T> T fromPlain(Object plain, Type type, String file, List<String> path) throws ConversionException
      Converts a document value through this registry.
      Type Parameters:
      T - the result type
      Parameters:
      plain - the document value
      type - the declared Java type
      file - the module-relative file
      path - the whole keys
      Returns:
      the converted value
      Throws:
      ConversionException - on a root conversion failure

    • fromPlainResult

      public <T> ConversionResult<T> fromPlainResult(Object plain, Type type, String file, List<String> path) throws ConversionException
      Converts with an internal diagnostic collector shared by every nested context.
      Type Parameters:
      T - the result type
      Parameters:
      plain - the document value
      type - the declared type
      file - the module-relative file
      path - the whole keys
      Returns:
      the value and all collected nested failures
      Throws:
      ConversionException - on a scalar-root failure

    • toPlain

      public Object toPlain(Object value, Type type, String file, List<String> path, ConfigEntry entry) throws ConversionException
      Selects an explicitly declared legacy parser before registry conversion.
      Parameters:
      value - Java value
      type - declared type
      file - configuration file
      path - whole keys
      entry - annotation, or null for registry conversion
      Returns:
      plain data
      Throws:
      ConversionException - on conversion failure

    • toPlainResult

      @Internal public ConversionResult<Object> toPlainResult(Object value, Type type, String file, List<String> path, ConfigEntry entry) throws ConversionException
      Internal write-planning bridge; inspection callers may discard the located omissions.
      Parameters:
      value - Java value
      type - declared type
      file - configuration file
      path - whole keys
      entry - annotation, or null for registry conversion
      Returns:
      plain value and collected nested omissions
      Throws:
      ConversionException - on conversion failure

    • toPlainResult

      @Internal public ConversionResult<Object> toPlainResult(Object value, Type type, String file, List<String> path, ConfigEntry entry, Object fileValue) throws ConversionException
      Internal write-planning bridge that also takes the plain value the file holds at path.
      Parameters:
      value - Java value
      type - declared type
      file - configuration file
      path - whole keys
      entry - annotation, or null for registry conversion
      fileValue - the plain value the file holds at path, or null when unknown
      Returns:
      plain value and collected nested omissions
      Throws:
      ConversionException - on conversion failure

    • ambiguousFileKeys

      @Internal public List<List<String>> ambiguousFileKeys(Type type, Object fileValue, String file, List<String> path)
      File-key ambiguity scan: finds every typed map key that two or more of the file's own keys at one map level read back to (1: and '01': in a Map<Integer, String>), decided from the file's keys alone - no Java value is involved, so a key the module removed or never held still counts. It follows the same descent the writer uses (map entries by key text, list elements by index, only through declared map, collection and array types that the generic converter writes) and indexes each map level with the same helper the writer's binding uses, so the two never disagree. Only maps whose declared key type is neither String nor Object are indexed; file keys that do not read as the key type are ignored. Reading a key is a probe and adds no failure anywhere.
      Parameters:
      type - declared type of the setting
      fileValue - the plain value the file holds at path
      file - configuration file, for location
      path - whole keys of the setting, for location
      Returns:
      the located path of every ambiguous typed key, ending in its first spelling in file order; key paths only, never a value; empty when there is none

    • scanFileKeys

      private void scanFileKeys(ConverterRegistry.Context ctx, List<List<String>> found)
      Descends where the writer descends: only through declared types the generic converter writes.

    • scanFileList

      private void scanFileList(ConverterRegistry.Context ctx, Class<?> raw, List<List<String>> found)
      Scans each list element by its index, where the declared type is an array or a collection.

    • scanFileMap

      private void scanFileMap(ConverterRegistry.Context ctx, List<List<String>> found)
      Reports this map level's ambiguous typed keys, then scans every entry's value by its file key text.

    • heldInSeveralSpellings

      private static boolean heldInSeveralSpellings(List<String> spellings)

    • fromPlainResult

      public <T> ConversionResult<T> fromPlainResult(Object plain, Type type, String file, List<String> path, ConfigEntry entry) throws ConversionException
      Selects an explicitly declared legacy parser before registry conversion.
      Type Parameters:
      T - result type
      Parameters:
      plain - document value
      type - declared type
      file - configuration file
      path - whole keys
      entry - annotation, or null for registry conversion
      Returns:
      converted value and failures
      Throws:
      ConversionException - on conversion failure

    • write

      private Object write(Object value, ConverterRegistry.Context ctx) throws ConversionException
      Throws:
      ConversionException

    • invokeWrite

      private Object invokeWrite(ConfigConverter<Object> converter, Object value, ConverterRegistry.Context ctx) throws ConversionException
      Throws:
      ConversionException

    • read

      private <T> T read(Object plain, ConverterRegistry.Context ctx) throws ConversionException
      Throws:
      ConversionException

    • invokeRead

      private <T> T invokeRead(ConfigConverter<?> converter, Object plain, ConverterRegistry.Context ctx) throws ConversionException
      Throws:
      ConversionException

    • readSerializable

      private Object readSerializable(Object plain, Class<? extends org.bukkit.configuration.serialization.ConfigurationSerializable> factory, ConverterRegistry.Context ctx) throws ConversionException
      Throws:
      ConversionException