Implement #1364: rename JsonLocation as TokenStreamLocation

release-notes/VERSION

@@ -47,6 +47,7 @@ JSON library.
   `StreamWriteConstraints` to 500 in 3.0
 #1269: Change `JsonFactory.builder()` configuration of `RecyclerPool` to avoid
   allocation default implementation (in 3.0)
+#1364: JSTEP-6: rename `JsonLocation` as `TokenStreamLocation`
 - Rename `JsonGenerator.Feature.AUTO_CLOSE_JSON_CONTENT` as `AUTO_CLOSE_CONTENT`
 - Add `TreeCodec.nullNode()`, `TreeNode.isNull()` methods
 - Change the way `JsonLocation.NA` is included in exception messages

src/main/java/tools/jackson/core/JacksonException.java

@@ -157,7 +157,7 @@ Object writeReplace() {
     /**********************************************************************
      */
 
-    protected JsonLocation _location;
+    protected TokenStreamLocation _location;
 
     /**
      * Path through which problem that triggering throwing of
@@ -191,7 +191,7 @@ protected JacksonException(String msg, Throwable rootCause) {
         this(null, msg, null, rootCause);
     }
 
-    protected JacksonException(String msg, JsonLocation loc, Throwable rootCause) {
+    protected JacksonException(String msg, TokenStreamLocation loc, Throwable rootCause) {
         this(null, msg, loc, rootCause);
     }
 
@@ -201,7 +201,7 @@ protected JacksonException(Closeable processor, Throwable rootCause) {
         _location = _nonNullLocation(null);
     }
 
-    protected JacksonException(Closeable processor, String msg, JsonLocation loc,
+    protected JacksonException(Closeable processor, String msg, TokenStreamLocation loc,
             Throwable rootCause) {
         super(msg, rootCause);
         _processor = processor;
@@ -212,7 +212,7 @@ protected JacksonException(Closeable processor, String msg)
     {
         super(msg);
         _processor = processor;
-        JsonLocation loc = null;
+        TokenStreamLocation loc = null;
         if (processor instanceof JsonParser) {
             // 17-Aug-2015, tatu: Use of token location makes some sense from databinding,
             //   since actual parsing (current) location is typically only needed for low-level
@@ -227,7 +227,7 @@ protected JacksonException(Closeable processor, String msg, Throwable problem)
     {
         super(msg, problem);
         _processor = processor;
-        JsonLocation loc = null;
+        TokenStreamLocation loc = null;
         if (problem instanceof JacksonException) {
             loc = ((JacksonException) problem).getLocation();
         } else if (processor instanceof JsonParser) {
@@ -237,15 +237,15 @@ protected JacksonException(Closeable processor, String msg, Throwable problem)
         _location = _nonNullLocation(loc);
     }
 
-    protected JacksonException(Closeable processor, String msg, JsonLocation loc)
+    protected JacksonException(Closeable processor, String msg, TokenStreamLocation loc)
     {
         super(msg);
         _processor = processor;
         _location = _nonNullLocation(loc);
     }
 
-    private static JsonLocation _nonNullLocation(JsonLocation loc) {
-        return (loc == null) ? JsonLocation.NA : loc;
+    private static TokenStreamLocation _nonNullLocation(TokenStreamLocation loc) {
+        return (loc == null) ? TokenStreamLocation.NA : loc;
     }
 
     // @since 3.0
@@ -417,15 +417,15 @@ public StringBuilder getPathReference(StringBuilder sb)
     /**
      * Accessor for location information related to position within input
      * or output (depending on operation), if available; if not available
-     * may return {@link JsonLocation#NA} (but never {@code null}).
+     * may return {@link TokenStreamLocation#NA} (but never {@code null}).
      *<p>
      * Accuracy of location information depends on backend (format) as well
      * as (in some cases) operation being performed.
      *
      * @return Location in input or output that triggered the problem reported, if
      *    available; {@code null} otherwise.
      */
-    public JsonLocation getLocation() { return _location; }
+    public TokenStreamLocation getLocation() { return _location; }
 
     /**
      * Method that allows accessing the original "message" argument,
@@ -510,7 +510,7 @@ protected String _buildMessage()
         if (baseMessage == null) {
             baseMessage = "N/A";
         }
-        JsonLocation loc = getLocation();
+        TokenStreamLocation loc = getLocation();
         String suffix = messageSuffix();
         // mild optimization, if nothing extra is needed:
         StringBuilder sb = new StringBuilder(200);

src/main/java/tools/jackson/core/JsonParser.java

@@ -154,13 +154,13 @@ protected JsonParser() { }
      *<p>
      * Note that the location is not guaranteed to be accurate (although most
      * implementation will try their best): some implementations may only
-     * return {@link JsonLocation#NA} due to not having access
+     * return {@link TokenStreamLocation#NA} due to not having access
      * to input location information (when delegating actual decoding work
      * to other library).
      *
      * @return Starting location of the token parser currently points to
      */
-    public abstract JsonLocation currentTokenLocation();
+    public abstract TokenStreamLocation currentTokenLocation();
 
     /**
      * Method that returns location of the last processed character;
@@ -169,13 +169,13 @@ protected JsonParser() { }
      * Note that the location is not guaranteed to be accurate (although most
      * implementation will try their best): some implementations may only
      * report specific boundary locations (start or end locations of tokens)
-     * and others only return {@link JsonLocation#NA} due to not having access
+     * and others only return {@link TokenStreamLocation#NA} due to not having access
      * to input location information (when delegating actual decoding work
      * to other library).
      *
      * @return Location of the last processed input unit (byte or character)
      */
-    public abstract JsonLocation currentLocation();
+    public abstract TokenStreamLocation currentLocation();
 
     /**
      * Get an approximate count of the number of tokens that have been read.
@@ -1739,7 +1739,7 @@ protected StreamReadException _constructReadException(String msg, Throwable t) {
     /**
      * Helper method for constructing {@link StreamReadException}
      * based on current state of the parser, except for specified
-     * {@link JsonLocation} for problem location (which may not be
+     * {@link TokenStreamLocation} for problem location (which may not be
      * the exact current location)
      *
      * @param msg Base exception message to construct exception with
@@ -1749,7 +1749,7 @@ protected StreamReadException _constructReadException(String msg, Throwable t) {
      *
      * @since 2.13
      */
-    protected StreamReadException _constructReadException(String msg, JsonLocation loc) {
+    protected StreamReadException _constructReadException(String msg, TokenStreamLocation loc) {
         return new StreamReadException(this, msg, loc);
     }
 }

src/main/java/tools/jackson/core/StreamReadFeature.java

@@ -74,7 +74,7 @@ public enum StreamReadFeature
     // // // Other
 
     /**
-     * Feature that determines whether {@link JsonLocation} instances should be constructed
+     * Feature that determines whether {@link TokenStreamLocation} instances should be constructed
      * with reference to source or not. If source reference is included, its type and contents
      * are included when `toString()` method is called (most notably when printing out parse
      * exception with that location information). If feature is disabled, no source reference
@@ -88,7 +88,7 @@ public enum StreamReadFeature
      *<p>
      * Feature is disabled by default for security reason (to avoid leaking additional source
      * information), meaning that "source reference" information is NOT passed
-     * and none of source content will be included in {@link JsonLocation}
+     * and none of source content will be included in {@link TokenStreamLocation}
      * constructed either when requested explicitly, or when needed for an exception.
      */
     INCLUDE_SOURCE_IN_LOCATION(false),

src/main/java/tools/jackson/core/TokenStreamContext.java

@@ -265,15 +265,15 @@ public JsonPointer pathAsPointer(boolean includeRoot) {
      * for example, in case of JSON `Object` context, offset at which `[` token was
      * read or written. Often used for error reporting purposes.
      * Implementations that do not keep track of such location are expected to return
-     * {@link JsonLocation#NA}; this is what the default implementation does.
+     * {@link TokenStreamLocation#NA}; this is what the default implementation does.
      *
      * @param srcRef Source reference needed to construct location instance
      *
      * @return Location pointing to the point where the context
      *   start marker was found (or written); never {@code null}.
      */
-    public JsonLocation startLocation(ContentReference srcRef) {
-        return JsonLocation.NA;
+    public TokenStreamLocation startLocation(ContentReference srcRef) {
+        return TokenStreamLocation.NA;
     }
 
     /**

src/main/java/tools/jackson/core/TokenStreamFactory.java

@@ -1235,7 +1235,7 @@ public RecyclerPool<BufferRecycler> _getRecyclerPool() {
      * Overridable factory method that actually instantiates desired
      * context object.
      *
-     * @param contentRef Source reference to use (relevant to {@code JsonLocation} construction)
+     * @param contentRef Source reference to use (relevant to {@code TokenStreamLocation} construction)
      * @param resourceManaged Whether input/output buffers used are managed by this factory
      *
      * @return Context constructed
@@ -1248,7 +1248,7 @@ protected IOContext _createContext(ContentReference contentRef, boolean resource
      * Overridable factory method that actually instantiates desired
      * context object.
      *
-     * @param contentRef Source reference to use (relevant to {@code JsonLocation} construction)
+     * @param contentRef Source reference to use (relevant to {@code TokenStreamLocation} construction)
      * @param resourceManaged Whether input/output buffers used are managed by this factory
      * @param enc Character encoding defined to be used/expected
      *

src/main/java/tools/jackson/core/JsonLocation.java → src/main/java/tools/jackson/core/TokenStreamLocation.java

@@ -15,9 +15,11 @@
  * NOTE: users should be careful if using {@link #equals} implementation as
  * it may or may not compare underlying "content reference" for equality.
  * Instead if would make sense to explicitly implementing equality checks
- * using specific criteria caller desires.
+ * using specific criteria caller desires
+ * <br />
+ * NOTE: in Jackson 2.x this type was named {@code JsonLocation}
  */
-public class JsonLocation
+public class TokenStreamLocation
     implements java.io.Serializable
 {
     private static final long serialVersionUID = 2L;
@@ -26,7 +28,7 @@ public class JsonLocation
      * Shared immutable "N/A location" that can be returned to indicate
      * that no location information is available.
      */
-    public final static JsonLocation NA = new JsonLocation(ContentReference.unknown(),
+    public final static TokenStreamLocation NA = new TokenStreamLocation(ContentReference.unknown(),
             -1L, -1L, -1, -1);
 
     private final static String NO_LOCATION_DESC = "[No location information]";
@@ -57,13 +59,13 @@ public class JsonLocation
     /**********************************************************************
      */
 
-    public JsonLocation(ContentReference contentRef, long totalChars,
+    public TokenStreamLocation(ContentReference contentRef, long totalChars,
             int lineNr, int colNr)
     {
         this(contentRef, -1L, totalChars, lineNr, colNr);
     }
 
-    public JsonLocation(ContentReference contentRef, long totalBytes, long totalChars,
+    public TokenStreamLocation(ContentReference contentRef, long totalBytes, long totalChars,
             int lineNr, int columnNr)
     {
         // 14-Mar-2021, tatu: Defensive programming, but also for convenience...
@@ -220,8 +222,8 @@ public boolean equals(Object other)
     {
         if (other == this) return true;
         if (other == null) return false;
-        if (!(other instanceof JsonLocation)) return false;
-        JsonLocation otherLoc = (JsonLocation) other;
+        if (!(other instanceof TokenStreamLocation)) return false;
+        TokenStreamLocation otherLoc = (TokenStreamLocation) other;
 
         if (_contentReference == null) {
             if (otherLoc._contentReference != null) return false;

src/main/java/tools/jackson/core/base/ParserBase.java

@@ -282,8 +282,8 @@ public void close() throws JacksonException
         _inputPtr = Math.max(_inputPtr, _inputEnd);
     }
 
-//    public JsonLocation getTokenLocation()
-//   public JsonLocation getCurrentLocation()
+    // public TokenStreamLocation currentTokenLocation()
+    // public TokenStreamLocation currentLocation()
 
     /*
     /**********************************************************************
@@ -1110,7 +1110,7 @@ protected <T> T _handleBase64MissingPadding(Base64Variant b64variant)
 
     /**
      * Helper method used to encapsulate logic of including (or not) of
-     * "content reference" when constructing {@link JsonLocation} instances.
+     * "content reference" when constructing {@link TokenStreamLocation} instances.
      *
      * @return ContentReference object to use.
      */
@@ -1123,7 +1123,7 @@ protected ContentReference _contentReference() {
 
     /**
      * Helper method used to encapsulate logic of providing
-     * "content reference" when constructing {@link JsonLocation} instances
+     * "content reference" when constructing {@link TokenStreamLocation} instances
      * and source information is <b>NOT</b> to be included
      * ({@code StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION} disabled).
      *<p>

src/main/java/tools/jackson/core/base/ParserMinimalBase.java

@@ -353,8 +353,8 @@ public void close() throws JacksonException
 
     // public abstract TokenStreamContext getParsingContext();
 
-    //  public abstract JsonLocation currentTokenLocation();
-    //  public abstract JsonLocation currentLocation();
+    // public abstract TokenStreamLocation currentTokenLocation();
+    // public abstract TokenStreamLocation currentLocation();
 
     @Override
     public ObjectReadContext objectReadContext() {
@@ -1061,7 +1061,7 @@ protected <T> T _reportUnexpectedNumberChar(int ch, String comment) throws Strea
      *
      * @return Same as {@link #currentLocation()} except offset by -1
      */
-    protected JsonLocation _currentLocationMinusOne() {
+    protected TokenStreamLocation _currentLocationMinusOne() {
         return currentLocation();
     }
 

src/main/java/tools/jackson/core/exc/StreamConstraintsException.java

@@ -1,7 +1,7 @@
 package tools.jackson.core.exc;
 
 import tools.jackson.core.JacksonException;
-import tools.jackson.core.JsonLocation;
+import tools.jackson.core.TokenStreamLocation;
 
 /**
  * Exception type used to indicate violations of stream constraints
@@ -17,7 +17,7 @@ public StreamConstraintsException(String msg) {
         super(msg);
     }
 
-    public StreamConstraintsException(String msg, JsonLocation loc) {
+    public StreamConstraintsException(String msg, TokenStreamLocation loc) {
         super(msg, loc, null);
     }
 }

src/main/java/tools/jackson/core/exc/StreamReadException.java

@@ -23,16 +23,16 @@ public StreamReadException(JsonParser p, String msg, Throwable rootCause) {
         this(p, msg, _loc(p), rootCause);
     }
 
-    public StreamReadException(JsonParser p, String msg, JsonLocation loc) {
+    public StreamReadException(JsonParser p, String msg, TokenStreamLocation loc) {
         super(p, msg, loc);
     }
 
-    public StreamReadException(JsonParser p, String msg, JsonLocation loc,
+    public StreamReadException(JsonParser p, String msg, TokenStreamLocation loc,
             Throwable rootCause) {
         super(p, msg, loc, rootCause);
     }
 
-    private static JsonLocation _loc(JsonParser p) {
+    private static TokenStreamLocation _loc(JsonParser p) {
         return(p == null) ? null : p.currentLocation();    
     }
 

src/main/java/tools/jackson/core/filter/FilteringParserDelegate.java

@@ -160,7 +160,7 @@ public int getMatchCount() {
     @Override public boolean isExpectedStartArrayToken() { return _currToken == JsonToken.START_ARRAY; }
     @Override public boolean isExpectedStartObjectToken() { return _currToken == JsonToken.START_OBJECT; }
 
-    @Override public JsonLocation currentLocation() { return delegate.currentLocation(); }
+    @Override public TokenStreamLocation currentLocation() { return delegate.currentLocation(); }
 
     @Override
     public TokenStreamContext streamReadContext() {

src/main/java/tools/jackson/core/io/ContentReference.java

@@ -12,7 +12,7 @@
  * Abstraction that encloses information about content being processed --
  * input source or output target, streaming or
  * not -- for the purpose of including pertinent information in
- * location (see {@link tools.jackson.core.JsonLocation})
+ * location (see {@link tools.jackson.core.TokenStreamLocation})
  * objections, most commonly to be printed out as part of {@code Exception}
  * messages.
  */
@@ -374,9 +374,8 @@ protected boolean _appendEscaped(StringBuilder sb, int ctrlChar) {
     /**********************************************************************
      */
 
-    // Just needed for JsonLocation#equals(): although it'd seem we only need
-    // to care about identity, for backwards compatibility better compare
-    // bit more
+    // Just needed for TokenStreamLocation#equals(): although it'd seem we only need
+    // to care about identity, for backwards compatibility better compare bit more
     @Override
     public boolean equals(Object other)
     {

src/main/java/tools/jackson/core/json/DupDetector.java

@@ -53,7 +53,7 @@ public void reset() {
         _seen = null;
     }
 
-    public JsonLocation findLocation() {
+    public TokenStreamLocation findLocation() {
         // ugly but:
         if (_source instanceof JsonParser) {
             return ((JsonParser)_source).currentLocation();

src/main/java/tools/jackson/core/json/JsonReadContext.java

@@ -172,10 +172,10 @@ public JsonReadContext createChildObjectContext(int lineNr, int colNr) {
     @Override public JsonReadContext getParent() { return _parent; }
 
     @Override
-    public JsonLocation startLocation(ContentReference srcRef) {
+    public TokenStreamLocation startLocation(ContentReference srcRef) {
         // We don't keep track of offsets at this level (only reader does)
         long totalChars = -1L;
-        return new JsonLocation(ContentReference.rawReference(srcRef),
+        return new TokenStreamLocation(ContentReference.rawReference(srcRef),
                 totalChars, _lineNr, _columnNr);
     }