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.hocon.*;
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 Hocon} variant that produces <b>compact</b> (single-line) HOCON output.
028 *
029 * <p>
030 *    This is the first-class facade form of the compact HOCON variant.  It pairs
031 *    {@link HoconSerializer#DEFAULT_COMPACT} with {@link HoconParser#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>hocon</jv> = HoconC.<jsm>of</jsm>(<jv>myPojo</jv>);
038 *    MyPojo <jv>myPojo</jv> = HoconC.<jsm>to</jsm>(<jv>hocon</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 Hocon} so that every shortcut is bound to this class's
044 *       compact {@link #DEFAULT} rather than the {@link Hocon#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 HoconC extends Hocon {
056
057   /** Default reusable instance, compact format. */
058   public static final HoconC DEFAULT = new HoconC();
059
060   /**
061    * Serializes a POJO to a <c>String</c> using the {@link #DEFAULT} marshaller.
062    *
063    * @param object The object to serialize.
064    * @return The serialized object.
065    * @throws SerializeException If a problem occurred trying to convert the output.
066    */
067   public static String of(Object object) throws SerializeException {
068      return DEFAULT.write(object);
069   }
070
071   /**
072    * Parses an input into the specified object type using the {@link #DEFAULT} marshaller.
073    *
074    * @param <T> The class type of the object being created.
075    * @param input The input.
076    * @param type The object type to create.
077    * @return The parsed object.
078    * @throws ParseException Malformed input encountered.
079    */
080   public static <T> T to(String input, Class<T> type) throws ParseException {
081      return DEFAULT.read(input, type);
082   }
083
084   /**
085    * Parses an input into the specified parameterized object type using the {@link #DEFAULT} marshaller.
086    *
087    * @param <T> The class type of the object to create.
088    * @param input The input.
089    * @param type The object type to create.
090    * @param args The type arguments of the class if it's a collection or map.
091    * @return The parsed object.
092    * @throws ParseException Malformed input encountered.
093    */
094   public static <T> T to(String input, Type type, Type... args) throws ParseException {
095      return DEFAULT.read(input, type, args);
096   }
097
098   /**
099    * Parses the contents of a {@link Reader} into the specified object type using the {@link #DEFAULT} marshaller.
100    *
101    * <p>
102    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
103    * {@link ParseException}.
104    *
105    * @param <T> The class type of the object being created.
106    * @param input The input reader.
107    * @param type The object type to create.
108    * @return The parsed object.
109    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
110    */
111   public static <T> T to(Reader input, Class<T> type) throws ParseException {
112      try {
113         return DEFAULT.read(input, type);
114      } catch (IOException e) {
115         throw new ParseException(e);
116      }
117   }
118
119   /**
120    * Parses the contents of a {@link Reader} into the specified parameterized object type using the {@link #DEFAULT} marshaller.
121    *
122    * <p>
123    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
124    * {@link ParseException}.
125    *
126    * @param <T> The class type of the object to create.
127    * @param input The input reader.
128    * @param type The object type to create.
129    * @param args The type arguments of the class if it's a collection or map.
130    * @return The parsed object.
131    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
132    */
133   public static <T> T to(Reader input, Type type, Type... args) throws ParseException {
134      try {
135         return DEFAULT.read(input, type, args);
136      } catch (IOException e) {
137         throw new ParseException(e);
138      }
139   }
140
141   /**
142    * Serializes a POJO to the specified {@link Writer} using the {@link #DEFAULT} marshaller.
143    *
144    * <p>
145    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
146    * {@link SerializeException}.
147    *
148    * @param object The object to serialize.
149    * @param output The writer to serialize to.
150    * @throws SerializeException If a problem occurred trying to convert the output or an I/O error occurred on the underlying stream.
151    */
152   public static void of(Object object, Writer output) throws SerializeException {
153      try {
154         DEFAULT.write(object, output);
155      } catch (IOException e) {
156         throw new SerializeException(e);
157      }
158   }
159
160   /**
161    * Opens a low-level {@link RecordReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
162    *
163    * @param input The input.
164    * @return A new {@link RecordReader}.
165    * @throws IOException If a problem occurred opening the underlying input.
166    */
167   public static RecordReader toRecords(Object input) throws IOException {
168      return DEFAULT.readRecords(input);
169   }
170
171   /**
172    * Opens a low-level {@link RecordWriter} cursor over the specified output using the {@link #DEFAULT} marshaller.
173    *
174    * @param output The output.
175    * @return A new {@link RecordWriter}.
176    * @throws IOException If a problem occurred opening the underlying output.
177    */
178   public static RecordWriter ofRecords(Object output) throws IOException {
179      return DEFAULT.writeRecords(output);
180   }
181
182   /**
183    * Constructor.
184    *
185    * <p>
186    * Uses {@link HoconSerializer#DEFAULT_COMPACT} and {@link HoconParser#DEFAULT}.
187    */
188   public HoconC() {
189      super(HoconSerializer.DEFAULT_COMPACT, HoconParser.DEFAULT);
190   }
191}