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;
018
019import java.io.*;
020
021/**
022 * Stream-based RDF parser for RDF/PROTO binary format.
023 *
024 * <p>
025 * Parses compact binary RDF (Protocol Buffers encoding) into POJOs. Accepts byte arrays and input streams.
026 * Semantically equivalent to RDF/XML parsing—produces the same Java objects.
027 *
028 * <h5 class='figure'>Examples:</h5>
029 * <p class='bjava'>
030 *    <jc>// Parse RDF/PROTO bytes into a bean.</jc>
031 *    <jk>byte</jk>[] <jv>protoBytes</jv> = RdfProto.<jsm>of</jsm>(<jv>person</jv>);
032 *    Person <jv>person</jv> = RdfProtoParser.<jsf>DEFAULT</jsf>.read(<jv>protoBytes</jv>, Person.<jk>class</jk>);
033 * </p>
034 * <p class='bjava'>
035 *    <jc>// Or use the RdfProto marshaller for convenience.</jc>
036 *    Person <jv>person</jv> = RdfProto.<jsm>to</jsm>(<jv>protoBytes</jv>, Person.<jk>class</jk>);
037 * </p>
038 * <p class='bjava'>
039 *    <jc>// Parse into a map with key/value types.</jc>
040 *    Map&lt;String, String&gt; <jv>map</jv> = RdfProtoParser.<jsf>DEFAULT</jsf>.read(<jv>protoBytes</jv>, Map.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>);
041 * </p>
042 * <p class='bjava'>
043 *    <jc>// Parse from InputStream.</jc>
044 *    Person <jv>person</jv> = RdfProtoParser.<jsf>DEFAULT</jsf>.read(<jv>inputStream</jv>, Person.<jk>class</jk>);
045 * </p>
046 * <p class='bjava'>
047 *    <jc>// Custom parser with swaps.</jc>
048 *    RdfProtoParser <jv>p</jv> = RdfProtoParser.create().swaps(DateSwap.<jk>class</jk>).build();
049 *    MyBean <jv>bean</jv> = <jv>p</jv>.read(<jv>protoBytes</jv>, MyBean.<jk>class</jk>);
050 * </p>
051 *
052 * <p>Input is binary (<jk>byte</jk>[] or {@link InputStream}). Complex structures (nested objects, arrays) are supported—they are encoded as equivalent RDF triples in Protocol Buffers format.</p>
053 *
054 * <h5 class='section'>Notes:</h5><ul>
055 *    <li class='note'>This class is thread safe and reusable.
056 * </ul>
057 *
058 * <h5 class='section'>See Also:</h5><ul>
059 *    <li class='link'>{doc jmr.RdfDetails}
060 * </ul>
061 */
062@SuppressWarnings({
063   "java:S110" // Deep inheritance inherent to the RDF parser hierarchy.
064})
065public class RdfProtoParser extends RdfStreamParser {
066
067   /** Default RDF/PROTO parser.*/
068   public static final RdfProtoParser DEFAULT = new RdfProtoParser(create());
069
070   /**
071    * Creates a new builder.
072    *
073    * @return A new builder.
074    */
075   @SuppressWarnings({
076      "java:S1452", // Builder<?> wildcard return intentional; callers chain via fluent API without needing the concrete type
077      "java:S9149" // Public Juneau DSL factory; hiding parent create() is intentional.
078   })
079   public static RdfStreamParser.Builder<?> create() {
080      return RdfStreamParser.create()
081         .language(Constants.LANG_RDFPROTO)
082         .consumes("application/vnd.apache.protobuf");
083   }
084
085   /**
086    * Constructor.
087    *
088    * @param builder The builder.
089    *    <br>Cannot be <jk>null</jk>.
090    */
091   public RdfProtoParser(RdfStreamParser.Builder<?> builder) {
092      super(builder);
093   }
094}