Source code

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