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.marshaller; 018 019import java.io.*; 020import java.lang.reflect.*; 021import java.nio.charset.*; 022 023import org.apache.juneau.*; 024import org.apache.juneau.csv.*; 025import org.apache.juneau.parser.*; 026import org.apache.juneau.serializer.*; 027 028/** 029 * A pairing of a {@link CsvSerializer} and {@link CsvParser} into a single class with convenience read/write methods. 030 * 031 * <h5 class='section'>See Also:</h5><ul> 032 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshallers">Marshallers</a> 033 * </ul> 034 */ 035public class Csv extends CharMarshaller { 036 037 //----------------------------------------------------------------------------------------------------------------- 038 // Static 039 //----------------------------------------------------------------------------------------------------------------- 040 041 /** 042 * Default reusable instance. 043 */ 044 public static final Csv DEFAULT = new Csv(); 045 046 //----------------------------------------------------------------------------------------------------------------- 047 // Instance 048 //----------------------------------------------------------------------------------------------------------------- 049 050 /** 051 * Constructor. 052 * 053 * @param s 054 * The serializer to use for serializing output. 055 * <br>Must not be <jk>null</jk>. 056 * @param p 057 * The parser to use for parsing input. 058 * <br>Must not be <jk>null</jk>. 059 */ 060 public Csv(CsvSerializer s, CsvParser p) { 061 super(s, p); 062 } 063 064 /** 065 * Constructor. 066 * 067 * <p> 068 * Uses {@link CsvSerializer#DEFAULT} and {@link CsvParser#DEFAULT}. 069 */ 070 public Csv() { 071 this(CsvSerializer.DEFAULT, CsvParser.DEFAULT); 072 } 073 074 /** 075 * Parses a JSON input string to the specified type. 076 * 077 * <p> 078 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>. 079 * 080 * @param <T> The class type of the object being created. 081 * @param input The input. 082 * @param type The object type to create. 083 * @return The parsed object. 084 * @throws ParseException Malformed input encountered. 085 */ 086 public static <T> T to(String input, Class<T> type) throws ParseException { 087 return DEFAULT.read(input, type); 088 } 089 090 /** 091 * Parses a JSON input object to the specified Java type. 092 * 093 * <p> 094 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>. 095 * 096 * @param <T> The class type of the object being created. 097 * @param input 098 * The input. 099 * <br>Can be any of the following types: 100 * <ul> 101 * <li><jk>null</jk> 102 * <li>{@link Reader} 103 * <li>{@link CharSequence} 104 * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by 105 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 106 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by 107 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 108 * <li>{@link File} containing system encoded text (or charset defined by 109 * {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value). 110 * </ul> 111 * @param type The object type to create. 112 * @return The parsed object. 113 * @throws ParseException Malformed input encountered. 114 * @throws IOException Thrown by underlying stream. 115 */ 116 public static <T> T to(Object input, Class<T> type) throws ParseException, IOException { 117 return DEFAULT.read(input, type); 118 } 119 120 /** 121 * Parses a JSON input string to the specified Java type. 122 * 123 * <p> 124 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>. 125 * 126 * @param <T> The class type of the object to create. 127 * @param input The input. 128 * @param type 129 * The object type to create. 130 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 131 * @param args 132 * The type arguments of the class if it's a collection or map. 133 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 134 * <br>Ignored if the main type is not a map or collection. 135 * @return The parsed object. 136 * @throws ParseException Malformed input encountered. 137 * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections. 138 */ 139 public static <T> T to(String input, Type type, Type...args) throws ParseException { 140 return DEFAULT.read(input, type, args); 141 } 142 143 /** 144 * Parses a JSON input object to the specified Java type. 145 * 146 * <p> 147 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>. 148 * 149 * @param <T> The class type of the object to create. 150 * @param input 151 * The input. 152 * <br>Can be any of the following types: 153 * <ul> 154 * <li><jk>null</jk> 155 * <li>{@link Reader} 156 * <li>{@link CharSequence} 157 * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by 158 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 159 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by 160 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 161 * <li>{@link File} containing system encoded text (or charset defined by 162 * {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value). 163 * </ul> 164 * @param type 165 * The object type to create. 166 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 167 * @param args 168 * The type arguments of the class if it's a collection or map. 169 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 170 * <br>Ignored if the main type is not a map or collection. 171 * @return The parsed object. 172 * @throws ParseException Malformed input encountered. 173 * @throws IOException Thrown by underlying stream. 174 * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections. 175 */ 176 public static <T> T to(Object input, Type type, Type...args) throws ParseException, IOException { 177 return DEFAULT.read(input, type, args); 178 } 179 180 /** 181 * Serializes a Java object to a JSON string. 182 * 183 * <p> 184 * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>. 185 * 186 * @param object The object to serialize. 187 * @return 188 * The serialized object. 189 * @throws SerializeException If a problem occurred trying to convert the output. 190 */ 191 public static String of(Object object) throws SerializeException { 192 return DEFAULT.write(object); 193 } 194 195 /** 196 * Serializes a Java object to a JSON output. 197 * 198 * <p> 199 * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>output</jv>)</c>. 200 * 201 * @param object The object to serialize. 202 * @param output 203 * The output object. 204 * <br>Can be any of the following types: 205 * <ul> 206 * <li>{@link Writer} 207 * <li>{@link OutputStream} - Output will be written as UTF-8 encoded stream. 208 * <li>{@link File} - Output will be written as system-default encoded stream. 209 * <li>{@link StringBuilder} - Output will be written to the specified string builder. 210 * </ul> 211 * @return The output object. 212 * @throws SerializeException If a problem occurred trying to convert the output. 213 * @throws IOException Thrown by underlying stream. 214 */ 215 public static Object of(Object object, Object output) throws SerializeException, IOException { 216 DEFAULT.write(object, output); 217 return output; 218 } 219}