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.jena.marshaller;
018
019import org.apache.juneau.marshall.jena.*;
020import org.apache.juneau.marshall.marshaller.*;
021import java.lang.reflect.*;
022import org.apache.juneau.marshall.parser.*;
023import org.apache.juneau.marshall.serializer.*;
024
025/**
026 * A pairing of {@link RdfProtoSerializer} and {@link RdfProtoParser} for RDF/PROTO binary format.
027 *
028 * <h5 class='figure'>Examples:</h5>
029 * <p class='bjava'>
030 *    <jc>// Serialize a bean or map to RDF/PROTO bytes</jc>
031 *    byte[] <jv>bytes</jv> = RdfProto.<jsm>of</jsm>(<jv>myBean</jv>);
032 *
033 *    <jc>// Parse RDF/PROTO bytes into a bean or map</jc>
034 *    MyPojo <jv>parsed</jv> = RdfProto.<jsm>to</jsm>(<jv>bytes</jv>, MyPojo.<jk>class</jk>);
035 * </p>
036 * <p class='bjava'>
037 *    <jc>// Using instance methods</jc>
038 *    RdfProto <jv>m</jv> = RdfProto.<jsf>DEFAULT</jsf>;
039 *    <jv>bytes</jv> = <jv>m</jv>.write(<jv>myBean</jv>);
040 *    <jv>parsed</jv> = <jv>m</jv>.read(<jv>bytes</jv>, MyPojo.<jk>class</jk>);
041 * </p>
042 *
043 * <p>Output is binary (<jk>byte</jk>[]), Protocol Buffers format.</p>
044 *
045 * <p>Complex structures (nested objects, arrays) serialize to equivalent RDF triples in binary form.</p>
046 *
047 * <p class='bjava'>
048 * <jc>// Using static shortcuts.</jc>
049 *    MyPojo <jv>myPojo</jv> = RdfProto.<jsm>to</jsm>(<jv>bytes</jv>, MyPojo.<jk>class</jk>);
050 *    <jk>byte</jk>[] <jv>bytes</jv> = RdfProto.<jsm>of</jsm>(<jv>myPojo</jv>);
051 * </p>
052 *
053 * <h5 class='section'>See Also:</h5><ul>
054 *    <li class='link'>{doc jmr.RdfDetails}
055 *    <li class='link'>{doc jm.Marshallers}
056 * </ul>
057 */
058public class RdfProto extends StreamMarshaller {
059
060   /** Default reusable instance.*/
061   public static final RdfProto DEFAULT = new RdfProto();
062
063   /**
064    * Serializes a POJO to a <code><jk>byte</jk>[]</code> 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 byte[] 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(byte[] 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(byte[] input, Type type, Type... args) throws ParseException {
107      return DEFAULT.read(input, type, args);
108   }
109
110   /** Constructor using defaults.*/
111   public RdfProto() {
112      this(RdfProtoSerializer.DEFAULT, RdfProtoParser.DEFAULT);
113   }
114
115   /**
116    * Constructor with serializer and parser.
117    *
118    * @param s The serializer to use.
119    *    <br>Must not be <jk>null</jk>.
120    * @param p The parser to use.
121    *    <br>Must not be <jk>null</jk>.
122    */
123   public RdfProto(RdfProtoSerializer s, RdfProtoParser p) {
124      super(s, p);
125   }
126}