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.sse.*;
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 * Pairs {@link SseSerializer} and {@link SseParser} into a single class with convenience
028 * read/write methods for the <c>text/event-stream</c> wire format.
029 *
030 * <h5 class='figure'>Examples:</h5>
031 * <p class='bjava'>
032 *    <jc>// Serialize a list of events using the DEFAULT instance</jc>
033 *    List&lt;SseEvent&gt; <jv>events</jv> = List.<jsm>of</jsm>(
034 *       <jk>new</jk> SseEvent(<js>"progress"</js>, <js>"step 1"</js>),
035 *       <jk>new</jk> SseEvent(<js>"progress"</js>, <js>"step 2"</js>)
036 *    );
037 *    String <jv>wire</jv> = Sse.<jsm>of</jsm>(<jv>events</jv>);
038 *
039 *    <jc>// Parse a wire string back into a list of events</jc>
040 *    List&lt;SseEvent&gt; <jv>parsed</jv> = Sse.<jsm>to</jsm>(<jv>wire</jv>, List.<jk>class</jk>, SseEvent.<jk>class</jk>);
041 * </p>
042 *
043 * <p class='bjava'>
044 * <jc>// Using static shortcuts.</jc>
045 *    MyPojo <jv>myPojo</jv> = Sse.<jsm>to</jsm>(<jv>string</jv>, MyPojo.<jk>class</jk>);
046 *    String <jv>string</jv> = Sse.<jsm>of</jsm>(<jv>myPojo</jv>);
047 * </p>
048 *
049 * <h5 class='section'>See Also:</h5><ul>
050 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshallers">Marshallers</a>
051 * </ul>
052 */
053@SuppressWarnings({
054   "resource" // Cursor shortcut methods return Closeables owned by the caller; Eclipse JDT @Owning warning is by design.
055})
056public class Sse extends CharMarshaller {
057
058   /**
059    * Default reusable instance.
060    */
061   public static final Sse DEFAULT = new Sse();
062
063   /**
064    * Serializes a POJO to a <c>String</c> using the {@link #DEFAULT} marshaller.
065    *
066    * <p>
067    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>.
068    *
069    * @param object The object to serialize.
070    * @return The serialized object.
071    * @throws SerializeException If a problem occurred trying to convert the output.
072    */
073   public static String of(Object object) throws SerializeException {
074      return DEFAULT.write(object);
075   }
076
077   /**
078    * Parses an input into the specified object type using the {@link #DEFAULT} marshaller.
079    *
080    * <p>
081    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>.
082    *
083    * @param <T> The class type of the object being created.
084    * @param input The input.
085    * @param type The object type to create.
086    * @return The parsed object.
087    * @throws ParseException Malformed input encountered.
088    */
089   public static <T> T to(String input, Class<T> type) throws ParseException {
090      return DEFAULT.read(input, type);
091   }
092
093   /**
094    * Parses an input into the specified parameterized object type using the {@link #DEFAULT} marshaller.
095    *
096    * <p>
097    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>.
098    *
099    * @param <T> The class type of the object to create.
100    * @param input The input.
101    * @param type The object type to create.
102    * @param args The type arguments of the class if it's a collection or map.
103    * @return The parsed object.
104    * @throws ParseException Malformed input encountered.
105    */
106   public static <T> T to(String input, Type type, Type... args) throws ParseException {
107      return DEFAULT.read(input, type, args);
108   }
109
110   /**
111    * Parses the contents of a {@link Reader} into the specified object type using the {@link #DEFAULT} marshaller.
112    *
113    * <p>
114    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c> that catches any
115    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link ParseException}, so the
116    * caller is not burdened with a checked exception.
117    *
118    * @param <T> The class type of the object being created.
119    * @param input The input reader.
120    * @param type The object type to create.
121    * @return The parsed object.
122    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
123    */
124   public static <T> T to(Reader input, Class<T> type) throws ParseException {
125      try {
126         return DEFAULT.read(input, type);
127      } catch (IOException e) {
128         throw new ParseException(e);
129      }
130   }
131
132   /**
133    * Parses the contents of a {@link Reader} into the specified parameterized object type using the {@link #DEFAULT} marshaller.
134    *
135    * <p>
136    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c> that catches any
137    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link ParseException}, so the
138    * caller is not burdened with a checked exception.
139    *
140    * @param <T> The class type of the object to create.
141    * @param input The input reader.
142    * @param type The object type to create.
143    * @param args The type arguments of the class if it's a collection or map.
144    * @return The parsed object.
145    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
146    */
147   public static <T> T to(Reader input, Type type, Type... args) throws ParseException {
148      try {
149         return DEFAULT.read(input, type, args);
150      } catch (IOException e) {
151         throw new ParseException(e);
152      }
153   }
154
155   /**
156    * Serializes a POJO to the specified {@link Writer} using the {@link #DEFAULT} marshaller.
157    *
158    * <p>
159    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>, <jv>output</jv>)</c> that catches any
160    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link SerializeException}, so the
161    * caller is not burdened with a checked exception.
162    *
163    * @param object The object to serialize.
164    * @param output The writer to serialize to.
165    * @throws SerializeException If a problem occurred trying to convert the output or an I/O error occurred on the underlying stream.
166    */
167   public static void of(Object object, Writer output) throws SerializeException {
168      try {
169         DEFAULT.write(object, output);
170      } catch (IOException e) {
171         throw new SerializeException(e);
172      }
173   }
174
175   /**
176    * Opens a low-level {@link RecordReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
177    *
178    * <p>
179    * A shortcut for calling <c><jsf>DEFAULT</jsf>.readRecords(<jv>input</jv>)</c>.
180    *
181    * @param input The input.
182    * @return A new {@link RecordReader}.
183    * @throws IOException If a problem occurred opening the underlying input.
184    */
185   public static RecordReader toRecords(Object input) throws IOException {
186      return DEFAULT.readRecords(input);
187   }
188
189   /**
190    * Opens a low-level {@link RecordWriter} cursor over the specified output using the {@link #DEFAULT} marshaller.
191    *
192    * <p>
193    * A shortcut for calling <c><jsf>DEFAULT</jsf>.writeRecords(<jv>output</jv>)</c>.
194    *
195    * @param output The output.
196    * @return A new {@link RecordWriter}.
197    * @throws IOException If a problem occurred opening the underlying output.
198    */
199   public static RecordWriter ofRecords(Object output) throws IOException {
200      return DEFAULT.writeRecords(output);
201   }
202
203   /**
204    * Constructor.
205    */
206   public Sse() {
207      this(SseSerializer.DEFAULT, SseParser.DEFAULT);
208   }
209
210   /**
211    * Constructor.
212    *
213    * @param s The serializer.
214    * @param p The parser.
215    */
216   public Sse(SseSerializer s, SseParser p) {
217      super(s, p);
218   }
219}