Class FileUrlPropertiesConfigSource
- java.lang.Object
-
- com.mchange.v2.cfg.FileUrlPropertiesConfigSource
-
- All Implemented Interfaces:
PropertiesConfigSource,VetoableConfig
public final class FileUrlPropertiesConfigSource extends java.lang.Object implements PropertiesConfigSource, VetoableConfig
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classFileUrlPropertiesConfigSource.ResolvedEverything afile:identifier means, except how to parse the bytes it names.-
Nested classes/interfaces inherited from interface com.mchange.v2.cfg.PropertiesConfigSource
PropertiesConfigSource.Parse
-
-
Constructor Summary
Constructors Constructor Description FileUrlPropertiesConfigSource()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static ConfigParseExceptionexceptionIndicatingFileNotFound(VetoableConfig source, java.lang.String identifier, boolean requiredConfig, java.lang.Exception e, java.util.List<DelayedLogItem> delayedLogItems)The exception to throw when afile:identifier names a file that is not there.static booleanisFileUrlIdentifier(java.lang.String identifier)PropertiesConfigSource.ParsepropertiesFromSource(java.lang.String identifier)An Exception signifies this source cannot be parsed at all; it is a bad source.static FileUrlPropertiesConfigSource.Resolvedresolve(VetoableConfig source, java.lang.String identifier, java.util.List<DelayedLogItem> delayedLogItems)Interprets afile:identifier, up to but not including reading it.static voidwarnIfRemovableByOthers(java.lang.String identifier, java.nio.file.Path readPath, boolean requiredConfig, java.util.List<DelayedLogItem> delayedLogItems)Advisory only.
-
-
-
Method Detail
-
isFileUrlIdentifier
public static boolean isFileUrlIdentifier(java.lang.String identifier)
-
propertiesFromSource
public PropertiesConfigSource.Parse propertiesFromSource(java.lang.String identifier) throws java.io.FileNotFoundException, java.lang.Exception
Description copied from interface:PropertiesConfigSourceAn Exception signifies this source cannot be parsed at all; it is a bad source. More local failures should be handled and reported in parse messages.A
FileNotFoundExceptionorNoSuchFileExceptionmeans only that nothing was found at this identifier: the path is dropped and the remaining sources are read, reported at FINE. Any other exception is reported at WARNING, and likewise drops only this path.Both of those are reported for the source, by its caller. A
ConfigParseExceptionis the opposite arrangement: it is reported by nobody, and carries its own account instead. Throw one whenever this method has accumulatedDelayedLogItems that would otherwise be lost with the Parse it will never return.A
ConfigVetoedExceptionis different in kind: it does not mean "I could not read this", it means "this configuration must not be used". Only aVetoableConfigshould throw one.- Specified by:
propertiesFromSourcein interfacePropertiesConfigSource- Throws:
java.io.FileNotFoundExceptionjava.lang.Exception
-
resolve
public static FileUrlPropertiesConfigSource.Resolved resolve(VetoableConfig source, java.lang.String identifier, java.util.List<DelayedLogItem> delayedLogItems) throws ConfigParseException, java.net.URISyntaxException, java.io.IOException
Interprets afile:identifier, up to but not including reading it.What it does, and why it is public
Everything a
file:identifier means except how to parse the bytes it names: the query-string grammar,${system.property}references resolved against the sealed snapshot, the absolute-path rule, and thepermissions=useronlyownership-and-mode chain. What comes back is aFileUrlPropertiesConfigSource.Resolvednaming the file to open and the two directives that outlive resolution.Public so that a
PropertiesConfigSourcereading a non-properties file can get identicalfile:semantics rather than reimplement them — a second implementation would drift, and these semantics are security-relevant. c3p0'sc3p0-xml:file:/path/to/c3p0-config.xmlis the worked example: it resolves here, parses XML itself, and so honors?required=and?permissions=useronlyexactly as a properties file does.A caller doing this owes the file one more thing after a successful read:
warnIfRemovableByOthers(java.lang.String, java.nio.file.Path, boolean, java.util.List<com.mchange.v2.cfg.DelayedLogItem>)whenFileUrlPropertiesConfigSource.Resolved.enforceUserOnlyPermissionsis set. That advisory is not part of resolution because it concerns a file that has already been read successfully, and omitting it makespermissions=useronlyquietly mean less through one source than another.What it throws
Every refusal and every parse failure is a
ConfigParseException, which is the one type a caller must handle. Within that:InsecureConfigurationException— a veto, and aConfigVetoedException: an unsupported or malformed query-string key or value, a relative path, or a file that failed thepermissions=useronlycheck. Also a missing file whererequired=true, since the requirement is the deployment's own statement that absence is not acceptable.OwnLogCarryingMissingFileException— the file is absent and absence is allowed. Named rather than generic because this source wants to report the absence in its own words, carrying the delayed items it accumulated; see that class.ConfigParseExceptionitself — a malformed${}reference: one never closed, or an empty one naming nothing. A failure to parse the identifier rather than a refusal on security grounds, so it is reported rather than vetoing the load.
URISyntaxExceptionandIOExceptionescape as themselves, from parsing the URL and from examining the filesystem respectively.Note what is not thrown: an unset
${}reference. A named property that is unset, or set to nothing but whitespace, makes the configuration it names absent — the same as a file that is not there, and subject to the samerequired=rule. That is what lets a source name an optional file unconditionally in a shared resource-path list.- Parameters:
source- the source on whose behalf we are resolving. Vetoes name it, so a refusal is attributed to the source a caller actually asked for rather than to whichever class happens to hold this code. Typed VetoableConfig rather than PropertiesConfigSource becausepermissions=useronlycan refuse: a source that cannot veto has no business asking for a check that might.identifier- the full identifier, beginningfile:, query string includeddelayedLogItems- accumulates what resolution has to say. Not a logger: resolution runs while logging may itself be half-configured, so items are collected here and replayed once logging is up. A thrown exception carries the items accumulated before it, so nothing said on the way to a failure is lost.- Throws:
ConfigParseExceptionjava.net.URISyntaxExceptionjava.io.IOException
-
warnIfRemovableByOthers
public static void warnIfRemovableByOthers(java.lang.String identifier, java.nio.file.Path readPath, boolean requiredConfig, java.util.List<DelayedLogItem> delayedLogItems)Advisory only. Never vetoes, never affects what is read. The permission and ownership checks above establish that nobody else can change what this file says. They cannot establish that the file will still be there: deletion is controlled by the directories above it, not by the file. Whoever can write a containing directory can unlink the configuration, and can do so at any depth -- a tight 0700 directory inside a world-writable parent is not safe, because the parent's writer can rename the whole subtree aside and put their own in its place. So we walk all the way up. That matters here more than it might elsewhere because of an asymmetry in this class: with required=true a vanished file throws, loudly. Otherwise it is skipped at FINE and the application simply runs on without configuration it was written to expect. The quiet case is the dangerous one, so it is the one we warn about, and required=true is the remedy we suggest -- it converts a silent disappearance into a loud failure. We deliberately impose no requirement on directory structure. A general configuration library cannot demand a dedicated directory the way ssh demands ~/.ssh; config lives in shared trees for legitimate reasons. We only point out what we notice. And we notice only some of it. This is a BEST-EFFORT detection, deliberately biased toward silence: where we cannot establish that a risk is present, we say nothing rather than guess. So the absence of a warning is NOT an assurance that a file is safe from deletion -- it may equally mean we could not tell. We stay silent, specifically, when the real path will not resolve, so that there is no chain of directories to examine at all; when a directory along the way cannot be stat'ed, since being unable to look at something is not evidence against it, so the walk skips it and continues upward; and when the sticky bit cannot be read because the non-standard "unix" attribute view is unavailable, since without it a world-writable directory cannot be told apart from a world-writable sticky one like /tmp, and warning about both would be worse than warning about neither. Two further gaps are inherent rather than incidental. First, mode bits are not the only thing that can grant write access to a directory: an ACL can, on filesystems that carry them, and we do not examine ACLs -- so a directory we pass over in silence may still be writable by someone else. Second, this is a point-in-time observation, as every check here is; a directory's mode or ownership can change after we have looked at it. Erring toward silence is the right bias for an advisory that cannot be switched off. A warning that fires when it should not teaches people to ignore the warning, which costs more than the cases we miss.For callers outside this class
Public so that a
PropertiesConfigSourcereading a non-properties file throughresolve(com.mchange.v2.cfg.VetoableConfig, java.lang.String, java.util.List<com.mchange.v2.cfg.DelayedLogItem>)can complete whatpermissions=useronlypromises. Call it after a successful read, and only whenFileUrlPropertiesConfigSource.Resolved.enforceUserOnlyPermissionsis set:if ( resolved.enforceUserOnlyPermissions ) warnIfRemovableByOthers( identifier, resolved.readPath, resolved.requiredConfig, delayedLogItems );It is separate from
resolvebecause it concerns a file that has already been read: the file's own mode was sound, and what remains to say is that someone else may be able to replace it tomorrow. Skip it andpermissions=useronlyquietly means less through your source than through this one.Two things to know before reading its silence as a clean bill of health. It returns immediately when
requiredConfigis true — a vanished required file already throws, so there is no silent failure left to advise about. And, per above, it is deliberately biased toward silence: it reports only what it is sure of, so saying nothing is not the same as finding nothing wrong.- Parameters:
identifier- the identifier as written, for the messagereadPath- fromFileUrlPropertiesConfigSource.Resolved.readPath: the file actually opened, whose real directory chain is what gets walkedrequiredConfig- fromFileUrlPropertiesConfigSource.Resolved.requiredConfigdelayedLogItems- where the advisory is recorded, if there is one
-
exceptionIndicatingFileNotFound
public static ConfigParseException exceptionIndicatingFileNotFound(VetoableConfig source, java.lang.String identifier, boolean requiredConfig, java.lang.Exception e, java.util.List<DelayedLogItem> delayedLogItems)
The exception to throw when afile:identifier names a file that is not there. Returns it; the caller throws it.Returning rather than throwing is deliberate. Written as
throw exceptionIndicatingFileNotFound( .. )the compiler sees that control leaves the block, so no unreachablereturnorthrowhas to be invented to satisfy it — which is what a void method that always throws forces at every call site. The cost is that a caller who drops thethrowsilently proceeds as though the file had been read, so always throw the result.Which exception depends on what absence means here, and that is the reason to call this rather than construct one:
required=true— anInsecureConfigurationException, hence a veto. The deployment said absence was unacceptable.- the failure is already a
ConfigParseException— passed through unchanged, so a refusal raised deeper down is not reclassified as mere absence on its way out. - otherwise — an
OwnLogCarryingMissingFileException, with a delayed item recording the skip. Ordinary absence: the path contributes nothing and the load continues.
Public for the same reason
resolve(com.mchange.v2.cfg.VetoableConfig, java.lang.String, java.util.List<com.mchange.v2.cfg.DelayedLogItem>)is: a source that reads a non-properties file throughresolvemust report absence the same way, orrequired=would mean one thing through one source and another through the next.- Parameters:
source- the source to attribute a veto to. Seeresolve(com.mchange.v2.cfg.VetoableConfig, java.lang.String, java.util.List<com.mchange.v2.cfg.DelayedLogItem>).identifier- the identifier as written, NOTFileUrlPropertiesConfigSource.Resolved.readPath— the message should name what the deployment wrote, not what a symlink chain resolved it to.requiredConfig- fromFileUrlPropertiesConfigSource.Resolved.requiredConfige- the failure that indicated absence, carried as the causedelayedLogItems- accumulated items, carried by the returned exception- Returns:
- the exception to throw. Never null.
-
-