Class C3P0Config
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 Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic PropertiesThis will include System properties, and sensitive values like c3p0.password (even if they are supplied by XML config).static voidbindNamedConfigToBean(Object bean, String configName, boolean shouldBindUserOverridesAsString) static voidbindUserOverridesAsString(Object bean, String uoas) static voidbindUserOverridesToBean(Object bean, String configName) getExtensions(String configName) static com.mchange.v2.cfg.MultiPropertiesConfigstatic StringDeprecated.In general, try to use com.mchange.v2.cfg.SealedSystemPropertiesStringProperty with C3P0Config.getMultiPropertiesConfig() as its argument.getUnspecifiedUserProperties(String configName) static StringgetUnspecifiedUserProperty(com.mchange.v2.c3p0.cfg.C3P0Config.PropKeyConfigName pkcn) static StringgetUnspecifiedUserProperty(String propKey, String configName) getUserOverrides(String configName) static StringgetUserOverridesAsString(String configName) static booleaninitializeBooleanPropertyVar(String propKey, boolean dflt) static Mapstatic intinitializeIntPropertyVar(String propKey, int dflt) static StringinitializeStringPropertyVar(String propKey, String dflt) static StringinitializeStringPropertyVar(String propKey, String dflt, com.mchange.v2.c3p0.cfg.Validator<String> validator) static Stringstatic voidstatic voidrefreshMainConfig(com.mchange.v2.cfg.MultiPropertiesConfig[] overrides, String overridesDescription) Deprecated.Please userefreshMainConfigWithOverrides( MultiPropertiesConfig[] overrides, String overridesDescription ).static voidrefreshMainConfigWithBackstops(com.mchange.v2.cfg.MultiPropertiesConfig[] backstops, String backstopsDescription) static voidrefreshMainConfigWithBackstops(com.mchange.v2.cfg.MultiPropertiesConfig backstops, String backstopsDescription) static voidrefreshMainConfigWithBackstops(Properties backstops, String backstopsDescription) static voidrefreshMainConfigWithBackstopsAndOverrides(com.mchange.v2.cfg.MultiPropertiesConfig[] backstops, String backstopsDescription, com.mchange.v2.cfg.MultiPropertiesConfig[] overrides, String overridesDescription) static voidrefreshMainConfigWithBackstopsAndOverrides(com.mchange.v2.cfg.MultiPropertiesConfig backstops, String backstopsDescription, com.mchange.v2.cfg.MultiPropertiesConfig overrides, String overridesDescription) static voidrefreshMainConfigWithBackstopsAndOverrides(Properties backstops, String backstopsDescription, Properties overrides, String overridesDescription) static voidrefreshMainConfigWithOverrides(com.mchange.v2.cfg.MultiPropertiesConfig[] overrides, String overridesDescription) static voidrefreshMainConfigWithOverrides(com.mchange.v2.cfg.MultiPropertiesConfig overrides, String overridesDescription) static voidrefreshMainConfigWithOverrides(Properties overrides, String overridesDescription)
-
Field Details
-
FREEZE_CONFIG_KEY
- See Also:
-
SYNC_REFRESH_LOG_CONFIG
- See Also:
-
PROPS_FILE_RSRC_PATH
- See Also:
-
-
Constructor Details
-
C3P0Config
public C3P0Config()
-
-
Method Details
-
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, considercom.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
-
refreshMainConfig
@Deprecated public static void refreshMainConfig(com.mchange.v2.cfg.MultiPropertiesConfig[] overrides, String overridesDescription) Deprecated.Please userefreshMainConfigWithOverrides( 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
-
getPropsFileConfigProperty
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
-
getExtensions
-
getUnspecifiedUserProperties
-
getUserOverrides
-
getUserOverridesAsString
public static String getUserOverridesAsString(String configName) throws IOException, com.mchange.v2.csv.MalformedCsvException - Throws:
IOExceptioncom.mchange.v2.csv.MalformedCsvException
-
bindUserOverridesAsString
- Throws:
Exception
-
bindUserOverridesToBean
- Throws:
Exception
-
bindNamedConfigToBean
public static void bindNamedConfigToBean(Object bean, String configName, boolean shouldBindUserOverridesAsString) throws IntrospectionException - Throws:
IntrospectionException
-
initializeUserOverridesAsString
-
initializeExtensions
-
initializeStringPropertyVar
-
initializeStringPropertyVar
-
initializeIntPropertyVar
-
initializeBooleanPropertyVar
-
getMultiPropertiesConfig
public static com.mchange.v2.cfg.MultiPropertiesConfig getMultiPropertiesConfig()
-