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.json5l.*;
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 * Pairs {@link Json5lSerializer} and {@link Json5lParser} into a single class with convenience
028 * to/of methods.
029 *
030 * <h5 class='figure'>Examples:</h5>
031 * <p class='bjava'>
032 *    <jc>// Serialize to JSON5L using instance</jc>
033 *    Json5l <jv>json5l</jv> = <jk>new</jk> Json5l();
034 *    String <jv>out</jv> = <jv>json5l</jv>.write(<jv>myList</jv>);
035 *    List&lt;MyBean&gt; <jv>in</jv> = <jv>json5l</jv>.read(<jv>out</jv>, List.<jk>class</jk>, MyBean.<jk>class</jk>);
036 *
037 *    <jc>// Serialize to JSON5L using DEFAULT instance</jc>
038 *    String <jv>out</jv> = Json5l.<jsm>of</jsm>(<jv>myList</jv>);
039 *    List&lt;MyBean&gt; <jv>in</jv> = Json5l.<jsm>to</jsm>(<jv>out</jv>, List.<jk>class</jk>, MyBean.<jk>class</jk>);
040 * </p>
041 *
042 * <h5 class='figure'>Example output (List of beans, strict-per-line default):</h5>
043 * <p class='bjson'>
044 * {"name":"Alice","age":30}
045 * {"name":"Bob","age":25}
046 * </p>
047 *
048 * <p class='bjava'>
049 * <jc>// Using static shortcuts.</jc>
050 *    MyPojo <jv>myPojo</jv> = Json5l.<jsm>to</jsm>(<jv>string</jv>, MyPojo.<jk>class</jk>);
051 *    String <jv>string</jv> = Json5l.<jsm>of</jsm>(<jv>myPojo</jv>);
052 * </p>
053 *
054 * <h5 class='section'>See Also:</h5><ul>
055 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshallers">Marshallers</a>
056 * </ul>
057 */
058@SuppressWarnings({
059   "resource" // Cursor shortcut methods return Closeables owned by the caller; Eclipse JDT @Owning warning is by design.
060})
061public class Json5l extends CharMarshaller {
062
063   /**
064    * Default reusable instance.
065    */
066   public static final Json5l DEFAULT = new Json5l();
067
068   /**
069    * Serializes a POJO to a <c>String</c> using the {@link #DEFAULT} marshaller.
070    *
071    * <p>
072    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>.
073    *
074    * @param object The object to serialize.
075    * @return The serialized object.
076    * @throws SerializeException If a problem occurred trying to convert the output.
077    */
078   public static String of(Object object) throws SerializeException {
079      return DEFAULT.write(object);
080   }
081
082   /**
083    * Parses an input into the specified object type using the {@link #DEFAULT} marshaller.
084    *
085    * <p>
086    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>.
087    *
088    * @param <T> The class type of the object being created.
089    * @param input The input.
090    * @param type The object type to create.
091    * @return The parsed object.
092    * @throws ParseException Malformed input encountered.
093    */
094   public static <T> T to(String input, Class<T> type) throws ParseException {
095      return DEFAULT.read(input, type);
096   }
097
098   /**
099    * Parses an input into the specified parameterized object type using the {@link #DEFAULT} marshaller.
100    *
101    * <p>
102    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>.
103    *
104    * @param <T> The class type of the object to create.
105    * @param input The input.
106    * @param type The object type to create.
107    * @param args The type arguments of the class if it's a collection or map.
108    * @return The parsed object.
109    * @throws ParseException Malformed input encountered.
110    */
111   public static <T> T to(String input, Type type, Type... args) throws ParseException {
112      return DEFAULT.read(input, type, args);
113   }
114
115   /**
116    * Parses the contents of a {@link Reader} into the specified object type using the {@link #DEFAULT} marshaller.
117    *
118    * <p>
119    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c> that catches any
120    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link ParseException}, so the
121    * caller is not burdened with a checked exception.
122    *
123    * @param <T> The class type of the object being created.
124    * @param input The input reader.
125    * @param type The object type to create.
126    * @return The parsed object.
127    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
128    */
129   public static <T> T to(Reader input, Class<T> type) throws ParseException {
130      try {
131         return DEFAULT.read(input, type);
132      } catch (IOException e) {
133         throw new ParseException(e);
134      }
135   }
136
137   /**
138    * Parses the contents of a {@link Reader} into the specified parameterized object type using the {@link #DEFAULT} marshaller.
139    *
140    * <p>
141    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c> that catches any
142    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link ParseException}, so the
143    * caller is not burdened with a checked exception.
144    *
145    * @param <T> The class type of the object to create.
146    * @param input The input reader.
147    * @param type The object type to create.
148    * @param args The type arguments of the class if it's a collection or map.
149    * @return The parsed object.
150    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
151    */
152   public static <T> T to(Reader input, Type type, Type... args) throws ParseException {
153      try {
154         return DEFAULT.read(input, type, args);
155      } catch (IOException e) {
156         throw new ParseException(e);
157      }
158   }
159
160   /**
161    * Serializes a POJO to the specified {@link Writer} using the {@link #DEFAULT} marshaller.
162    *
163    * <p>
164    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>, <jv>output</jv>)</c> that catches any
165    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link SerializeException}, so the
166    * caller is not burdened with a checked exception.
167    *
168    * @param object The object to serialize.
169    * @param output The writer to serialize to.
170    * @throws SerializeException If a problem occurred trying to convert the output or an I/O error occurred on the underlying stream.
171    */
172   public static void of(Object object, Writer output) throws SerializeException {
173      try {
174         DEFAULT.write(object, output);
175      } catch (IOException e) {
176         throw new SerializeException(e);
177      }
178   }
179
180   /**
181    * Opens a low-level {@link TokenReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
182    *
183    * <p>
184    * A shortcut for calling <c><jsf>DEFAULT</jsf>.readTokens(<jv>input</jv>)</c>.
185    *
186    * @param input The input.
187    * @return A new {@link TokenReader}.
188    * @throws IOException If a problem occurred opening the underlying input.
189    */
190   public static TokenReader toTokens(Object input) throws IOException {
191      return DEFAULT.readTokens(input);
192   }
193
194   /**
195    * Opens a low-level {@link TokenWriter} generator over the specified output using the {@link #DEFAULT} marshaller.
196    *
197    * <p>
198    * A shortcut for calling <c><jsf>DEFAULT</jsf>.writeTokens(<jv>output</jv>)</c>.
199    *
200    * @param output The output.
201    * @return A new {@link TokenWriter}.
202    * @throws IOException If a problem occurred opening the underlying output.
203    */
204   public static TokenWriter ofTokens(Object output) throws IOException {
205      return DEFAULT.writeTokens(output);
206   }
207
208   /**
209    * Opens a low-level {@link RecordReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
210    *
211    * <p>
212    * A shortcut for calling <c><jsf>DEFAULT</jsf>.readRecords(<jv>input</jv>)</c>.
213    *
214    * @param input The input.
215    * @return A new {@link RecordReader}.
216    * @throws IOException If a problem occurred opening the underlying input.
217    */
218   public static RecordReader toRecords(Object input) throws IOException {
219      return DEFAULT.readRecords(input);
220   }
221
222   /**
223    * Opens a low-level {@link RecordWriter} cursor over the specified output using the {@link #DEFAULT} marshaller.
224    *
225    * <p>
226    * A shortcut for calling <c><jsf>DEFAULT</jsf>.writeRecords(<jv>output</jv>)</c>.
227    *
228    * @param output The output.
229    * @return A new {@link RecordWriter}.
230    * @throws IOException If a problem occurred opening the underlying output.
231    */
232   public static RecordWriter ofRecords(Object output) throws IOException {
233      return DEFAULT.writeRecords(output);
234   }
235
236   /**
237    * Opens a {@link RecordReader} that yields each element of a top-level wire array using the {@link #DEFAULT} marshaller.
238    *
239    * <p>
240    * A shortcut for calling <c><jsf>DEFAULT</jsf>.readArrayRecords(<jv>input</jv>)</c>.
241    *
242    * @param input The input.
243    * @return A new {@link RecordReader}.
244    * @throws IOException If a problem occurred opening the underlying input.
245    */
246   public static RecordReader toArrayRecords(Object input) throws IOException {
247      return DEFAULT.readArrayRecords(input);
248   }
249
250   /**
251    * Opens a {@link RecordWriter} that wraps each written value as one element of a top-level wire array using the {@link #DEFAULT} marshaller.
252    *
253    * <p>
254    * A shortcut for calling <c><jsf>DEFAULT</jsf>.writeArrayRecords(<jv>output</jv>)</c>.
255    *
256    * @param output The output.
257    * @return A new {@link RecordWriter}.
258    * @throws IOException If a problem occurred opening the underlying output.
259    */
260   public static RecordWriter ofArrayRecords(Object output) throws IOException {
261      return DEFAULT.writeArrayRecords(output);
262   }
263
264   /**
265    * Constructor.
266    *
267    * <p>
268    * Uses {@link Json5lSerializer#DEFAULT} and {@link Json5lParser#DEFAULT}.
269    */
270   public Json5l() {
271      this(Json5lSerializer.DEFAULT, Json5lParser.DEFAULT);
272   }
273
274   /**
275    * Constructor.
276    *
277    * @param s
278    *    The serializer to use for serializing output.
279    *    <br>Must not be <jk>null</jk>.
280    * @param p
281    *    The parser to use for parsing input.
282    *    <br>Must not be <jk>null</jk>.
283    */
284   public Json5l(Json5lSerializer s, Json5lParser p) {
285      super(s, p);
286   }
287}