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.uon.*;
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 {@link Uon} variant that percent-<b>encodes</b> reserved/URL-unsafe characters in its UON output.
028 *
029 * <p>
030 *    This is the first-class facade form of the encoding UON variant.  It pairs
031 *    {@link UonSerializer#DEFAULT_ENCODING} with {@link UonParser#DEFAULT_DECODING} (which decodes the
032 *    percent-encoded characters back) and exposes the full static shortcut surface bound to its own
033 *    {@link #DEFAULT} instance.
034 *
035 * <h5 class='figure'>Examples:</h5>
036 * <p class='bjava'>
037 * <jc>// Using static shortcuts.</jc>
038 *    String <jv>uon</jv> = UonE.<jsm>of</jsm>(<jv>myPojo</jv>);
039 *    MyPojo <jv>myPojo</jv> = UonE.<jsm>to</jsm>(<jv>uon</jv>, MyPojo.<jk>class</jk>);
040 * </p>
041 *
042 * <h5 class='section'>Notes:</h5><ul>
043 *    <li class='note'>Because Java <i>hides</i> (does not override) static members, this class redeclares the
044 *       entire static shortcut surface of {@link Uon} so that every shortcut is bound to this class's
045 *       encoding {@link #DEFAULT} rather than the {@link Uon#DEFAULT}.
046 * </ul>
047 *
048 * <h5 class='section'>See Also:</h5><ul>
049 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshallers">Marshallers</a>
050 * </ul>
051 */
052@SuppressWarnings({
053   "java:S9149", // Per-format static factories intentionally shadow the parent's.
054   "resource" // Cursor shortcut methods return Closeables owned by the caller; Eclipse JDT @Owning warning is by design.
055})
056public class UonE extends Uon {
057
058   /** Default reusable instance, encoding format. */
059   public static final UonE DEFAULT = new UonE();
060
061   /**
062    * Serializes a POJO to a <c>String</c> using the {@link #DEFAULT} marshaller.
063    *
064    * @param object The object to serialize.
065    * @return The serialized object.
066    * @throws SerializeException If a problem occurred trying to convert the output.
067    */
068   public static String of(Object object) throws SerializeException {
069      return DEFAULT.write(object);
070   }
071
072   /**
073    * Parses an input into the specified object type using the {@link #DEFAULT} marshaller.
074    *
075    * @param <T> The class type of the object being created.
076    * @param input The input.
077    * @param type The object type to create.
078    * @return The parsed object.
079    * @throws ParseException Malformed input encountered.
080    */
081   public static <T> T to(String input, Class<T> type) throws ParseException {
082      return DEFAULT.read(input, type);
083   }
084
085   /**
086    * Parses an input into the specified parameterized object type using the {@link #DEFAULT} marshaller.
087    *
088    * @param <T> The class type of the object to create.
089    * @param input The input.
090    * @param type The object type to create.
091    * @param args The type arguments of the class if it's a collection or map.
092    * @return The parsed object.
093    * @throws ParseException Malformed input encountered.
094    */
095   public static <T> T to(String input, Type type, Type... args) throws ParseException {
096      return DEFAULT.read(input, type, args);
097   }
098
099   /**
100    * Parses the contents of a {@link Reader} into the specified object type using the {@link #DEFAULT} marshaller.
101    *
102    * <p>
103    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
104    * {@link ParseException}.
105    *
106    * @param <T> The class type of the object being created.
107    * @param input The input reader.
108    * @param type The object type to create.
109    * @return The parsed object.
110    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
111    */
112   public static <T> T to(Reader input, Class<T> type) throws ParseException {
113      try {
114         return DEFAULT.read(input, type);
115      } catch (IOException e) {
116         throw new ParseException(e);
117      }
118   }
119
120   /**
121    * Parses the contents of a {@link Reader} into the specified parameterized object type using the {@link #DEFAULT} marshaller.
122    *
123    * <p>
124    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
125    * {@link ParseException}.
126    *
127    * @param <T> The class type of the object to create.
128    * @param input The input reader.
129    * @param type The object type to create.
130    * @param args The type arguments of the class if it's a collection or map.
131    * @return The parsed object.
132    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
133    */
134   public static <T> T to(Reader input, Type type, Type... args) throws ParseException {
135      try {
136         return DEFAULT.read(input, type, args);
137      } catch (IOException e) {
138         throw new ParseException(e);
139      }
140   }
141
142   /**
143    * Serializes a POJO to the specified {@link Writer} using the {@link #DEFAULT} marshaller.
144    *
145    * <p>
146    * Catches any {@link IOException} from the underlying stream and rethrows it as an unchecked
147    * {@link SerializeException}.
148    *
149    * @param object The object to serialize.
150    * @param output The writer to serialize to.
151    * @throws SerializeException If a problem occurred trying to convert the output or an I/O error occurred on the underlying stream.
152    */
153   public static void of(Object object, Writer output) throws SerializeException {
154      try {
155         DEFAULT.write(object, output);
156      } catch (IOException e) {
157         throw new SerializeException(e);
158      }
159   }
160
161   /**
162    * Opens a low-level {@link RecordReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
163    *
164    * @param input The input.
165    * @return A new {@link RecordReader}.
166    * @throws IOException If a problem occurred opening the underlying input.
167    */
168   public static RecordReader toRecords(Object input) throws IOException {
169      return DEFAULT.readRecords(input);
170   }
171
172   /**
173    * Opens a low-level {@link RecordWriter} cursor over the specified output using the {@link #DEFAULT} marshaller.
174    *
175    * @param output The output.
176    * @return A new {@link RecordWriter}.
177    * @throws IOException If a problem occurred opening the underlying output.
178    */
179   public static RecordWriter ofRecords(Object output) throws IOException {
180      return DEFAULT.writeRecords(output);
181   }
182
183   /**
184    * Constructor.
185    *
186    * <p>
187    * Uses {@link UonSerializer#DEFAULT_ENCODING} and {@link UonParser#DEFAULT_DECODING}.
188    */
189   public UonE() {
190      super(UonSerializer.DEFAULT_ENCODING, UonParser.DEFAULT_DECODING);
191   }
192}