001/*
002 * Converter.java January 2010
003 *
004 * Copyright (C) 2010, Niall Gallagher <niallg@users.sf.net>
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
015 * implied. See the License for the specific language governing 
016 * permissions and limitations under the License.
017 */
018
019package org.simpleframework.xml.convert;
020
021import org.simpleframework.xml.stream.InputNode;
022import org.simpleframework.xml.stream.OutputNode;
023
024/**
025 * The <code>Converter</code> object is used to convert an object
026 * to XML by intercepting the normal serialization process. When
027 * serializing an object the <code>write</code> method is invoked.
028 * This is provided with the object instance to be serialized and
029 * the <code>OutputNode</code> to use to write the XML. Values
030 * can be taken from the instance and transferred to the node.
031 * <p>
032 * For deserialization the <code>read</code> method is invoked.
033 * This is provided with the <code>InputNode</code>, which can be
034 * used to read the elements and attributes representing the 
035 * member data of the object being deserialized. Once the object
036 * has been instantiated it must be returned. 
037 * 
038 * @author Niall Gallagher
039 * 
040 * @see org.simpleframework.xml.convert.AnnotationStrategy
041 * @see org.simpleframework.xml.convert.RegistryStrategy
042 */
043public interface Converter<T> {
044
045   /**
046    * This <code>read</code> method is used to deserialize an object
047    * from the source XML. The deserialization is performed using 
048    * the XML node provided. This node can be used to read the XML
049    * elements and attributes in any format required. Once all of 
050    * the data has been extracted an instance must be returned.
051    * 
052    * @param node this is the node to deserialize the object from
053    * 
054    * @return the object instance resulting from the deserialization
055    */
056   T read(InputNode node) throws Exception; 
057
058   /**
059    * This <code>write</code> method is used to serialize an object
060    * to XML. The serialization should be performed in such a way
061    * that all of the objects values are represented by an element
062    * or attribute of the provided node. This ensures that it can
063    * be fully deserialized at a later time.
064    * 
065    * @param node this is the node to serialized to object to
066    * @param value this is the value that is to be serialized
067    */
068   void write(OutputNode node, T value) throws Exception;
069}