Convertor


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 org.w3c.dom.Document  ;
23  import org.w3c.dom.Element  ;
24  
25  /**
26   * Base interface for object conversion to XML namespace aware fragment
27   * and conversion of this fragment back to the object.
28   *
29   * <p>Inseparatable part of the convertor is its declarative registration which
30   * must be done in JAR Manifest. The example of such registration is:
31   *
32   * <p><code>
33   *  &nbsp;Name: com/yourdomain/YourConvertor.class<br>
34   *  &nbsp;NetBeans-Convertor: {yournamespace}yourelement, yourclass
35   * </code>
36   *
37   * <p>where
38   *
39   * <p><lu>
40   *   <li><code>Name:</code> is fully qualified name of the class of your convertor,
41   *         that is class implementing Convertor interface</li>
42   *   <li><code>NetBeans-Convertor:</code> declaration of your convertor</li>
43   *   <li><code>yournamespace</code> is XML namespace which
44   *       your convertor is capable to read</li>
45   *   <li><code>yourelement</code> is element name from 
46   *       the XML namespace which your convertor is capable to read</li>
47   *   <li><code>yourclass</code> is fully qualified name of the 
48   *       class which instances (but not subclasses!) is your convertor capable to 
49   *       persist. This is the only attribute which is optional and if omitted it means 
50   *       that your convertor is not capable to persist any class.</li>
51   *</lu>
52   *
53   * <p>The Convertor infrastructure will use the information from manifest to 
54   * create instance of your convertor and will call your convertor only with parameters
55   * matching the declared criteria.
56   *
57   * <p>It is guaranteed that {@link #read} method will be
58   * called only with element from the declared namespace and with the
59   * declared name. The object created by read method does not have to be
60   * assignable to class in NetBeans-Convertor attribute. It can be
61   * object of any type.
62   *
63   * <p>It is guaranteed that {@link #write} method will be called only
64   * if the object's class is equal to class declared in NetBeans-Convertor
65   * attribute and only if the convertor's classloader is equal to, 
66   * or a descendant of, the classloader used to load the object's class.
67   * If NetBeans-Convertor attribute does not specify class name the write method will
68   * never be called. The element created by write method is not constrained by
69   * the value of NetBeans-Convertor attribute. It can be element with arbitrary
70   * name and namespace.
71   *
72   * <p>The JAR Manifest can contain multiple convertors. One convertor can be
73   * registered for multiple namespaces/elements. In such a case the name of 
74   * the <code>NetBeans-Convertor</code> attribute must be suffixed by "-" and 
75   * number, eg.:
76   *
77   * <p><code> 
78   *  &nbsp;Name: com/yourdomain/YourConvertor.class<br>
79   *  &nbsp;NetBeans-Convertor: {yourdomain.com/firstns}firstelement, com.yourdomain.FirstClass<br>
80   *  &nbsp;NetBeans-Convertor-2: {yourdomain.com/secondns}secondreadonlyelement<br>
81   *  &nbsp;NetBeans-Convertor-3: {yourdomain.com/thirdns}thirdelement, com.yourdomain.ThirdClass
82   * </code>
83   *
84   * <p><strong>Recommendations for convertor implementors:</strong><br>
85   * <lu>
86   *   <li>It is strongly recommended to keep all details of the Java memory 
87   *         representation (implementation class names, field names, etc.)
88   *         out of the storage format. Otherwise you run into the problems 
89   *         whenever you refactor the implementation class internally.</li>
90   * </lu>
91   *
92   * <p>See also {@link SimplyConvertible} for information about how to persist
93   * your object without writing your own Convertor.
94   *
95   * @author  David Konecny
96   */
97  public interface Convertor {
98      
99      /**
100      * Creates object from the element.
101      *
102      * @param element element which namespace and name will correspond to
103      *     the namespace and name with which this convertor was registered
104      * @return instance of the object created from the element; cannot be null;
105      *    can be of arbitrary type
106      * @throws org.netbeans.api.convertor.ConvertorException can throw this 
107      *     exception when there is runtime problem with conversion of element
108      *     to object
109      */
110     Object   read(Element   element);
111     
112     /** 
113      * Converts the object to element. This method will be only called
114      * when NetBeans-Convertor attribute declares a class.
115      *
116      * @param doc document to which the returned element should belong
117      * @param inst object to convert; the class of the instance will be always
118      *     equal to the class specified in NetBeans-Convertor attribute
119      * @return element describing converted object; cannot be null;
120      *     returned element can be of any name and namespace
121      * @throws org.netbeans.api.convertor.ConvertorException can throw this 
122      *     exception when there is runtime problem with conversion of object 
123      *     to element
124      */
125     Element   write(Document   doc, Object   inst);
126 
127 }
128
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags