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 static org.apache.juneau.commons.utils.Shorts.*;
020import static org.apache.juneau.commons.utils.SystemUtils.*;
021
022import java.util.*;
023import java.util.concurrent.*;
024
025import org.apache.juneau.commons.bean.*;
026import org.apache.juneau.commons.collections.*;
027import org.apache.juneau.marshall.*;
028import org.apache.juneau.marshall.parser.*;
029import org.apache.juneau.marshall.xml.*;
030
031/**
032 * Parses RDF into POJOs.
033 *
034 * <h2 class='topic'>Behavior-specific subclasses</h2>
035 * <p>
036 * The following direct subclasses are provided for language-specific parsers:
037 * <ul class='spaced-list'>
038 *    <li>
039 *       {@link RdfXmlParser} - RDF/XML and RDF/XML-ABBREV.
040 *    <li>
041 *       {@link NTripleParser} - N-TRIPLE.
042 *    <li>
043 *       {@link TurtleParser} - TURTLE.
044 *    <li>
045 *       {@link N3Parser} - N3.
046 * </ul>
047 *
048 * <h2 class='section'>Notes:</h2><ul>
049 *    <li class='note'>This class is thread safe and reusable.
050 * </ul>
051 *
052 * <h2 class='section'>See Also:</h2><ul>
053 *    <li class='link'>{doc jmr.RdfDetails}
054
055 * </ul>
056 */
057@SuppressWarnings({
058   "java:S100", // RDF method names (getRdfXml, isXmlLang, etc.) use domain-specific casing
059   "java:S110", // Deep inheritance inherent to the RDF parser hierarchy.
060   "java:S1192" // Duplicated literals (argument/property names) read more clearly inline than as constants
061})
062public class RdfParser extends ReaderParser implements RdfMetaProvider {
063
064   /**
065    * Builder class.
066    */
067   @SuppressWarnings({
068      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
069   })
070   public abstract static class Builder<SELF extends Builder<SELF>> extends ReaderParser.Builder<SELF> {
071
072      private static final Cache<HashKey,RdfParser> CACHE = Cache.of(HashKey.class, RdfParser.class).build();
073
074      private static final Namespace DEFAULT_JUNEAU_NS = Namespace.of("j", "http://www.apache.org/juneau/");
075      private static final Namespace DEFAULT_JUNEAUBP_NS = Namespace.of("jp", "http://www.apache.org/juneaubp/");
076
077      boolean trimWhitespace;
078      boolean allowRemoteContexts;
079      boolean looseCollections;
080      String language;
081      Namespace juneauNs;
082      Namespace juneauBpNs;
083      RdfCollectionFormat collectionFormat;
084      Map<String,Object> jenaSettings = new TreeMap<>();
085
086      /**
087       * Constructor, default settings.
088       */
089      protected Builder() {
090         super();
091         trimWhitespace = env("Rdf.trimWhitespace", false);
092         looseCollections = env("Rdf.looseCollections", false);
093         language = env("Rdf.language", "RDF/XML-ABBREV");
094         collectionFormat = env("Rdf.collectionFormat", RdfCollectionFormat.DEFAULT);
095         juneauNs = DEFAULT_JUNEAU_NS;
096         juneauBpNs = DEFAULT_JUNEAUBP_NS;
097         jenaSettings = new TreeMap<>();
098      }
099
100      /**
101       * Copy constructor.
102       *
103       * @param copyFrom The builder to copy from.
104       *    <br>Cannot be <jk>null</jk>.
105       */
106      protected Builder(Builder<?> copyFrom) {
107         super(reqnn("copyFrom", copyFrom));
108         allowRemoteContexts = copyFrom.allowRemoteContexts;
109         collectionFormat = copyFrom.collectionFormat;
110         juneauBpNs = copyFrom.juneauBpNs;
111         juneauNs = copyFrom.juneauNs;
112         language = copyFrom.language;
113         looseCollections = copyFrom.looseCollections;
114         trimWhitespace = copyFrom.trimWhitespace;
115         jenaSettings = new TreeMap<>(copyFrom.jenaSettings);
116      }
117
118      /**
119       * Copy constructor.
120       *
121       * @param copyFrom The bean to copy from.
122       *    <br>Cannot be <jk>null</jk>.
123       */
124      protected Builder(RdfParser copyFrom) {
125         super(reqnn("copyFrom", copyFrom));
126         allowRemoteContexts = copyFrom.allowRemoteContexts;
127         collectionFormat = copyFrom.collectionFormat;
128         juneauBpNs = copyFrom.juneauBpNs;
129         juneauNs = copyFrom.juneauNs;
130         language = copyFrom.language;
131         looseCollections = copyFrom.looseCollections;
132         trimWhitespace = copyFrom.trimWhitespace;
133         jenaSettings = new TreeMap<>(copyFrom.jenaSettings);
134      }
135
136      /**
137       * Allow remote JSON-LD contexts.
138       *
139       * <p>
140       * When enabled, JSON-LD input may reference remote <js>"@context"</js> documents, which the parser will then fetch over the network.
141       * Only enable this when the input is trusted.
142       *
143       * <p>
144       * The default is <jk>false</jk>:  documents that reference a remote context fail to parse.
145       *
146       * @return This object.
147       */
148      public SELF allowRemoteContexts() {
149         return allowRemoteContexts(true);
150      }
151
152      /**
153       * Same as {@link #allowRemoteContexts()} but allows you to explicitly specify the value.
154       *
155       * @param value The new value for this property.
156       * @return This object.
157       */
158      public SELF allowRemoteContexts(boolean value) {
159         allowRemoteContexts = value;
160         return self();
161      }
162
163      @Override /* Overridden from Context.Builder<?> */
164      public RdfParser build() {
165         return cache(CACHE).build(RdfParser.class);
166      }
167
168      /**
169       * RDF format for representing collections and arrays.
170       *
171       * <ul class='values spaced-list'>
172       *    <li>
173       *       <js>"DEFAULT"</js> - Default format.  The default is an RDF Sequence container.
174       *    <li>
175       *       <js>"SEQ"</js> - RDF Sequence container.
176       *    <li>
177       *       <js>"BAG"</js> - RDF Bag container.
178       *    <li>
179       *       <js>"LIST"</js> - RDF List container.
180       *    <li>
181       *       <js>"MULTI_VALUED"</js> - Multi-valued properties.
182       * </ul>
183       *
184       * @param value The new value for this property.
185       *    <br>Cannot be <jk>null</jk>.
186       * @return This object.
187       */
188      public SELF collectionFormat(RdfCollectionFormat value) {
189         collectionFormat = reqnn("value", value);
190         return self();
191      }
192
193      @Override /* Overridden from Context.Builder<?> */
194      public abstract SELF copy();
195
196      @Override /* Overridden from Context.Builder<?> */
197      public HashKey hashKey() {
198         // @formatter:off
199         return HashKey.of(
200            super.hashKey(),
201            trimWhitespace,
202            allowRemoteContexts,
203            looseCollections,
204            language,
205            collectionFormat,
206            juneauNs,
207            juneauBpNs,
208            jenaSettings
209         );
210         // @formatter:on
211      }
212
213      /**
214       * Default XML namespace for bean properties.
215       *
216       * @param value
217       *    The new value for this property.
218       *    <br>The default is <code>{j:<js>'http://www.apache.org/juneaubp/'</js>}</code>.
219       *    <br>Cannot be <jk>null</jk>.
220       * @return This object.
221       */
222      public SELF juneauBpNs(Namespace value) {
223         juneauBpNs = reqnn("value", value);
224         return self();
225      }
226
227      /**
228       * XML namespace for Juneau properties.
229       *
230       * @param value
231       *    The new value for this property.
232       *    <br>The default is <code>{j:<js>'http://www.apache.org/juneau/'</js>}</code>.
233       *    <br>Cannot be <jk>null</jk>.
234       * @return This object.
235       */
236      public SELF juneauNs(Namespace value) {
237         juneauNs = reqnn("value", value);
238         return self();
239      }
240
241      /**
242       * RDF language.
243       *
244       * <p>
245       * Can be any of the following:
246       * <ul class='spaced-list'>
247       *    <li>
248       *       <js>"RDF/XML"</js>
249       *    <li>
250       *       <js>"RDF/XML-ABBREV"</js> (default)
251       *    <li>
252       *       <js>"N-TRIPLE"</js>
253       *    <li>
254       *       <js>"N3"</js> - General name for the N3 writer.
255       *       Will make a decision on exactly which writer to use (pretty writer, plain writer or simple writer) when
256       *       created.
257       *       Default is the pretty writer but can be overridden with system property
258       *       <c>org.apache.jena.n3.N3JenaWriter.writer</c>.
259       *    <li>
260       *       <js>"N3-PP"</js> - Name of the N3 pretty writer.
261       *       The pretty writer uses a frame-like layout, with prefixing, clustering like properties and embedding
262       *       one-referenced bNodes.
263       *    <li>
264       *       <js>"N3-PLAIN"</js> - Name of the N3 plain writer.
265       *       The plain writer writes records by subject.
266       *    <li>
267       *       <js>"N3-TRIPLES"</js> - Name of the N3 triples writer.
268       *       This writer writes one line per statement, like N-Triples, but does N3-style prefixing.
269       *    <li>
270       *       <js>"TURTLE"</js> -  Turtle writer.
271       *       http://www.dajobe.org/2004/01/turtle/
272       * </ul>
273       *
274       * <h4 class='section'>See Also:</h4><ul>
275       *    <li class='jm'>{@link RdfParser.Builder#n3()}
276       *    <li class='jm'>{@link RdfParser.Builder#ntriple()}
277       *    <li class='jm'>{@link RdfParser.Builder#turtle()}
278       *    <li class='jm'>{@link RdfParser.Builder#xml()}
279       * </ul>
280       *
281       * @param value The new value for this property.
282       *    <br>Cannot be <jk>null</jk>.
283       * @return This object.
284       */
285      public SELF language(String value) {
286         language = reqnn("value", value);
287         return self();
288      }
289
290      /**
291       * Collections should be serialized and parsed as loose collections.
292       *
293       * <p>
294       * When specified, collections of resources are handled as loose collections of resources in RDF instead of
295       * resources that are children of an RDF collection (e.g. Sequence, Bag).
296       *
297       * <p>
298       * Note that this setting is specialized for RDF syntax, and is incompatible with the concept of
299       * losslessly representing POJO models, since the tree structure of these POJO models are lost
300       * when serialized as loose collections.
301       *
302       * <p>
303       * This setting is typically only useful if the beans being parsed into do not have a bean property
304       * annotated with {@link Rdf#beanUri @Rdf(beanUri=true)}.
305       *
306       * <h4 class='section'>Example:</h4>
307       * <p class='bjava'>
308       *    WriterSerializer <jv>serializer</jv> = RdfSerializer
309       *       .<jsm>create</jsm>()
310       *       .xmlabbrev()
311       *       .looseCollections()
312       *       .build();
313       *
314       *    ReaderParser <jv>parser</jv> = RdfParser
315       *       .<jsm>create</jsm>()
316       *       .xml()
317       *       .looseCollections()
318       *       .build();
319       *
320       *    List&lt;MyBean&gt; <jv>list</jv> = <jsm>createListOfMyBeans</jsm>();
321       *
322       *    <jc>// Serialize to RDF/XML as loose resources</jc>
323       *    String <jv>rdfXml</jv> = <jv>serializer</jv>.write(<jv>list</jv>);
324       *
325       *    <jc>// Parse back into a Java collection</jc>
326       *    <jv>list</jv> = <jv>parser</jv>.read(<jv>rdfXml</jv>, LinkedList.<jk>class</jk>, MyBean.<jk>class</jk>);
327       *
328       *    MyBean[] <jv>bean</jv> = <jsm>createArrayOfMyBeans</jsm>();
329       *
330       *    <jc>// Serialize to RDF/XML as loose resources</jc>
331       *    <jv>rdfXml</jv> = <jv>serializer</jv>.write(<jv>beans</jv>);
332       *
333       *    <jc>// Parse back into a bean array</jc>
334       *    <jv>beans</jv> = <jv>parser</jv>.read(<jv>rdfXml</jv>, MyBean[].<jk>class</jk>);
335       * </p>
336       *
337       * @return This object.
338       */
339      public SELF looseCollections() {
340         return looseCollections(true);
341      }
342
343      /**
344       * Same as {@link #looseCollections()} but explicitly specifies the setting value.
345       *
346       * @param value The new value for this property.
347       * @return This object.
348       */
349      public SELF looseCollections(boolean value) {
350         looseCollections = value;
351         return self();
352      }
353
354      /**
355       * RDF language.
356       *
357       * <p>
358       * Shortcut for calling <code>language(<jsf>LANG_N3</jsf>)</code>.
359       *
360       * @return This object.
361       */
362      public SELF n3() {
363         return language(Constants.LANG_N3);
364      }
365
366      /**
367       * N3/Turtle property: <c>disableAbbrevBaseURI</c>.
368       *
369       * <p>
370       * Controls whether to use abbreviations <c>&lt;&gt;</c> or <c>&lt;#&gt;</c>.
371       *
372       * @return This object.
373       */
374      public SELF n3_disableAbbrevBaseUri() {
375         return n3_disableAbbrevBaseUri(true);
376      }
377
378      /**
379       * N3/Turtle property: <c>disableAbbrevBaseURI</c>.
380       *
381       * <p>
382       * Controls whether to use abbreviations <c>&lt;&gt;</c> or <c>&lt;#&gt;</c>.
383       *
384       * @param value
385       *    The new value for this setting.
386       * @return This object.
387       */
388      public SELF n3_disableAbbrevBaseUri(boolean value) {
389         return jena("n3.disableAbbrevBaseUri", value);
390      }
391
392      /**
393       * N3/Turtle property: <c>disableObjectLists</c>.
394       *
395       * <p>
396       * Don't print object lists as comma separated lists.
397       *
398       * @return This object.
399       */
400      public SELF n3_disableObjectLists() {
401         return n3_disableObjectLists(true);
402      }
403
404      /**
405       * N3/Turtle property: <c>disableObjectLists</c>.
406       *
407       * <p>
408       * Don't print object lists as comma separated lists.
409       *
410       * @param value
411       *    The new value for this property.
412       * @return This object.
413       */
414      public SELF n3_disableObjectLists(boolean value) {
415         return jena("n3.disableObjectLists", value);
416      }
417
418      /**
419       * N3/Turtle property: <c>disableUseDoubles</c>.
420       *
421       * <p>
422       * Disallow the use of doubles as <c>123.456</c>.
423       *
424       * @return This object.
425       */
426      public SELF n3_disableUseDoubles() {
427         return n3_disableUseDoubles(true);
428      }
429
430      /**
431       * N3/Turtle property: <c>disableUseDoubles</c>.
432       *
433       * <p>
434       * Disallow the use of doubles as <c>123.456</c>.
435       *
436       * @param value
437       *    The new value for this setting.
438       * @return This object.
439       */
440      public SELF n3_disableUseDoubles(boolean value) {
441         return jena("n3.disableUseDoubles", value);
442      }
443
444      /**
445       * N3/Turtle property: <c>disableUsePropertySymbols</c>.
446       *
447       * <p>
448       * Controls whether to use <c>a</c>, <c>=</c> and <c>=&gt;</c> in output
449       *
450       * @return This object.
451       */
452      public SELF n3_disableUsePropertySymbols() {
453         return n3_disableUsePropertySymbols(true);
454      }
455
456      /**
457       * N3/Turtle property: <c>disableUsePropertySymbols</c>.
458       *
459       * <p>
460       * Controls whether to use <c>a</c>, <c>=</c> and <c>=&gt;</c> in output
461       *
462       * @param value
463       *    The new value for this setting.
464       * @return This object.
465       */
466      public SELF n3_disableUsePropertySymbols(boolean value) {
467         return jena("n3.disableUsePropertySymbols", value);
468      }
469
470      /**
471       * N3/Turtle property: <c>disableUseTripleQuotedStrings</c>.
472       *
473       * <p>
474       * Disallow the use of <c>"""</c> to delimit long strings.
475       *
476       * @return This object.
477       */
478      public SELF n3_disableUseTripleQuotedStrings() {
479         return n3_disableUseTripleQuotedStrings(true);
480      }
481
482      /**
483       * N3/Turtle property: <c>disableUseTripleQuotedStrings</c>.
484       *
485       * <p>
486       * Disallow the use of <c>"""</c> to delimit long strings.
487       *
488       * @param value
489       *    The new value for this setting.
490       * @return This object.
491       */
492      public SELF n3_disableUseTripleQuotedStrings(boolean value) {
493         return jena("n3.disableUseTripleQuotedStrings", value);
494      }
495
496      /**
497       * N3/Turtle property: <c>indentProperty</c>.
498       *
499       * <p>
500       * Width to indent properties.
501       *
502       * @param value
503       *    The new value for this property.
504       * @return This object.
505       */
506      public SELF n3_indentProperty(int value) {
507         return jena("n3.indentProperty", value);
508      }
509
510      /**
511       * N3/Turtle property: <c>minGap</c>.
512       *
513       * <p>
514       * Minimum gap between items on a line.
515       *
516       * @param value
517       *    The new value for this property.
518       * @return This object.
519       */
520      public SELF n3_minGap(int value) {
521         return jena("n3.minGap", value);
522      }
523
524      /**
525       * N3/Turtle property: <c>propertyColumn</c>.
526       *
527       * <p>
528       * Width of the property column.
529       *
530       * @param value
531       *    The new value for this property.
532       * @return This object.
533       */
534      public SELF n3_propertyColumn(int value) {
535         return jena("n3.propertyColumn", value);
536      }
537
538      /**
539       * N3/Turtle property: <c>subjectColumn</c>.
540       *
541       * <p>
542       * If the subject is shorter than this value, the first property may go on the same line.
543       *
544       * @param value
545       *    The new value for this property.
546       * @return This object.
547       */
548      public SELF n3_subjectColumn(int value) {
549         return jena("n3.subjectColumn", value);
550      }
551
552      /**
553       * N3/Turtle property: <c>widePropertyLen</c>.
554       *
555       * <p>
556       * Width of the property column.
557       * Must be longer than <c>propertyColumn</c>.
558       *
559       * @param value
560       *    The new value for this property.
561       * @return This object.
562       */
563      public SELF n3_widePropertyLen(int value) {
564         return jena("n3.widePropertyLen", value);
565      }
566
567      /**
568       * RDF language.
569       *
570       * <p>
571       * Shortcut for calling <code>language(<jsf>LANG_NTRIPLE</jsf>)</code>.
572       *
573       * @return This object.
574       */
575      public SELF ntriple() {
576         return language(Constants.LANG_NTRIPLE);
577      }
578
579      /**
580       * RDF/XML property: <c>allowBadURIs</c>.
581       *
582       * <p>
583       * URIs in the graph are, by default, checked prior to serialization.
584       *
585       * @return This object.
586       */
587      public SELF rdfxml_allowBadUris() {
588         return rdfxml_allowBadUris(true);
589      }
590
591      /**
592       * RDF/XML property: <c>allowBadURIs</c>.
593       *
594       * <p>
595       * URIs in the graph are, by default, checked prior to serialization.
596       *
597       * @param value
598       *    The new value for this property.
599       * @return This object.
600       */
601      public SELF rdfxml_allowBadUris(boolean value) {
602         return jena("rdfXml.allowBadURIs", value);
603      }
604
605      /**
606       * RDF/XML property: <c>attributeQuoteChar</c>.
607       *
608       * <p>
609       * The XML attribute quote character.
610       *
611       * @param value
612       *    The new value for this property.
613       * @return This object.
614       */
615      public SELF rdfxml_attributeQuoteChar(char value) {
616         return jena("rdfXml.attributeQuoteChar", value);
617      }
618
619      /**
620       * RDF/XML property: <c>blockRules</c>.
621       *
622       * <p>
623       * A list of <c>Resource</c> or a <c>String</c> being a comma separated list of fragment IDs from
624       * {doc http://www.w3.org/TR/rdf-syntax-grammar RDF Syntax Grammar} indicating grammar
625       * rules that will not be used.
626       *
627       * @param value
628       *    The new value for this property.
629       * @return This object.
630       */
631      public SELF rdfxml_blockRules(String value) {
632         return jena("rdfXml.blockRules", value);
633      }
634
635      /**
636       * RDF/XML property: <c>disableShowDoctypeDeclaration</c>.
637       *
638       * <p>
639       * If disabled, an XML doctype declaration isn't included in the output.
640       * This declaration includes a <c>!ENTITY</c> declaration for each prefix mapping in the model, and any
641       * attribute value that starts with the URI of that mapping is written as starting with the corresponding entity
642       * invocation.
643       *
644       * @return This object.
645       */
646      public SELF rdfxml_disableShowDoctypeDeclaration() {
647         return rdfxml_disableShowDoctypeDeclaration(true);
648      }
649
650      /**
651       * RDF/XML property: <c>disableShowDoctypeDeclaration</c>.
652       *
653       * <p>
654       * If disabled, an XML doctype declaration isn't included in the output.
655       * This declaration includes a <c>!ENTITY</c> declaration for each prefix mapping in the model, and any
656       * attribute value that starts with the URI of that mapping is written as starting with the corresponding entity
657       * invocation.
658       *
659       * @param value
660       *    The new value for this property.
661       * @return This object.
662       */
663      public SELF rdfxml_disableShowDoctypeDeclaration(boolean value) {
664         return jena("rdfXml.disableShowDoctypeDeclaration", value);
665      }
666
667      /**
668       * RDF/XML ARP property: <c>embedding</c>.
669       *
670       * <p>
671       * Sets ARP to look for RDF embedded within an enclosing XML document.
672       *
673       * <h4 class='section'>See Also:</h4><ul>
674       *    <li>
675       *       {doc ext.ARP/ARPOptions.html#setEmbedding(boolean) ARPOptions.setEmbedding(boolean)}
676       * </ul>
677       *
678       * @return This object.
679       */
680      public SELF rdfxml_embedding() {
681         return rdfxml_embedding(true);
682      }
683
684      /**
685       * RDF/XML ARP property: <c>embedding</c>.
686       *
687       * <p>
688       * Sets ARP to look for RDF embedded within an enclosing XML document.
689       *
690       * <h4 class='section'>See Also:</h4><ul>
691       *    <li>
692       *       {doc ext.ARP/ARPOptions.html#setEmbedding(boolean) ARPOptions.setEmbedding(boolean)}
693       * </ul>
694       *
695       * @param value
696       *    The new value for this property.
697       * @return This object.
698       */
699      public SELF rdfxml_embedding(boolean value) {
700         return jena("rdfXml.embedding", value);
701      }
702
703      /**
704       * RDF/XML ARP property: <c>error-mode</c>.
705       *
706       * <p>
707       * This allows a coarse-grained approach to control of error handling.
708       *
709       * <ul class='values'>
710       *    <li><js>"default"</js>
711       *    <li><js>"lax"</js>
712       *    <li><js>"strict"</js>
713       *    <li><js>"strict-ignore"</js>
714       *    <li><js>"strict-warning"</js>
715       *    <li><js>"strict-error"</js>
716       *    <li><js>"strict-fatal"</js>
717       * </ul>
718       *
719       * <h4 class='section'>See Also:</h4><ul>
720       *    <li>
721       *       {doc ext.ARP/ARPOptions.html#setDefaultErrorMode() ARPOptions.setDefaultErrorMode()}
722       *    <li>
723       *       {doc ext.ARP/ARPOptions.html#setLaxErrorMode() ARPOptions.setLaxErrorMode()}
724       *    <li>
725       *       {doc ext.ARP/ARPOptions.html#setStrictErrorMode() ARPOptions.setStrictErrorMode()}
726       *    <li>
727       *       {doc ext.ARP/ARPOptions.html#setStrictErrorMode(int) ARPOptions.setStrictErrorMode(int)}
728       * </ul>
729       *
730       * @param value
731       *    The new value for this property.
732       * @return This object.
733       */
734      public SELF rdfxml_errorMode(String value) {
735         return jena("rdfXml.error-mode", value);
736      }
737
738      /**
739       * RDF/XML property: <c>iri_rules</c>.
740       *
741       * <p>
742       * Set the engine for checking and resolving.
743       *
744       * <ul class='values spaced-list'>
745       *    <li>
746       *       <js>"lax"</js> - The rules for RDF URI references only, which does permit spaces although the use of spaces
747       *       is not good practice.
748       *    <li>
749       *       <js>"strict"</js> - Sets the IRI engine with rules for valid IRIs, XLink and RDF; it does not permit spaces
750       *       in IRIs.
751       *    <li>
752       *       <js>"iri"</js> - Sets the IRI engine to IRI
753       *       ({doc http://www.ietf.org/rfc/rfc3986.txt RFC 3986},
754       *       {doc http://www.ietf.org/rfc/rfc3987.txt RFC 3987}).
755       *
756       * </ul>
757       *
758       * @param value
759       *    The new value for this property.
760       * @return This object.
761       */
762      public SELF rdfxml_iriRules(String value) {
763         return jena("rdfXml.iri-rules", value);
764      }
765
766      /**
767       * RDF/XML property: <c>longId</c>.
768       *
769       * <p>
770       * Whether to use long ID's for anon resources.
771       * Short ID's are easier to read, but can run out of memory on very large models.
772       *
773       * @return This object.
774       */
775      public SELF rdfxml_longId() {
776         return rdfxml_longId(true);
777      }
778
779      /**
780       * RDF/XML property: <c>longId</c>.
781       *
782       * <p>
783       * Whether to use long ID's for anon resources.
784       * Short ID's are easier to read, but can run out of memory on very large models.
785       *
786       * @param value
787       *    The new value for this property.
788       * @return This object.
789       */
790      public SELF rdfxml_longId(boolean value) {
791         return jena("rdfXml.longId", value);
792      }
793
794      /**
795       * RDF/XML property: <c>relativeURIs</c>.
796       *
797       * <p>
798       * What sort of relative URIs should be used.
799       *
800       * <p>
801       * A comma separate list of options:
802       * <ul class='spaced-list'>
803       *    <li>
804       *       <js>"same-document"</js> - Same-document references (e.g. <js>""</js> or <js>"#foo"</js>)
805       *    <li>
806       *       <js>"network"</js>  - Network paths (e.g. <js>"//example.org/foo"</js> omitting the URI scheme)
807       *    <li>
808       *       <js>"absolute"</js> - Absolute paths (e.g. <js>"/foo"</js> omitting the scheme and authority)
809       *    <li>
810       *       <js>"relative"</js> - Relative path not beginning in <js>"../"</js>
811       *    <li>
812       *       <js>"parent"</js> - Relative path beginning in <js>"../"</js>
813       *    <li>
814       *       <js>"grandparent"</js> - Relative path beginning in <js>"../../"</js>
815       * </ul>
816       *
817       * <p>
818       * The default value is <js>"same-document, absolute, relative, parent"</js>.
819       * To switch off relative URIs use the value <js>""</js>.
820       * Relative URIs of any of these types are output where possible if and only if the option has been specified.
821       *
822       * @param value
823       *    The new value for this property.
824       * @return This object.
825       */
826      public SELF rdfxml_relativeUris(String value) {
827         return jena("rdfXml.relativeURIs", value);
828      }
829
830      /**
831       * RDF/XML property: <c>showXmlDeclaration</c>.
832       *
833       * <ul class='values spaced-list'>
834       *    <li>
835       *       <js>"true"</js> - Add XML Declaration to the output.
836       *    <li>
837       *       <js>"false"</js> - Don't add XML Declaration to the output.
838       *    <li>
839       *       <js>"default"</js> - Only add an XML Declaration when asked to write to an <c>OutputStreamWriter</c>
840       *       that uses some encoding other than <c>UTF-8</c> or <c>UTF-16</c>.
841       *       In this case the encoding is shown in the XML declaration.
842       * </ul>
843       *
844       * @param value
845       *    The new value for this property.
846       * @return This object.
847       */
848      public SELF rdfxml_showXmlDeclaration(String value) {
849         return jena("rdfXml.showXmlDeclaration", value);
850      }
851
852      /**
853       * RDF/XML property: <c>tab</c>.
854       *
855       * <p>
856       * The number of spaces with which to indent XML child elements.
857       *
858       * @param value
859       *    The new value for this property.
860       * @return This object.
861       */
862      public SELF rdfxml_tab(int value) {
863         return jena("rdfXml.tab", value);
864      }
865
866      /**
867       * RDF/XML property: <c>xmlbase</c>.
868       *
869       * <p>
870       * The value to be included for an <xa>xml:base</xa> attribute on the root element in the file.
871       *
872       * @param value
873       *    The new value for this property.
874       * @return This object.
875       */
876      public SELF rdfxml_xmlbase(String value) {
877         return jena("rdfXml.xmlbase", value);
878      }
879
880      /**
881       * Trim whitespace from text elements.
882       *
883       * <p>
884       * When enabled, whitespace in text elements will be automatically trimmed.
885       *
886       * <h4 class='section'>Example:</h4>
887       * <p class='bjava'>
888       *    <jc>// Create an RDF parser that trims whitespace.</jc>
889       *    ReaderParser <jv>parser</jv> = RdfParser
890       *       .<jsm>create</jsm>()
891       *       .xml()
892       *       .trimWhitespace()
893       *       .build();
894       * </p>
895       *
896       * @return This object.
897       */
898      public SELF trimWhitespace() {
899         return trimWhitespace(true);
900      }
901
902      /**
903       * Same as {@link #trimWhitespace()} but allows you to explicitly specify the value.
904       *
905       * @param value
906       *    The new value for this setting.
907       * @return This object.
908       */
909      public SELF trimWhitespace(boolean value) {
910         trimWhitespace = value;
911         return self();
912      }
913
914      /**
915       * Shortcut for calling <code>language(<jsf>LANG_TURTLE</jsf>)</code>.
916       *
917       * @return This object.
918       */
919      public SELF turtle() {
920         return language(Constants.LANG_TURTLE);
921      }
922
923      /**
924       * Shortcut for calling <code>language(<jsf>LANG_JSONLD</jsf>)</code>.
925       *
926       * @return This object.
927       */
928      public SELF jsonLd() {
929         return language(Constants.LANG_JSONLD);
930      }
931
932      /**
933       * Shortcut for calling <code>language(<jsf>LANG_NQUADS</jsf>)</code>.
934       *
935       * @return This object.
936       */
937      public SELF nQuads() {
938         return language(Constants.LANG_NQUADS);
939      }
940
941      /**
942       * Shortcut for calling <code>language(<jsf>LANG_TRIG</jsf>)</code>.
943       *
944       * @return This object.
945       */
946      public SELF triG() {
947         return language(Constants.LANG_TRIG);
948      }
949
950      /**
951       * Shortcut for calling <code>language(<jsf>LANG_TRIX</jsf>)</code>.
952       *
953       * @return This object.
954       */
955      public SELF triX() {
956         return language(Constants.LANG_TRIX);
957      }
958
959      /**
960       * Shortcut for calling <code>language(<jsf>LANG_RDFJSON</jsf>)</code>.
961       *
962       * @return This object.
963       */
964      public SELF rdfJson() {
965         return language(Constants.LANG_RDFJSON);
966      }
967
968
969      /**
970       * Shortcut for calling <code>language(<jsf>LANG_RDF_XML</jsf>)</code>.
971       *
972       * @return This object.
973       */
974      public SELF xml() {
975         return language(Constants.LANG_RDF_XML);
976      }
977
978      /**
979       * Shortcut for calling <code>language(<jsf>LANG_RDF_XML_ABBREV</jsf>)</code>.
980       *
981       * @return This object.
982       */
983      public SELF xmlabbrev() {
984         return language(Constants.LANG_RDF_XML_ABBREV);
985      }
986
987      SELF jena(String key, Object value) {
988         jenaSettings.put(key, value);
989         return self();
990      }
991   }
992
993   /**
994    * Concrete default builder leaf for the non-subclassed {@link RdfParser#create()} / {@link RdfParser#copy()} path.
995    */
996   public static final class DefaultBuilder extends Builder<DefaultBuilder> {
997
998      DefaultBuilder() {}
999
1000      DefaultBuilder(RdfParser copyFrom) {
1001         super(copyFrom);
1002      }
1003
1004      DefaultBuilder(Builder<?> copyFrom) {
1005         super(copyFrom);
1006      }
1007
1008      @Override /* Overridden from Context.Builder<?> */
1009      public DefaultBuilder copy() {
1010         return new DefaultBuilder(this);
1011      }
1012   }
1013
1014   /**
1015    * Creates a new builder for this object.
1016    *
1017    * @return A new builder.
1018    */
1019   @SuppressWarnings({
1020      "java:S1452", // Builder<?> wildcard return intentional; callers chain via fluent API without needing the concrete type
1021      "java:S9149" // Public Juneau DSL factory; hiding parent create() is intentional.
1022   })
1023   public static Builder<?> create() {
1024      return new DefaultBuilder();
1025   }
1026
1027   private static String getConsumes(Builder<?> builder) {
1028      if (nn(builder.getConsumes()))
1029         return builder.getConsumes();
1030      return switch (builder.language) {
1031         case "RDF/XML", "RDF/XML-ABBREV" -> "text/xml+rdf";
1032         case "N-TRIPLE" -> "text/n-triple";
1033         case "N3" -> "text/n3";
1034         case "N3-PP" -> "text/n3-pp";
1035         case "N3-PLAIN" -> "text/n3-plain";
1036         case "N3-TRIPLES" -> "text/n3-triples";
1037         case "TURTLE" -> "text/turtle";
1038         case "JSON-LD" -> "application/ld+json";
1039         case "N-QUADS" -> "application/n-quads";
1040         case "TRIG" -> "application/trig";
1041         case "TRIX" -> "application/trix+xml";
1042         case "RDF/JSON" -> "application/rdf+json";
1043         default -> "text/xml+rdf";
1044      };
1045   }
1046
1047   protected final boolean allowRemoteContexts;
1048   protected final boolean looseCollections;
1049   protected final boolean trimWhitespace;
1050   protected final Namespace juneauBpNs;
1051   protected final Namespace juneauNs;
1052   protected final RdfCollectionFormat collectionFormat;
1053   protected final String language;
1054
1055   final Map<String,Object> jenaSettings;
1056   private final Map<ClassMeta<?>,RdfClassMeta> rdfClassMetas = new ConcurrentHashMap<>();
1057   private final Map<BeanMeta<?>,RdfBeanMeta> rdfBeanMetas = new ConcurrentHashMap<>();
1058
1059   private final Map<BeanPropertyMeta,RdfBeanPropertyMeta> rdfBeanPropertyMetas = new ConcurrentHashMap<>();
1060   private final Map<ClassMeta<?>,XmlClassMeta> xmlClassMetas = new ConcurrentHashMap<>();
1061   private final Map<BeanMeta<?>,XmlBeanMeta> xmlBeanMetas = new ConcurrentHashMap<>();
1062
1063   private final Map<BeanPropertyMeta,XmlBeanPropertyMeta> xmlBeanPropertyMetas = new ConcurrentHashMap<>();
1064
1065   /**
1066    * Constructor.
1067    *
1068    * @param builder The builder for this object.
1069    *    <br>Cannot be <jk>null</jk>.
1070    */
1071   public RdfParser(Builder<?> builder) {
1072      super(builder.consumes(getConsumes(builder)));
1073
1074      allowRemoteContexts = builder.allowRemoteContexts;
1075      collectionFormat = builder.collectionFormat;
1076      juneauBpNs = builder.juneauBpNs;
1077      juneauNs = builder.juneauNs;
1078      language = builder.language;
1079      looseCollections = builder.looseCollections;
1080      trimWhitespace = builder.trimWhitespace;
1081      jenaSettings = new TreeMap<>(builder.jenaSettings);
1082   }
1083
1084   @Override /* Overridden from Context */
1085   public Builder<?> copy() {
1086      return new DefaultBuilder(this);
1087   }
1088
1089   @Override /* Overridden from Context */
1090   public RdfParserSession.Builder createSession() {
1091      return RdfParserSession.create(this);
1092   }
1093
1094   @Override /* Overridden from RdfMetaProvider */
1095   public RdfBeanMeta getRdfBeanMeta(BeanMeta<?> bm) {
1096      return rdfBeanMetas.computeIfAbsent(bm, k -> new RdfBeanMeta(k, this));
1097   }
1098
1099   @Override /* Overridden from RdfMetaProvider */
1100   public RdfBeanPropertyMeta getRdfBeanPropertyMeta(BeanPropertyMeta bpm) {
1101      return rdfBeanPropertyMetas.computeIfAbsent(bpm, k -> new RdfBeanPropertyMeta(k.getDelegateFor(), this));
1102   }
1103
1104   @Override /* Overridden from RdfMetaProvider */
1105   public RdfClassMeta getRdfClassMeta(ClassMeta<?> cm) {
1106      return rdfClassMetas.computeIfAbsent(cm, k -> new RdfClassMeta(k, this));
1107   }
1108
1109   @Override /* Overridden from Context */
1110   public RdfParserSession getSession() { return createSession().build(); }
1111
1112   @Override /* Overridden from XmlMetaProvider */
1113   public XmlBeanMeta getXmlBeanMeta(BeanMeta<?> bm) {
1114      return xmlBeanMetas.computeIfAbsent(bm, k -> new XmlBeanMeta(k, this));
1115   }
1116
1117   @Override /* Overridden from XmlMetaProvider */
1118   public XmlBeanPropertyMeta getXmlBeanPropertyMeta(BeanPropertyMeta bpm) {
1119      return xmlBeanPropertyMetas.computeIfAbsent(bpm, k -> new XmlBeanPropertyMeta(k.getDelegateFor(), this));
1120   }
1121
1122   @Override /* Overridden from XmlMetaProvider */
1123   public XmlClassMeta getXmlClassMeta(ClassMeta<?> cm) {
1124      return xmlClassMetas.computeIfAbsent(cm, k -> new XmlClassMeta(k, this));
1125   }
1126
1127   /**
1128    * RDF format for representing collections and arrays.
1129    *
1130    * @see RdfParser.Builder#collectionFormat(RdfCollectionFormat)
1131    * @return
1132    *    RDF format for representing collections and arrays.
1133    */
1134   protected final RdfCollectionFormat getCollectionFormat() { return collectionFormat; }
1135
1136   /**
1137    * All Jena-related configuration properties.
1138    *
1139    * @return
1140    *    A map of all Jena-related configuration properties.
1141    */
1142   protected final Map<String,Object> getJenaSettings() { return u(jenaSettings); }
1143
1144   /**
1145    * Default XML namespace for bean properties.
1146    *
1147    * @see RdfParser.Builder#juneauBpNs(Namespace)
1148    * @return
1149    *    Default XML namespace for bean properties.
1150    */
1151   protected final Namespace getJuneauBpNs() { return juneauBpNs; }
1152
1153   /**
1154    * XML namespace for Juneau properties.
1155    *
1156    * @see RdfParser.Builder#juneauNs(Namespace)
1157    * @return
1158    *    XML namespace for Juneau properties.
1159    */
1160   protected final Namespace getJuneauNs() { return juneauNs; }
1161
1162   /**
1163    * RDF language.
1164    *
1165    * @see RdfParser.Builder#language(String)
1166    * @return
1167    *    The RDF language to use.
1168    */
1169   protected final String getLanguage() { return language; }
1170
1171   /**
1172    * Collections should be serialized and parsed as loose collections.
1173    *
1174    * @see RdfParser.Builder#looseCollections()
1175    * @return
1176    *    <jk>true</jk> if collections of resources are handled as loose collections of resources in RDF instead of
1177    *    resources that are children of an RDF collection (e.g. Sequence, Bag).
1178    */
1179   protected final boolean isLooseCollections() { return looseCollections; }
1180
1181   /**
1182    * Trim whitespace from text elements.
1183    *
1184    * @see RdfParser.Builder#trimWhitespace()
1185    * @return
1186    *    <jk>true</jk> if whitespace in text elements will be automatically trimmed.
1187    */
1188   protected final boolean isTrimWhitespace() { return trimWhitespace; }
1189
1190   @Override /* Overridden from ReaderParser */
1191   protected FluentMap<String,Object> properties() {
1192      return super.properties()
1193         .a("collectionFormat", collectionFormat)
1194         .a("juneauBpNs", juneauBpNs)
1195         .a("juneauNs", juneauNs)
1196         .a("language", language)
1197         .a("looseCollections", looseCollections)
1198         .a("trimWhitespace", trimWhitespace);
1199   }
1200}