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