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 a {@link RdfJsonSerializer} and {@link RdfJsonParser} into a single class with convenience to/of methods.
027 *
028 * <h5 class='figure'>Examples:</h5>
029 * <p class='bjava'>
030 *    <jc>// Serialize a bean or map to RDF/JSON</jc>
031 *    String <jv>rdfJson</jv> = RdfJson.<jsm>of</jsm>(<jv>myBean</jv>);
032 *
033 *    <jc>// Parse RDF/JSON into a bean or map</jc>
034 *    MyPojo <jv>parsed</jv> = RdfJson.<jsm>to</jsm>(<jv>rdfJson</jv>, MyPojo.<jk>class</jk>);
035 * </p>
036 * <p class='bjava'>
037 *    <jc>// Using instance methods</jc>
038 *    RdfJson <jv>m</jv> = RdfJson.<jsf>DEFAULT</jsf>;
039 *    <jv>rdfJson</jv> = <jv>m</jv>.write(<jv>myBean</jv>);
040 *    <jv>parsed</jv> = <jv>m</jv>.read(<jv>rdfJson</jv>, MyPojo.<jk>class</jk>);
041 * </p>
042 *
043 * <h5 class='figure'>Example output (bean with name/age, RDF/JSON format):</h5>
044 * <p class='bjson'>
045 *    { <js>"&lt;subject&gt;"</js>: { <js>"&lt;.../name&gt;"</js>: [{ <js>"value"</js>: <js>"Alice"</js> }],
046 *       <js>"&lt;.../age&gt;"</js>: [{ <js>"value"</js>: 30, <js>"type"</js>: <js>"literal"</js> }] } }
047 * </p>
048 *
049 * <h5 class='figure'>Complex (nested address + array):</h5>
050 * <p class='bjson'>
051 *    { <js>"&lt;...&gt;"</js>: { <js>"&lt;.../name&gt;"</js>: [{ <js>"value"</js>: <js>"Alice"</js> }],
052 *       <js>"&lt;.../address&gt;"</js>: [{ <js>"type"</js>: <js>"uri"</js>, <js>"value"</js>: <js>".../address"</js> }] },
053 *      <js>"&lt;.../address&gt;"</js>: { <js>"&lt;.../street&gt;"</js>: [{ <js>"value"</js>: <js>"123 Main St"</js> }],
054 *       <js>"&lt;.../city&gt;"</js>: [{ <js>"value"</js>: <js>"Boston"</js> }], <js>"&lt;.../state&gt;"</js>: [{ <js>"value"</js>: <js>"MA"</js> }] } }
055 * </p>
056 *
057 * <p class='bjava'>
058 * <jc>// Using static shortcuts.</jc>
059 *    MyPojo <jv>myPojo</jv> = RdfJson.<jsm>to</jsm>(<jv>string</jv>, MyPojo.<jk>class</jk>);
060 *    String <jv>string</jv> = RdfJson.<jsm>of</jsm>(<jv>myPojo</jv>);
061 * </p>
062 *
063 * <h5 class='section'>See Also:</h5><ul>
064 *    <li class='link'>{doc jmr.RdfDetails}
065 *    <li class='link'>{doc jm.Marshallers}
066 * </ul>
067 */
068public class RdfJson extends CharMarshaller {
069
070   /** Default reusable instance.*/
071   public static final RdfJson DEFAULT = new RdfJson();
072
073   /**
074    * Serializes a POJO to a <c>String</c> using the {@link #DEFAULT} marshaller.
075    *
076    * <p>
077    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>.
078    *
079    * @param object The object to serialize.
080    * @return The serialized object.
081    * @throws SerializeException If a problem occurred trying to convert the output.
082    */
083   public static String of(Object object) throws SerializeException {
084      return DEFAULT.write(object);
085   }
086
087   /**
088    * Parses an input into the specified object type using the {@link #DEFAULT} marshaller.
089    *
090    * <p>
091    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>.
092    *
093    * @param <T> The class type of the object being created.
094    * @param input The input.
095    * @param type The object type to create.
096    * @return The parsed object.
097    * @throws ParseException Malformed input encountered.
098    */
099   public static <T> T to(String input, Class<T> type) throws ParseException {
100      return DEFAULT.read(input, type);
101   }
102
103   /**
104    * Parses an input into the specified parameterized object type using the {@link #DEFAULT} marshaller.
105    *
106    * <p>
107    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>.
108    *
109    * @param <T> The class type of the object to create.
110    * @param input The input.
111    * @param type The object type to create.
112    * @param args The type arguments of the class if it's a collection or map.
113    * @return The parsed object.
114    * @throws ParseException Malformed input encountered.
115    */
116   public static <T> T to(String input, Type type, Type... args) throws ParseException {
117      return DEFAULT.read(input, type, args);
118   }
119
120   /** Constructor using defaults.*/
121   public RdfJson() {
122      this(RdfJsonSerializer.DEFAULT, RdfJsonParser.DEFAULT);
123   }
124
125   /**
126    * Constructor with serializer and parser.
127    *
128    * @param s The serializer to use.
129    *    <br>Must not be <jk>null</jk>.
130    * @param p The parser to use.
131    *    <br>Must not be <jk>null</jk>.
132    */
133   public RdfJson(RdfJsonSerializer s, RdfJsonParser p) {
134      super(s, p);
135   }
136}