001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.marshall.marshaller;
018
019import org.apache.juneau.marshall.json5.*;
020import java.io.*;
021import java.lang.reflect.*;
022import org.apache.juneau.marshall.parser.*;
023import org.apache.juneau.marshall.serializer.*;
024import org.apache.juneau.marshall.stream.*;
025
026/**
027 * A {@link Json5} variant that produces <b>readable</b> (indented, multi-line) JSON5 output.
028 *
029 * <p>
030 *    This is the first-class facade form of the readable JSON5 variant.  It pairs
031 *    {@link Json5Serializer#DEFAULT_READABLE} with {@link Json5Parser#DEFAULT} and exposes the full
032 *    static shortcut surface bound to its own {@link #DEFAULT} instance.
033 *
034 * <h5 class='figure'>Examples:</h5>
035 * <p class='bjava'>
036 * <jc>// Using static shortcuts.</jc>
037 *    String <jv>json</jv> = Json5R.<jsm>of</jsm>(<jv>myPojo</jv>);
038 *    MyPojo <jv>myPojo</jv> = Json5R.<jsm>to</jsm>(<jv>json</jv>, MyPojo.<jk>class</jk>);
039 * </p>
040 *
041 * <h5 class='section'>Notes:</h5><ul>
042 *    <li class='note'>Because Java <i>hides</i> (does not override) static members, this class redeclares the
043 *       entire static shortcut surface of {@link Json5} so that every shortcut is bound to this class's
044 *       readable {@link #DEFAULT} rather than the compact {@link Json5#DEFAULT}.
045 * </ul>
046 *
047 * <h5 class='section'>See Also:</h5><ul>
048 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshallers">Marshallers</a>
049 * </ul>
050 */
051@SuppressWarnings({
052   "java:S9149", // Per-format static factories intentionally shadow the parent's.
053   "resource" // Cursor shortcut methods return Closeables owned by the caller; Eclipse JDT @Owning warning is by design.
054})
055public class Json5R extends Json5 {
056
057   /**
058    * Default reusable instance, readable format.
059    */
060   public static final Json5R DEFAULT = new Json5R();
061
062   /**
063    * Serializes a POJO to a <c>String</c> using the {@link #DEFAULT} marshaller.
064    *
065    * @param object The object to serialize.
066    * @return The serialized object.
067    * @throws SerializeException If a problem occurred trying to convert the output.
068    */
069   public static String of(Object object) throws SerializeException {
070      return DEFAULT.write(object);
071   }
072
073   /**
074    * Parses an input into the specified object type using the {@link #DEFAULT} marshaller.
075    *
076    * @param <T> The class type of the object being created.
077    * @param input The input.
078    * @param type The object type to create.
079    * @return The parsed object.
080    * @throws ParseException Malformed input encountered.
081    */
082   public static <T> T to(String input, Class<T> type) throws ParseException {
083      return DEFAULT.read(input, type);
084   }
085
086   /**
087    * Parses an input into the specified parameterized object type using the {@link #DEFAULT} marshaller.
088    *
089    * @param <T> The class type of the object to create.
090    * @param input The input.
091    * @param type The object type to create.
092    * @param args The type arguments of the class if it's a collection or map.
093    * @return The parsed object.
094    * @throws ParseException Malformed input encountered.
095    */
096   public static <T> T to(String input, Type type, Type... args) throws ParseException {
097      return DEFAULT.read(input, type, args);
098   }
099
100   /**
101    * Parses the contents of a {@link Reader} into the specified object type using the {@link #DEFAULT} marshaller.
102    *
103    * <p>
104    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
105    * {@link ParseException}.
106    *
107    * @param <T> The class type of the object being created.
108    * @param input The input reader.
109    * @param type The object type to create.
110    * @return The parsed object.
111    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
112    */
113   public static <T> T to(Reader input, Class<T> type) throws ParseException {
114      try {
115         return DEFAULT.read(input, type);
116      } catch (IOException e) {
117         throw new ParseException(e);
118      }
119   }
120
121   /**
122    * Parses the contents of a {@link Reader} into the specified parameterized object type using the {@link #DEFAULT} marshaller.
123    *
124    * <p>
125    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
126    * {@link ParseException}.
127    *
128    * @param <T> The class type of the object to create.
129    * @param input The input reader.
130    * @param type The object type to create.
131    * @param args The type arguments of the class if it's a collection or map.
132    * @return The parsed object.
133    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
134    */
135   public static <T> T to(Reader input, Type type, Type... args) throws ParseException {
136      try {
137         return DEFAULT.read(input, type, args);
138      } catch (IOException e) {
139         throw new ParseException(e);
140      }
141   }
142
143   /**
144    * Serializes a POJO to the specified {@link Writer} using the {@link #DEFAULT} marshaller.
145    *
146    * <p>
147    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
148    * {@link SerializeException}.
149    *
150    * @param object The object to serialize.
151    * @param output The writer to serialize to.
152    * @throws SerializeException If a problem occurred trying to convert the output or an I/O error occurred on the underlying stream.
153    */
154   public static void of(Object object, Writer output) throws SerializeException {
155      try {
156         DEFAULT.write(object, output);
157      } catch (IOException e) {
158         throw new SerializeException(e);
159      }
160   }
161
162   /**
163    * Opens a low-level {@link TokenReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
164    *
165    * @param input The input.
166    * @return A new {@link TokenReader}.
167    * @throws IOException If a problem occurred opening the underlying input.
168    */
169   public static TokenReader toTokens(Object input) throws IOException {
170      return DEFAULT.readTokens(input);
171   }
172
173   /**
174    * Opens a low-level {@link TokenWriter} generator over the specified output using the {@link #DEFAULT} marshaller.
175    *
176    * @param output The output.
177    * @return A new {@link TokenWriter}.
178    * @throws IOException If a problem occurred opening the underlying output.
179    */
180   public static TokenWriter ofTokens(Object output) throws IOException {
181      return DEFAULT.writeTokens(output);
182   }
183
184   /**
185    * Opens a low-level {@link RecordReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
186    *
187    * @param input The input.
188    * @return A new {@link RecordReader}.
189    * @throws IOException If a problem occurred opening the underlying input.
190    */
191   public static RecordReader toRecords(Object input) throws IOException {
192      return DEFAULT.readRecords(input);
193   }
194
195   /**
196    * Opens a low-level {@link RecordWriter} cursor over the specified output using the {@link #DEFAULT} marshaller.
197    *
198    * @param output The output.
199    * @return A new {@link RecordWriter}.
200    * @throws IOException If a problem occurred opening the underlying output.
201    */
202   public static RecordWriter ofRecords(Object output) throws IOException {
203      return DEFAULT.writeRecords(output);
204   }
205
206   /**
207    * Opens a {@link RecordReader} that yields each element of a top-level wire array using the {@link #DEFAULT} marshaller.
208    *
209    * @param input The input.
210    * @return A new {@link RecordReader}.
211    * @throws IOException If a problem occurred opening the underlying input.
212    */
213   public static RecordReader toArrayRecords(Object input) throws IOException {
214      return DEFAULT.readArrayRecords(input);
215   }
216
217   /**
218    * Opens a {@link RecordWriter} that wraps each written value as one element of a top-level wire array using the {@link #DEFAULT} marshaller.
219    *
220    * @param output The output.
221    * @return A new {@link RecordWriter}.
222    * @throws IOException If a problem occurred opening the underlying output.
223    */
224   public static RecordWriter ofArrayRecords(Object output) throws IOException {
225      return DEFAULT.writeArrayRecords(output);
226   }
227
228   /**
229    * Constructor.
230    *
231    * <p>
232    * Uses {@link Json5Serializer#DEFAULT_READABLE} and {@link Json5Parser#DEFAULT}.
233    */
234   public Json5R() {
235      super(Json5Serializer.DEFAULT_READABLE, Json5Parser.DEFAULT);
236   }
237}