/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2003 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.netbeans.spi.convertor;

import java.util.Properties;

/** 
 * SimplyConvertible is way how to persist your object by Convertor infrastructure
 * without writing any convertor. 
 *
 * 
Three things must be done to make this happen:
 * 
 *    
your class must have public default constructor
 *    
your class must implement SimplyConvertible interface
 *    
you must register your class in JAR Manifest
 * 
 *
 * 
Default public constructor is necessary because Convertor infrastructure will
 * use it to create instance of your class.
 *
 * 
SimplyConvertible interface has two methods. The {@link #write} method
 * will be called on your object whenever your instance needs to be persist. The
 * method will pass you empty {@link java.util.Properties} object to which you
 * can store all relevant data of your instance. All String properties will be
 * then persisted by the Convertor infrastructure. Second method is {@link #read}
 * method which does opposite. Instance of your class is first created by
 * default constructor and then this method will pass you Properties object
 * with all properties which you stored in write() method. That allows you to
 * reinitialize your instance to the state before it was persisted.
 * The Convertor infrastructure guarantees that it will not call the read()
 * method more than once and it will call it immediatelly after the instance 
 * was created by your default constructor.
 *
 * 
The Properties object content will be persisted as XML namespace aware
 * fragment with following structure:
 *
 * 
 
 *  <yourelement xmlns="yournamespace">

 *   <propertykey1>propertyvalue1</propertykey1>

 *   <propertykey2>propertyvalue2</propertykey2>

 *   <propertykeyN>propertyvalueN</propertykeyN>

 *  </yourelement>

 *  
 *
 * 
Property keys are used as XML element names and so the
 * same restrictions as for XML element names are valid for property keys.
 * Similarly the property values need to be valid XML text content (i.e. no
 * control characters, newlines will be normalized, etc.).  Invalid property 
 * key or property value will result in runtime 
 * {@link org.netbeans.api.convertor.ConvertorException}. The XML elements 
 * are created in lexicographical order according to property keys.
 *
 * 
Declarative registration looks like:
 *
 * 
 
 *   Name: com/yourdomain/YourClass.class

 *   NetBeans-Simply-Convertible: {yournamespace}yourelement

 * 
 *
 * 
where
 *
 * 

 *   
Name: is fully qualified name of your class which 
 *         implements SimplyConvertible interface
 *   
NetBeans-Simply-Convertible: declaration of simply
 *          convertible
 *   
yournamespace is XML namespace
 *          to which your class will be persisted
 *   
yourelement is element name
 *          to which your class will be persisted
 *
 *
 * 
Although it was said that simply convertible object must implement 
 * SimplyConvertible interface there are cases when this is not desirable and
 * so it does not have implement it. For example it might be desirable to hide
 * fact that object is simply convertible when object is part of an API contract.
 * In such a case you do not have to implement SimplyConvertible interface.
 * However your object must have two methods with the same signatures
 * as SimplyConvertible methods have and default constructor. The methods
 * and constructor do not have to have public access.
 * 
 * 
See also {@link Convertor} for information about how to write regular 
 * convertor.
 *
 * @author  David Konecny
 */
public interface SimplyConvertible {
    
    /**
     * Read object state from the given Properties instance.
     * The method will be called only once by Convertor infrastructure just
     * after the instance was created by default constructor.
     *
     * @param p properties instance with properties stored by write() method
     * @throws org.netbeans.api.convertor.ConvertorException can throw this 
     *     exception when content of Properties instance is malformed
     */    
    void read(Properties p);

    /**
     * Write object state to the given Properties instance.
     * The Convertor infrastructure will take care about persistence of
     * content of Properties instance. Non-String properties are forbidden.
     * For naming restrictions on property keys see the class Javadoc.
     *
     * @param p empty properties instance for the data to be persisted
     */    
    void write(Properties p);
    
}