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.msgpack.*;
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 MsgPack} variant that represents binary values as <b>spaced hexadecimal</b> text instead
028 * of raw MessagePack bytes.
029 *
030 * <p>
031 *    This is the first-class facade form of the spaced-hex MessagePack variant.  It pairs
032 *    {@link MsgPackSerializer#DEFAULT_SPACED_HEX} with {@link MsgPackParser#DEFAULT_SPACED_HEX} and exposes
033 *    the full static shortcut surface bound to its own {@link #DEFAULT} instance.
034 *
035 * <h5 class='figure'>Examples:</h5>
036 * <p class='bjava'>
037 * <jc>// Using static shortcuts.</jc>
038 *    <jk>byte</jk>[] <jv>bytes</jv> = MsgPackSpacedHex.<jsm>of</jsm>(<jv>myPojo</jv>);
039 *    MyPojo <jv>myPojo</jv> = MsgPackSpacedHex.<jsm>to</jsm>(<jv>bytes</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 MsgPack} so that every shortcut is bound to this class's
045 *       spaced-hex {@link #DEFAULT} rather than the {@link MsgPack#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 MsgPackSpacedHex extends MsgPack {
057
058   /** Default reusable instance, spaced-hex format. */
059   public static final MsgPackSpacedHex DEFAULT = new MsgPackSpacedHex();
060
061   /**
062    * Serializes a POJO to a <code><jk>byte</jk>[]</code> 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 byte[] 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(byte[] 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(byte[] input, Type type, Type... args) throws ParseException {
096      return DEFAULT.read(input, type, args);
097   }
098
099   /**
100    * Parses the contents of an {@link InputStream} 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 stream.
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(InputStream 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 an {@link InputStream} 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 stream.
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(InputStream 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 OutputStream} 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 output stream 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, OutputStream 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 TokenReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
163    *
164    * @param input The input.
165    * @return A new {@link TokenReader}.
166    * @throws IOException If a problem occurred opening the underlying input.
167    */
168   public static TokenReader toTokens(Object input) throws IOException {
169      return DEFAULT.readTokens(input);
170   }
171
172   /**
173    * Opens a low-level {@link TokenWriter} generator over the specified output using the {@link #DEFAULT} marshaller.
174    *
175    * @param output The output.
176    * @return A new {@link TokenWriter}.
177    * @throws IOException If a problem occurred opening the underlying output.
178    */
179   public static TokenWriter ofTokens(Object output) throws IOException {
180      return DEFAULT.writeTokens(output);
181   }
182
183   /**
184    * Opens a low-level {@link RecordReader} cursor over the specified input using the {@link #DEFAULT} marshaller.
185    *
186    * @param input The input.
187    * @return A new {@link RecordReader}.
188    * @throws IOException If a problem occurred opening the underlying input.
189    */
190   public static RecordReader toRecords(Object input) throws IOException {
191      return DEFAULT.readRecords(input);
192   }
193
194   /**
195    * Opens a low-level {@link RecordWriter} cursor over the specified output using the {@link #DEFAULT} marshaller.
196    *
197    * @param output The output.
198    * @return A new {@link RecordWriter}.
199    * @throws IOException If a problem occurred opening the underlying output.
200    */
201   public static RecordWriter ofRecords(Object output) throws IOException {
202      return DEFAULT.writeRecords(output);
203   }
204
205   /**
206    * Opens a {@link RecordReader} that yields each element of a top-level wire array using the {@link #DEFAULT} marshaller.
207    *
208    * @param input The input.
209    * @return A new {@link RecordReader}.
210    * @throws IOException If a problem occurred opening the underlying input.
211    */
212   public static RecordReader toArrayRecords(Object input) throws IOException {
213      return DEFAULT.readArrayRecords(input);
214   }
215
216   /**
217    * Opens a {@link RecordWriter} that wraps each written value as one element of a top-level wire array using the {@link #DEFAULT} marshaller.
218    *
219    * @param output The output.
220    * @return A new {@link RecordWriter}.
221    * @throws IOException If a problem occurred opening the underlying output.
222    */
223   public static RecordWriter ofArrayRecords(Object output) throws IOException {
224      return DEFAULT.writeArrayRecords(output);
225   }
226
227   /**
228    * Constructor.
229    *
230    * <p>
231    * Uses {@link MsgPackSerializer#DEFAULT_SPACED_HEX} and {@link MsgPackParser#DEFAULT_SPACED_HEX}.
232    */
233   public MsgPackSpacedHex() {
234      super(MsgPackSerializer.DEFAULT_SPACED_HEX, MsgPackParser.DEFAULT_SPACED_HEX);
235   }
236}