/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.marshall.marshaller;

import org.apache.juneau.marshall.protobuf.*;
import java.io.*;
import java.lang.reflect.*;
import org.apache.juneau.marshall.parser.*;
import org.apache.juneau.marshall.serializer.*;

/**
 * A pairing of a {@link ProtobufSerializer} and {@link ProtobufParser} into a single class with convenience read/write
 * methods.
 *
 * <p>
 * Output is binary (<code><jk>byte</jk>[]</code>) in the Protocol Buffers <b>binary</b> wire format.
 *
 * <p>
 * Distinct from the text-format {@link Prototext} marshaller (<c>text/protobuf</c>):  this marshaller emits the compact,
 * non-self-describing protobuf binary wire format and requires the target type on read.
 *
 * <h5 class='figure'>Examples:</h5>
 * <p class='bjava'>
 *    <jc>// Using static convenience methods</jc>
 *    byte[] <jv>protobuf</jv> = Protobuf.<jsm>of</jsm>(<jv>myBean</jv>);
 *    MyBean <jv>parsed</jv> = Protobuf.<jsm>to</jsm>(<jv>protobuf</jv>, MyBean.<jk>class</jk>);
 * </p>
 * <p class='bjava'>
 *    <jc>// Using the DEFAULT instance</jc>
 *    byte[] <jv>protobuf</jv> = Protobuf.<jsf>DEFAULT</jsf>.write(<jv>myBean</jv>);
 *    MyBean <jv>parsed</jv> = Protobuf.<jsf>DEFAULT</jsf>.read(<jv>protobuf</jv>, MyBean.<jk>class</jk>);
 * </p>
 *
 * <p class='bjava'>
 * <jc>// Using static shortcuts.</jc>
 *    MyPojo <jv>myPojo</jv> = Protobuf.<jsm>to</jsm>(<jv>bytes</jv>, MyPojo.<jk>class</jk>);
 *    <jk>byte</jk>[] <jv>bytes</jv> = Protobuf.<jsm>of</jsm>(<jv>myPojo</jv>);
 * </p>
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Marshallers">Marshallers</a>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Protobuf">Protobuf Binary Format Basics</a>
 * </ul>
 */
public class Protobuf extends StreamMarshaller {

   /**
    * Default reusable instance.
    */
   public static final Protobuf DEFAULT = new Protobuf();

   /**
    * Serializes a POJO to a <code><jk>byte</jk>[]</code> using the {@link #DEFAULT} marshaller.
    *
    * <p>
    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>.
    *
    * @param object The object to serialize.
    * @return The serialized object.
    * @throws SerializeException If a problem occurred trying to convert the output.
    */
   public static byte[] of(Object object) throws SerializeException {
      return DEFAULT.write(object);
   }

   /**
    * Parses an input into the specified object type using the {@link #DEFAULT} marshaller.
    *
    * <p>
    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>.
    *
    * @param <T> The class type of the object being created.
    * @param input The input.
    * @param type The object type to create.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered.
    */
   public static <T> T to(byte[] input, Class<T> type) throws ParseException {
      return DEFAULT.read(input, type);
   }

   /**
    * Parses an input into the specified parameterized object type using the {@link #DEFAULT} marshaller.
    *
    * <p>
    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>.
    *
    * @param <T> The class type of the object to create.
    * @param input The input.
    * @param type The object type to create.
    * @param args The type arguments of the class if it's a collection or map.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered.
    */
   public static <T> T to(byte[] input, Type type, Type... args) throws ParseException {
      return DEFAULT.read(input, type, args);
   }

   /**
    * Parses the contents of an {@link InputStream} into the specified object type using the {@link #DEFAULT} marshaller.
    *
    * <p>
    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c> that catches any
    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link ParseException}, so the
    * caller is not burdened with a checked exception.
    *
    * @param <T> The class type of the object being created.
    * @param input The input stream.
    * @param type The object type to create.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
    */
   public static <T> T to(InputStream input, Class<T> type) throws ParseException {
      try {
         return DEFAULT.read(input, type);
      } catch (IOException e) {
         throw new ParseException(e);
      }
   }

   /**
    * Parses the contents of an {@link InputStream} into the specified parameterized object type using the {@link #DEFAULT} marshaller.
    *
    * <p>
    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c> that catches any
    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link ParseException}, so the
    * caller is not burdened with a checked exception.
    *
    * @param <T> The class type of the object to create.
    * @param input The input stream.
    * @param type The object type to create.
    * @param args The type arguments of the class if it's a collection or map.
    * @return The parsed object.
    * @throws ParseException Malformed input encountered or an I/O error occurred on the underlying stream.
    */
   public static <T> T to(InputStream input, Type type, Type... args) throws ParseException {
      try {
         return DEFAULT.read(input, type, args);
      } catch (IOException e) {
         throw new ParseException(e);
      }
   }

   /**
    * Serializes a POJO to the specified {@link OutputStream} using the {@link #DEFAULT} marshaller.
    *
    * <p>
    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>, <jv>output</jv>)</c> that catches any
    * {@link IOException} from the underlying stream and rethrows it as an unchecked {@link SerializeException}, so the
    * caller is not burdened with a checked exception.
    *
    * @param object The object to serialize.
    * @param output The output stream to serialize to.
    * @throws SerializeException If a problem occurred trying to convert the output or an I/O error occurred on the underlying stream.
    */
   public static void of(Object object, OutputStream output) throws SerializeException {
      try {
         DEFAULT.write(object, output);
      } catch (IOException e) {
         throw new SerializeException(e);
      }
   }

   /**
    * Constructor.
    *
    * <p>
    * Uses {@link ProtobufSerializer#DEFAULT} and {@link ProtobufParser#DEFAULT}.
    */
   public Protobuf() {
      this(ProtobufSerializer.DEFAULT, ProtobufParser.DEFAULT);
   }

   /**
    * Constructor.
    *
    * @param s The serializer to use for serializing output.
    * @param p The parser to use for parsing input.
    */
   public Protobuf(ProtobufSerializer s, ProtobufParser p) {
      super(s, p);
   }
}