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