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