Class ExtraPropertiesConfigSources


  • public abstract class ExtraPropertiesConfigSources
    extends java.lang.Object
    How a library teaches this one to read an identifier form it has never heard of.

    Why this exists

    MConfig understands a fixed set of identifier forms: classloader resource paths, file: URLs, hocon: paths, and the two System-property pseudo-paths. Adding a form used to mean adding a branch here, which is how c3p0's XML format came to live inside this library — a layering inversion that was apologized for in a comment and kept in step by hand. A library may now declare its own readers instead, and this library knows nothing of them.

    Declaring one

    Ship a mcfg-extra-properties-config-sources.txt resource at the root of a jar or classpath directory, one fully-qualified class name per line. Blank lines are ignored, as is anything from a # to the end of a line, so a name may carry a trailing comment. Each named class must extend this one and must have a public no-argument constructor, because instances are created reflectively, by name.

    Each declared resolver is offered an identifier that nothing built in claims. It returns a PropertiesConfigSource if it recognizes the identifier, or null to pass the question on to the next resolver. An identifier no resolver claims is reported at WARNING and contributes no configuration; it is not fatal.

    A resolver's source may implement VetoableConfig, so an extension can make an identifier refusable. Vetoability is a property of the source rather than of how the identifier is spelled, and so is discovered by resolving: MConfig.AsProvided will decline such an identifier exactly as it declines a file: one, rather than risking a refusal it promises callers cannot happen.

    The two orderings, which are opposite

    Resolvers are first-found. Across resources, the one earliest on the CLASSPATH is consulted first, per the JVM's usual rule for a contested resource; within one resource, the earliest line is consulted first. The first resolver to claim an identifier settles how it is read, so later declarations cannot displace earlier ones.

    That is the opposite of how the resource paths themselves compose, where later wins — a path later in a config source list takes precedence, because the last value written is the one in force. The distinction is worth holding onto: one is a question of who decides how to read a name, the other of whose value survives.

    Lifetime, and why there is no refresh

    The set of resolvers is resolved once per ClassLoader and then fixed. A resource that appears afterwards is not picked up, and there is deliberately no way to ask for a rescan.

    That is a decision rather than an omission. This is a dispatch table, not configuration: it settles how an identifier is interpreted, where configuration settles what a setting's value is. MConfig's cached readers key on the identifier string as a stable name, so a table that could change mid-JVM would let one string mean different things at different moments. It would also make resolution unstable within a single read, which resolves each identifier twice — once to ask whether it is vetoable, once to read it. java.util.ServiceLoader caches providers and requires an explicit reload() for the same reasons; a reload here could be added later, as a deliberate API, if a real need appears.

    Because instances are shared and cached, implementations must be stateless and safe for concurrent use, so that any instance is interchangeable with any other. Anything a resolver needs for the duration of one call belongs in a local variable.

    • Field Detail

      • MCFG_EXTRA_PROPERTIES_CONFIG_SOURCES

        public static final java.lang.String MCFG_EXTRA_PROPERTIES_CONFIG_SOURCES
        See Also:
        Constant Field Values
    • Constructor Detail

      • ExtraPropertiesConfigSources

        public ExtraPropertiesConfigSources()
    • Method Detail

      • getResourceConfigured

        public static java.util.List<ExtraPropertiesConfigSources> getResourceConfigured​(java.util.List<DelayedLogItem> delayedLogItemsOut)
        Returns:
        null iff there are no resource files configured, empty list if there are files but no classes
      • propertiesConfigSourceForIdentifier

        public abstract PropertiesConfigSource propertiesConfigSourceForIdentifier​(java.lang.String identifier,
                                                                                   java.util.List<DelayedLogItem> delayedLogItemsOut)