Class C3P0Config

java.lang.Object
com.mchange.v2.c3p0.cfg.C3P0Config

public final class C3P0Config extends Object
c3p0's configuration, as one body of properties-style keys.

One representation

Configuration arrives from many places — c3p0.properties, HOCON, c3p0-config.xml, System properties, programmatic overrides — and all of it is read into a single MultiPropertiesConfig of properties-style keys. Every accessor here derives from that one view by key prefix. There is no second representation to keep in step, which is the point: divergence between two views of one body of configuration was a recurring source of bugs, where a setting would be visible to one reader and invisible to another.

See the manual's Precedence of Configuration Settings for which source wins. In brief: a sealed System property outranks everything, then live System properties, then programmatic refresh overrides, then XML, then c3p0.properties, then HOCON, then the shipped defaults, then c3p0's hard-coded defaults, and backstops below those.

How c3p0-config.xml becomes properties

The XML format is read by a PropertiesConfigSource which translates it into properties keys, so that XML layers with every other source by the ordinary rules. mchange-commons-java knows nothing of the format: c3p0 declares C3P0ExtraPropertiesConfigSources through a mcfg-extra-properties-config-sources.txt resource, and that resolver claims identifiers beginning c3p0-xml:. See ExtraPropertiesConfigSources for the mechanism and C3P0XmlPropertiesConfigSource for the parser.

An identifier is c3p0-xml: followed by either a classloader resource path beginning / — where every resource at that path is read and merged, earlier classpath entries winning, just as for properties resources — or a file: URL, which gets the full file: treatment including ${system.property} references, ?required= and ?permissions=useronly. c3p0-xml:/ alone names nothing and is refused, as is a query string on the classloader form, which would otherwise be read as part of the resource path and silently find nothing. Because the file: form can refuse on permission grounds, the source is a VetoableConfig: plain MConfig.AsProvided will not read it.

Property names are mapped by shape, since the parser has no list of c3p0's configurable properties to validate against. Within <default-config>, a bare name takes a c3p0. prefix and a compound name is kept as written — so maxPoolSize becomes c3p0.maxPoolSize, while com.mchange.v2.log.freezeConfig means itself. Within <named-config name="X">, names are prefixed c3p0.named-configs.X. and a leading c3p0. is dropped first, so both spellings of a pool property arrive at one key; a fully-qualified name is refused with a warning there, because a named config is a per-DataSource scope while such settings are read globally, with no DataSource in hand. <user-overrides user="..."/> maps the same way beneath c3p0.user-overrides.<user>. or c3p0.named-configs.X.user-overrides.<user>. — a name attribute is accepted in place of user, with a warning, because a since-corrected error in c3p0's own documentation showed it. <extensions> names are never processed, being names a deployment invented for its own use, and are not read beneath a user override at all, since extensions are per-config rather than per-user.

Dots in a named-config name or a user-override user name

Both may contain dots. A database user name of the form first.last is ordinary, and c3p0-0.14.2 accepted a dotted <named-config> name in XML, where it kept scopes in a bean keyed by the attribute and so never split a flat key. These names become segments of one flat key namespace here, in which a dot is the only separator there is, so reading them back takes care; refusing them outright, which 0.15.0 briefly did, withdrew configuration that had worked for years.

What is refused, with a warning, is a name carrying named-configs, user-overrides or extensions as one of its dot-separated elements. Such a name is not merely awkward but genuinely ambiguous: c3p0.named-configs.a.extensions.b is equally an extension b of scope a and a property of a scope called a.extensions.b, and nothing in the key says which. A named config so named is refused by the parser and refused again on lookup, so the two ends agree. The same tokens in a user name are merely discouraged, with a warning: those resolve unambiguously, since a user name is always bounded by the user-overrides element on one side and its property on the other.

A user name is read as everything between user-overrides. and the final element, the final element being the property. That is unambiguous because a pool property name never contains a dot. It cuts the other way for a compound property name written under a user override, which is absorbed into the user name instead — accepted deliberately, since such a key means nothing in that position either way and still draws an unexpected-property warning.

