001/* 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2013-2017 Oracle and/or its affiliates. All rights reserved. 005 * 006 * The contents of this file are subject to the terms of either the GNU 007 * General Public License Version 2 only ("GPL") or the Common Development 008 * and Distribution License("CDDL") (collectively, the "License"). You 009 * may not use this file except in compliance with the License. You can 010 * obtain a copy of the License at 011 * https://oss.oracle.com/licenses/CDDL+GPL-1.1 012 * or LICENSE.txt. See the License for the specific 013 * language governing permissions and limitations under the License. 014 * 015 * When distributing the software, include this License Header Notice in each 016 * file and include the License file at LICENSE.txt. 017 * 018 * GPL Classpath Exception: 019 * Oracle designates this particular file as subject to the "Classpath" 020 * exception as provided by Oracle in the GPL Version 2 section of the License 021 * file that accompanied this code. 022 * 023 * Modifications: 024 * If applicable, add the following below the License Header, with the fields 025 * enclosed by brackets [] replaced by your own identifying information: 026 * "Portions Copyright [year] [name of copyright owner]" 027 * 028 * Contributor(s): 029 * If you wish your version of this file to be governed by only the CDDL or 030 * only the GPL Version 2, indicate your decision by adding "[Contributor] 031 * elects to include this software in this distribution under the [CDDL or GPL 032 * Version 2] license." If you don't indicate a single choice of license, a 033 * recipient has the option to distribute your version of this file under 034 * either the CDDL, the GPL Version 2 or to extend the choice of license to 035 * its licensees as provided above. However, if you add GPL Version 2 code 036 * and therefore, elected the GPL Version 2 license, then the option applies 037 * only if the new code is made subject to such option by the copyright 038 * holder. 039 */ 040 041package javax.json.stream; 042 043/** 044 * Provides the location information of a JSON event in an input source. The 045 * {@code JsonLocation} information can be used to identify incorrect JSON 046 * or can be used by higher frameworks to know about the processing location. 047 * 048 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonLocation> 049 * 050 * <BR /><BR />All the information provided by a {@code JsonLocation} is optional. For 051 * example, a provider may only report line numbers. Also, there may not be any 052 * location information for an input source. For example, if a 053 * {@code JsonParser} is created using 054 * {@link javax.json.JsonArray JsonArray} input source, all the methods in 055 * this class return -1. 056 * 057 * @see JsonParser 058 * @see JsonParsingException 059 */ 060public interface JsonLocation { 061 062 /** 063 * Return the line number (starts with 1 for the first line) for the current JSON event in the input source. 064 * 065 * @return the line number (starts with 1 for the first line) or -1 if none is available 066 */ 067 long getLineNumber(); 068 069 /** 070 * Return the column number (starts with 1 for the first column) for the current JSON event in the input source. 071 * 072 * @return the column number (starts with 1 for the first column) or -1 if none is available 073 */ 074 long getColumnNumber(); 075 076 /** 077 * Return the stream offset into the input source this location 078 * is pointing to. If the input source is a file or a byte stream then 079 * this is the byte offset into that stream, but if the input source is 080 * a character media then the offset is the character offset. 081 * Returns -1 if there is no offset available. 082 * 083 * @return the offset of input source stream, or -1 if there is 084 * no offset available 085 */ 086 long getStreamOffset(); 087 088}