Package io.jenkins.plugins.configsplice.engine.json

Class JsonScalarLocator

java.lang.Object

io.jenkins.plugins.configsplice.engine.json.JsonScalarLocator

public final class JsonScalarLocator
extends Object

Locates the exact source range of a JSON scalar addressed by a JsonPath (SRS sections 7.1 and 10.1).

Why locate-then-splice, and why a hybrid

Reading the document into a tree and writing it back would destroy comments, indentation, key order and newline style. So the parser is used only to understand the document; the bytes are edited in place.

Jackson reports where a token started, but the position it reports after reading a token is not reliably the token's last character: for unterminated-by-nature tokens such as numbers, the scanner must look at the following delimiter before it knows the number ended. So the end offset is computed lexically here, and the resulting candidate range is then verified by decoding it and comparing against the value Jackson itself parsed. A range only becomes a splice target once the two agree, which means a change in Jackson's offset conventions can make this class fail loudly but cannot make it corrupt a file.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	JsonScalarLocator.Located	A located scalar: where it is, what it is, and how confidently we found it.
static final record	JsonScalarLocator.OffsetEvidence	Diagnostic record of what the structural parser reported versus what was verified.
static enum	JsonScalarLocator.ScalarKind	The four JSON scalar types (SRS section 3, "Scalar").

Method Summary

Modifier and Type	Method	Description
static JsonScalarLocator.Located	locate(String text, JsonPath target)	Finds the scalar at target.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

locate

public static JsonScalarLocator.Located locate(String text,
 JsonPath target)
                                        throws SpliceException

Finds the scalar at target.

The whole document is always scanned, even after the target is found, because duplicate property names anywhere in the document are a fatal ambiguity (SRS section 7.1 rule 8).

Throws:

SpliceException - ErrorCode.PATH_MISSING if the path does not resolve, ErrorCode.NON_SCALAR if it resolves to an object or array, ErrorCode.DUPLICATE_JSON_KEY on a duplicate property name, ErrorCode.PARSE_FAILED on malformed input