A declared-but-empty named config

c3p0 distinguishes a scope declared empty — which falls through to lower-precedence configuration — from one never declared, which reverts to the default scope. A scope with no properties would otherwise leave no trace at all, so this source writes the bare scope key for it, carrying C3P0ConfigUtilsNoLogging.POTENTIALLY_EMPTY_NAMED_SCOPE_MARKER_VALUE as its value: a value that names itself in a config dump rather than sitting there as an unexplained empty string.

The mark is written only where it is needed — where the scope contributed no keys of its own, as judged by what actually landed rather than by which child elements were present, so that a scope whose every property was refused still reads as declared. A populated scope carries no mark, which also matches what a deployment writes by hand: nobody sets the base key of a scope they are giving properties to. Since a key is a prefix of itself, the mark reads as containsKey(pfx) on a by-prefix lookup, and declared remains the broader question — a scope declared in properties-style configuration carries no mark and is declared nonetheless. The mark is for named configs alone: for <user-overrides> and <extensions>, declared-and-empty and undeclared mean the same thing to c3p0, and an empty one of either is not content.

Scopes whose names share a dotted prefix

Because by-prefix lookup matches whole dot-separated tokens, scope a.b's keys sit underneath scope a's prefix. Neither scope may read the other's configuration, and two rules keep them apart. Definedness asks whether some key really belongs to this scope — its mark, a dotless property of its own, or its own user-overrides. or extensions. subtree — rather than merely sitting under its prefix, so a name nothing declared stays undefined however many deeper scopes exist. And a scope's keys are converted to base-prefixed properties only where the remainder after its prefix carries no further dot, which excludes user overrides, extensions, and every deeper scope's keys alike.

Both are load-bearing, and for different cases: definedness handles a shadowed name nothing declared, while the conversion rule handles a shadowed name that is declared, where no definedness test could help. Read naively, a scope inherited every deeper scope's settings and getUnspecifiedUserProperties disagreed with getUnspecifiedUserProperty about the same scope — two views of one configuration, which is the failure this package was rewritten to eliminate.

XML parsing is hardened, and stays hardened

