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}