1 /*
2 * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.oracle.javafx.jmx.json;
27
28 import com.oracle.javafx.jmx.json.JSONReader.EventType;
29 import java.util.Iterator;
30
31 /**
32 * Interface for reading a JSON document.
33 *
34 * An example of how to read a simple JSON document.
35 * <pre>
36 * JSON: { "abc": "123" }
37 *
38 * JSONFactory FACTORY = JSONFactory.instance();
39 * JSONWriter r = FACTORY.makeReader(reader);
40 * r.next(); // START_DOCUMENT
41 * r.depth(); // depth = -1
42 * r.next(); // START_OBJECT
43 * r.next(); // START_VALUE
44 * r.key(); // key = "abc"
45 * r.next(); // STRING
46 * r.value(); // value = "123"
47 * r.next(); // END_VALUE
48 * r.next(); // END_OBJECT
49 * r.next(); // END_DOCUMENT
50 * </pre>
51 *
52 */
53 public interface JSONReader extends Iterable<EventType>, Iterator<EventType> {
54
55 /**
56 * The type of JSON events.
57 */
58 public enum EventType {
59 /**
60 * An unknown event, possibly a syntax error in a JSON document.
61 */
62 ERROR,
63 /**
64 * Indicates the start of a JSON object.
65 */
66 START_OBJECT,
67 /**
68 * Indicates the end of a JSON object.
69 */
70 END_OBJECT,
71 /**
72 * Indicates the string value of a JSON element.
73 */
74 STRING,
75 /**
76 * The start of a JSON document.
77 */
78 START_DOCUMENT,
79 /**
80 * The end of a JSON document.
81 */
82 END_DOCUMENT,
83 /**
84 * Indicates the start of a JSON array.
85 */
86 START_ARRAY,
87 /**
88 * Indicates the start of a JSON array element.
89 */
90 START_ARRAY_ELEMENT,
91 /**
92 * Indicates the end of a JSON array element.
93 */
94 END_ARRAY_ELEMENT,
95 /**
96 * Indicates the end of a JSON array.
97 */
98 END_ARRAY,
99 /**
100 * Indicates a JSON floating point number.
101 */
102 NUMBER,
103 /**
104 * Indicates a JSON integer.
105 */
106 INTEGER,
107 /**
108 * Indicates a JSON true value.
109 */
110 TRUE,
111 /**
112 * Indicates a JSON false value.
113 */
114 FALSE,
115 /**
116 * Indicates a JSON null value.
117 */
118 NULL,
119 /**
120 * Indicates the start of a JSON object value.
121 */
122 START_VALUE,
123 /**
124 * Indicates the end of a JSON object value.
125 */
126 END_VALUE
127 };
128
129 /**
130 * The name of the current JSON object.
131 *
132 * @return the name of a JSON object.
133 */
134 public String key();
135
136 /**
137 * The value of the current JSON object or array element.
138 *
139 * @return the value of the JSON object or array element.
140 */
141 public String value();
142
143 /**
144 * Skips until the specified object is found at the specified depth.
145 * If depth is negative, find the first occurrence of the specified object.
146 * If objectName is null, skip until the specified depth is reached.
147 *
148 * @param key the name of the object to find, may be null
149 * @param depth stop at the first element at this depth, ignored if negative
150 * @return the event at which this method stops, EventType.END_DOCUMENT if not found
151 */
152 public EventType next(String key, int depth);
153
154 /**
155 * Close the underlying Reader when done reading.
156 */
157 public void close();
158
159 /**
160 * The current line number in the JSON file.
161 *
162 * @return the current line number in the JSON file
163 */
164 public int line();
165
166 /**
167 * The current column number in the JSON file.
168 *
169 * @return the current column number in the JSON file.
170 */
171 public int column();
172
173 /**
174 * The current byte offset in the underlying Reader. This
175 * is useful for computing percent completion.
176 *
177 * @return the current byte offset
178 */
179 public long offset();
180
181 /**
182 * The reader's current depth in the JSON file.
183 *
184 * @return the current depth in the JSON file.
185 */
186 public int depth();
187
188 /**
189 * Returns the path from the root to the current position of the JSON file.
190 *
191 * @return a String array containing the path.
192 */
193 public String[] path();
194
195 /**
196 * Build an in-memory representation of the input JSON. JSON Objects are
197 * represented with Maps and JSON Arrays are represented with Lists.
198 * @return a JSONDocument that contains a Map or a List representing the
199 * root of the input object
200 */
201 public JSONDocument build();
202 }