Doctypes, external entities, external DTDs and schemas, XInclude and entity expansion are all disabled — see CVE-2018-20433. The single escape is the System property com.mchange.v2.c3p0.cfg.xml.usePermissiveParser, read only from the sealed snapshot of System properties and never from configuration: a flag that relaxes XML parsing must not be settable by the documents whose parsing it relaxes. In practice it means a -D. c3p0's deprecated com.mchange.v2.c3p0.cfg.xml.expandEntityReferences is not honored; if it is set, a warning points at usePermissiveParser instead, so that a deployment migrating from older versions is told why its entity references stopped resolving rather than left to discover it.

  • Field Details

  • Constructor Details

    • C3P0Config

      public C3P0Config()
  • Method Details

    • allCurrentProperties

      public static Properties allCurrentProperties()
      This will include System properties, and sensitive values like c3p0.password (even if they are supplied by XML config). The return value should not be promiscuously printed or dumped. If you do want to print it, consider com.mchange.v2.util.PropertiesMasker.DEFAULT.masked(...) first.
    • refreshMainConfig

      public static void refreshMainConfig()
    • refreshMainConfigWithOverrides

      public static void refreshMainConfigWithOverrides(Properties overrides, String overridesDescription)
    • refreshMainConfigWithBackstops

      public static void refreshMainConfigWithBackstops(Properties backstops, String backstopsDescription)
    • refreshMainConfigWithBackstopsAndOverrides

      public static void refreshMainConfigWithBackstopsAndOverrides(Properties backstops, String backstopsDescription, Properties overrides, String overridesDescription)
    • refreshMainConfigWithOverrides

      public static void refreshMainConfigWithOverrides(com.mchange.v2.cfg.MultiPropertiesConfig overrides, String overridesDescription)
    • refreshMainConfigWithBackstops

      public static void refreshMainConfigWithBackstops(com.mchange.v2.cfg.MultiPropertiesConfig backstops, String backstopsDescription)
    • refreshMainConfigWithBackstopsAndOverrides

      public static void refreshMainConfigWithBackstopsAndOverrides(com.mchange.v2.cfg.MultiPropertiesConfig backstops, String backstopsDescription, com.mchange.v2.cfg.MultiPropertiesConfig overrides, String overridesDescription)
    • refreshMainConfig

      @Deprecated public static void refreshMainConfig(com.mchange.v2.cfg.MultiPropertiesConfig[] overrides, String overridesDescription)
      Deprecated.
      Please use refreshMainConfigWithOverrides( MultiPropertiesConfig[] overrides, String overridesDescription ). It's clearer.
    • refreshMainConfigWithOverrides

      public static void refreshMainConfigWithOverrides(com.mchange.v2.cfg.MultiPropertiesConfig[] overrides, String overridesDescription)
    • refreshMainConfigWithBackstops

      public static void refreshMainConfigWithBackstops(com.mchange.v2.cfg.MultiPropertiesConfig[] backstops, String backstopsDescription)
    • refreshMainConfigWithBackstopsAndOverrides

      public static void refreshMainConfigWithBackstopsAndOverrides(com.mchange.v2.cfg.MultiPropertiesConfig[] backstops, String backstopsDescription, com.mchange.v2.cfg.MultiPropertiesConfig[] overrides, String overridesDescription)
    • getPropsFileConfigProperty

      @Deprecated public static String getPropsFileConfigProperty(String prop)
      Deprecated.
      In general, try to use com.mchange.v2.cfg.SealedSystemPropertiesStringProperty with C3P0Config.getMultiPropertiesConfig() as its argument.
    • getUnspecifiedUserProperty

      public static String getUnspecifiedUserProperty(com.mchange.v2.c3p0.cfg.C3P0Config.PropKeyConfigName pkcn)
    • getUnspecifiedUserProperty

      public static String getUnspecifiedUserProperty(String propKey, String configName)
    • getExtensions

      public static Map<String,String> getExtensions(String configName)
    • getUnspecifiedUserProperties

      public static Map<String,String> getUnspecifiedUserProperties(String configName)
    • getUserOverrides

      public static Map<String,Map<String,String>> getUserOverrides(String configName)
    • getUserOverridesAsString

      public static String getUserOverridesAsString(String configName) throws IOException, com.mchange.v2.csv.MalformedCsvException
      Throws:
      IOException
      com.mchange.v2.csv.MalformedCsvException
    • bindUserOverridesAsString

      public static void bindUserOverridesAsString(Object bean, String uoas) throws Exception
      Throws:
      Exception
    • bindUserOverridesToBean

      public static void bindUserOverridesToBean(Object bean, String configName) throws Exception
      Throws:
      Exception
    • bindNamedConfigToBean

      public static void bindNamedConfigToBean(Object bean, String configName, boolean shouldBindUserOverridesAsString) throws IntrospectionException
      Throws:
      IntrospectionException
    • initializeUserOverridesAsString

      public static String initializeUserOverridesAsString()
    • initializeExtensions

      public static Map initializeExtensions()
    • initializeStringPropertyVar

      public static String initializeStringPropertyVar(String propKey, String dflt, com.mchange.v2.c3p0.cfg.Validator<String> validator)
    • initializeStringPropertyVar

      public static String initializeStringPropertyVar(String propKey, String dflt)
    • initializeIntPropertyVar

      public static int initializeIntPropertyVar(String propKey, int dflt)
    • initializeBooleanPropertyVar

      public static boolean initializeBooleanPropertyVar(String propKey, boolean dflt)
    • getMultiPropertiesConfig

      public static com.mchange.v2.cfg.MultiPropertiesConfig getMultiPropertiesConfig()