Coverage Report - org.simpleframework.xml.core.Converter
 
Classes in this File Line Coverage Branch Coverage Complexity
Converter
N/A
N/A
1
 
 1  
 /*
 2  
  * Converter.java July 2006
 3  
  *
 4  
  * Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
 5  
  *
 6  
  * Licensed under the Apache License, Version 2.0 (the "License");
 7  
  * you may not use this file except in compliance with the License.
 8  
  * You may obtain a copy of the License at
 9  
  *
 10  
  *     http://www.apache.org/licenses/LICENSE-2.0
 11  
  *
 12  
  * Unless required by applicable law or agreed to in writing, software
 13  
  * distributed under the License is distributed on an "AS IS" BASIS,
 14  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
 15  
  * implied. See the License for the specific language governing 
 16  
  * permissions and limitations under the License.
 17  
  */
 18  
 
 19  
 package org.simpleframework.xml.core;
 20  
 
 21  
 import org.simpleframework.xml.stream.InputNode;
 22  
 import org.simpleframework.xml.stream.OutputNode;
 23  
 
 24  
 /**
 25  
  * The <code>Converter</code> object serializes and deserializes XML
 26  
  * elements. Serialization of lists, primitives, and compound types 
 27  
  * are performed using a converter. Any object read from a converter
 28  
  * will produce a fully deserialized object will all its fields. 
 29  
  * The objects written to an XML element populate that element with 
 30  
  * attributes an elements according to the objects annotations.
 31  
  * 
 32  
  * @author Niall Gallagher
 33  
  */
 34  
 interface Converter {
 35  
 
 36  
    /**
 37  
     * The <code>read</code> method reads an object to a specific type
 38  
     * from the provided node. If the node provided is an attribute
 39  
     * then the object must be a primitive such as a string, integer,
 40  
     * boolean, or any of the other Java primitive types.  
 41  
     * 
 42  
     * @param node contains the details used to deserialize the object
 43  
     * 
 44  
     * @return a fully deserialized object will all its fields 
 45  
     * 
 46  
     * @throws Exception if a deserialized type cannot be instantiated
 47  
     */
 48  
    Object read(InputNode node) throws Exception; 
 49  
    
 50  
    /**
 51  
     * The <code>read</code> method reads an object to a specific type
 52  
     * from the provided node. If the node provided is an attribute
 53  
     * then the object must be a primitive such as a string, integer,
 54  
     * boolean, or any of the other Java primitive types.  
 55  
     * 
 56  
     * @param node contains the details used to deserialize the object
 57  
     * @param value this is an existing value to deserialize in to
 58  
     * 
 59  
     * @return a fully deserialized object will all its fields 
 60  
     * 
 61  
     * @throws Exception if a deserialized type cannot be instantiated
 62  
     */
 63  
    Object read(InputNode node, Object value) throws Exception; 
 64  
    
 65  
    /**
 66  
     * The <code>validate</code> method is used to validate the class
 67  
     * XML schema against an input source. This will traverse the class
 68  
     * fields and methods ensuring that the input XML document contains
 69  
     * a valid structure when compared against the class XML schema.
 70  
     * 
 71  
     * @param node contains the details used to validate the object
 72  
     * 
 73  
     * @return true if the document matches the class XML schema 
 74  
     * 
 75  
     * @throws Exception if the class XML schema does not fully match
 76  
     */
 77  
    boolean validate(InputNode node) throws Exception;
 78  
    
 79  
    /**
 80  
     * The <code>write</code> method writes the fields from the given 
 81  
     * object to the XML element. After this has finished the element
 82  
     * contains all attributes and sub-elements from the object.
 83  
     * 
 84  
     * @param object this is the object to be written to the element
 85  
     * @param node this is the element that is to be populated
 86  
     * 
 87  
     * @throws Exception throw if the object cannot be serialized
 88  
     */
 89  
    void write(OutputNode node, Object object) throws Exception;
 90  
 }