KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > spi > convertor > SimplyConvertible


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.netbeans.spi.convertor;
21
22 import java.util.Properties JavaDoc;
23
24 /**
25  * SimplyConvertible is way how to persist your object by Convertor infrastructure
26  * without writing any convertor.
27  *
28  * <p>Three things must be done to make this happen:
29  * <lu>
30  * <li>your class must have public default constructor</li>
31  * <li>your class must implement SimplyConvertible interface</li>
32  * <li>you must register your class in JAR Manifest</li>
33  * </lu>
34  *
35  * <p>Default public constructor is necessary because Convertor infrastructure will
36  * use it to create instance of your class.
37  *
38  * <p>SimplyConvertible interface has two methods. The {@link #write} method
39  * will be called on your object whenever your instance needs to be persist. The
40  * method will pass you empty {@link java.util.Properties} object to which you
41  * can store all relevant data of your instance. All String properties will be
42  * then persisted by the Convertor infrastructure. Second method is {@link #read}
43  * method which does opposite. Instance of your class is first created by
44  * default constructor and then this method will pass you Properties object
45  * with all properties which you stored in write() method. That allows you to
46  * reinitialize your instance to the state before it was persisted.
47  * The Convertor infrastructure guarantees that it will not call the read()
48  * method more than once and it will call it immediatelly after the instance
49  * was created by your default constructor.
50  *
51  * <p>The Properties object content will be persisted as XML namespace aware
52  * fragment with following structure:
53  *
54  * <p><code>
55  * &nbsp;&lt;yourelement xmlns="yournamespace"&gt;<br>
56  * &nbsp;&nbsp;&lt;propertykey1&gt;propertyvalue1&lt;/propertykey1&gt;<br>
57  * &nbsp;&nbsp;&lt;propertykey2&gt;propertyvalue2&lt;/propertykey2&gt;<br>
58  * &nbsp;&nbsp;&lt;propertykeyN&gt;propertyvalueN&lt;/propertykeyN&gt;<br>
59  * &nbsp;&lt;/yourelement&gt;<br>
60  * </code>
61  *
62  * <p>Property keys are used as XML element names and so the
63  * same restrictions as for XML element names are valid for property keys.
64  * Similarly the property values need to be valid XML text content (i.e. no
65  * control characters, newlines will be normalized, etc.). Invalid property
66  * key or property value will result in runtime
67  * {@link org.netbeans.api.convertor.ConvertorException}. The XML elements
68  * are created in lexicographical order according to property keys.
69  *
70  * <p>Declarative registration looks like:
71  *
72  * <p><code>
73  * &nbsp;Name: com/yourdomain/YourClass.class<br>
74  * &nbsp;NetBeans-Simply-Convertible: {yournamespace}yourelement<br>
75  * </code>
76  *
77  * <p>where
78  *
79  * <p><lu>
80  * <li><code>Name:</code> is fully qualified name of your class which
81  * implements SimplyConvertible interface</li>
82  * <li><code>NetBeans-Simply-Convertible:</code> declaration of simply
83  * convertible</li>
84  * <li><code>yournamespace</code> is XML namespace
85  * to which your class will be persisted</li>
86  * <li><code>yourelement</code> is element name
87  * to which your class will be persisted</li>
88  *</lu>
89  *
90  * <p>Although it was said that simply convertible object must implement
91  * SimplyConvertible interface there are cases when this is not desirable and
92  * so it does not have implement it. For example it might be desirable to hide
93  * fact that object is simply convertible when object is part of an API contract.
94  * In such a case you do not have to implement SimplyConvertible interface.
95  * However your object must have two methods with the same signatures
96  * as SimplyConvertible methods have and default constructor. The methods
97  * and constructor do not have to have public access.
98  *
99  * <p>See also {@link Convertor} for information about how to write regular
100  * convertor.
101  *
102  * @author David Konecny
103  */
104 public interface SimplyConvertible {
105     
106     /**
107      * Read object state from the given Properties instance.
108      * The method will be called only once by Convertor infrastructure just
109      * after the instance was created by default constructor.
110      *
111      * @param p properties instance with properties stored by write() method
112      * @throws org.netbeans.api.convertor.ConvertorException can throw this
113      * exception when content of Properties instance is malformed
114      */
115     void read(Properties JavaDoc p);
116
117     /**
118      * Write object state to the given Properties instance.
119      * The Convertor infrastructure will take care about persistence of
120      * content of Properties instance. Non-String properties are forbidden.
121      * For naming restrictions on property keys and values see the class Javadoc.
122      *
123      * @param p empty properties instance for the data to be persisted
124      */
125     void write(Properties JavaDoc p);
126     
127 }
128
Popular Tags