Using this method is always optional, since you can "fail late" instead.
You must restrict validation to paths you "own" (those whose meaning are defined by your code module). If you validate globally, you may trigger errors about paths that happen to be in the config but have nothing to do with your module. It's best to allow the modules owning those paths to validate them. Also, if every module validates only its own stuff, there isn't as much redundant work being done.
If no paths are specified in checkValid()'s parameter list, validation is for the entire config.
If you specify paths that are not in the reference config, those paths are ignored. (There's nothing to validate.)
Here's what validation involves:
If you want to allow a certain setting to have a flexible type (or otherwise want validation to be looser for some settings), you could either remove the problematic setting from the reference config provided to this method, or you could intercept the validation exception and screen out certain problems. Of course, this will only work if all other callers of this method are careful to restrict validation to their own paths, as they should be.
If validation fails, the thrown exception contains a list of all problems found. See {@link ConfigException.ValidationFailed#problems}. The exception's getMessage() will have all the problems concatenated into one huge string, as well.
Again, checkValid() can't guess every domain-specific way a setting can be invalid, so some problems may arise later when attempting to use the config. checkValid() is limited to reporting generic, but common, problems such as missing settings and blatant type incompatibilities.
@param reference a reference configuration
@param restrictToPaths only validate values underneath these paths that your code module owns and understands
@throws ConfigException.ValidationFailed if there are any validation issues
@throws ConfigException.NotResolved if this config is not resolved
@throws ConfigException.BugOrBroken if the reference config is unresolved or caller otherwise misuses the API
If the specified 'literal' is a valid lexical representation for this datatype, then this method must return without throwing any exception. If not, the callee must throw an exception (with diagnosis message, if possible.)
The application can use this method to provide detailed error message to users. This method is kept separate from the isValid method to achieve higher performance during normal validation. @exception DatatypeException If the given literal is invalid, then this exception is thrown. If the callee supports error diagnosis, then the exception should contain a diagnosis message.
| |
| |
| |
| |
| |
| |
| |
| |