001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.marshaller;
014
015import java.io.*;
016import java.lang.reflect.*;
017import java.nio.charset.*;
018
019import org.apache.juneau.*;
020import org.apache.juneau.csv.*;
021import org.apache.juneau.parser.*;
022import org.apache.juneau.serializer.*;
023
024/**
025 * A pairing of a {@link CsvSerializer} and {@link CsvParser} into a single class with convenience read/write methods.
026 *
027 * <h5 class='section'>See Also:</h5><ul>
028 *    <li class='link'><a class="doclink" href="../../../../index.html#jm.Marshallers">Marshallers</a>
029 * </ul>
030 */
031public class Csv extends CharMarshaller {
032
033   //-----------------------------------------------------------------------------------------------------------------
034   // Static
035   //-----------------------------------------------------------------------------------------------------------------
036
037   /**
038    * Default reusable instance.
039    */
040   public static final Csv DEFAULT = new Csv();
041
042   //-----------------------------------------------------------------------------------------------------------------
043   // Instance
044   //-----------------------------------------------------------------------------------------------------------------
045
046   /**
047    * Constructor.
048    *
049    * @param s
050    *    The serializer to use for serializing output.
051    *    <br>Must not be <jk>null</jk>.
052    * @param p
053    *    The parser to use for parsing input.
054    *    <br>Must not be <jk>null</jk>.
055    */
056   public Csv(CsvSerializer s, CsvParser p) {
057      super(s, p);
058   }
059
060   /**
061    * Constructor.
062    *
063    * <p>
064    * Uses {@link CsvSerializer#DEFAULT} and {@link CsvParser#DEFAULT}.
065    */
066   public Csv() {
067      this(CsvSerializer.DEFAULT, CsvParser.DEFAULT);
068   }
069
070   /**
071    * Parses a JSON input string to the specified type.
072    *
073    * <p>
074    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>.
075    *
076    * @param <T> The class type of the object being created.
077    * @param input The input.
078    * @param type The object type to create.
079    * @return The parsed object.
080    * @throws ParseException Malformed input encountered.
081    */
082   public static <T> T to(String input, Class<T> type) throws ParseException {
083      return DEFAULT.read(input, type);
084   }
085
086   /**
087    * Parses a JSON input object to the specified Java type.
088    *
089    * <p>
090    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>.
091    *
092    * @param <T> The class type of the object being created.
093    * @param input
094    *    The input.
095    *    <br>Can be any of the following types:
096    *    <ul>
097    *       <li><jk>null</jk>
098    *       <li>{@link Reader}
099    *       <li>{@link CharSequence}
100    *       <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by
101    *          {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value).
102    *       <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by
103    *          {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value).
104    *       <li>{@link File} containing system encoded text (or charset defined by
105    *          {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value).
106    *    </ul>
107    * @param type The object type to create.
108    * @return The parsed object.
109    * @throws ParseException Malformed input encountered.
110    * @throws IOException Thrown by underlying stream.
111    */
112   public static <T> T to(Object input, Class<T> type) throws ParseException, IOException {
113      return DEFAULT.read(input, type);
114   }
115
116   /**
117    * Parses a JSON input string to the specified Java type.
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
125    *    The object type to create.
126    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
127    * @param args
128    *    The type arguments of the class if it's a collection or map.
129    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
130    *    <br>Ignored if the main type is not a map or collection.
131    * @return The parsed object.
132    * @throws ParseException Malformed input encountered.
133    * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
134    */
135   public static <T> T to(String input, Type type, Type...args) throws ParseException {
136      return DEFAULT.read(input, type, args);
137   }
138
139   /**
140    * Parses a JSON input object to the specified Java type.
141    *
142    * <p>
143    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>.
144    *
145    * @param <T> The class type of the object to create.
146    * @param input
147    *    The input.
148    *    <br>Can be any of the following types:
149    *    <ul>
150    *       <li><jk>null</jk>
151    *       <li>{@link Reader}
152    *       <li>{@link CharSequence}
153    *       <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by
154    *          {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value).
155    *       <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by
156    *          {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value).
157    *       <li>{@link File} containing system encoded text (or charset defined by
158    *          {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value).
159    *    </ul>
160    * @param type
161    *    The object type to create.
162    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
163    * @param args
164    *    The type arguments of the class if it's a collection or map.
165    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
166    *    <br>Ignored if the main type is not a map or collection.
167    * @return The parsed object.
168    * @throws ParseException Malformed input encountered.
169    * @throws IOException Thrown by underlying stream.
170    * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
171    */
172   public static <T> T to(Object input, Type type, Type...args) throws ParseException, IOException {
173      return DEFAULT.read(input, type, args);
174   }
175
176   /**
177    * Serializes a Java object to a JSON string.
178    *
179    * <p>
180    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>.
181    *
182    * @param object The object to serialize.
183    * @return
184    *    The serialized object.
185    * @throws SerializeException If a problem occurred trying to convert the output.
186    */
187   public static String of(Object object) throws SerializeException {
188      return DEFAULT.write(object);
189   }
190
191   /**
192    * Serializes a Java object to a JSON output.
193    *
194    * <p>
195    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>output</jv>)</c>.
196    *
197    * @param object The object to serialize.
198    * @param output
199    *    The output object.
200    *    <br>Can be any of the following types:
201    *    <ul>
202    *       <li>{@link Writer}
203    *       <li>{@link OutputStream} - Output will be written as UTF-8 encoded stream.
204    *       <li>{@link File} - Output will be written as system-default encoded stream.
205    *       <li>{@link StringBuilder} - Output will be written to the specified string builder.
206    *    </ul>
207    * @return The output object.
208    * @throws SerializeException If a problem occurred trying to convert the output.
209    * @throws IOException Thrown by underlying stream.
210    */
211   public static Object of(Object object, Object output) throws SerializeException, IOException {
212      DEFAULT.write(object, output);
213      return output;
214   }
215}