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