Convertor (Convertor) - NetBeans API Javadoc (Current Development Version)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.netbeans.modules.convertor/1 1.3

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.netbeans.spi.convertor
Interface Convertor

public interface Convertor

Base interface for object conversion to XML namespace aware fragment and conversion of this fragment back to the object.

Inseparatable part of the convertor is its declarative registration which must be done in JAR Manifest. The example of such registration is:

Name: com/yourdomain/YourConvertor.class NetBeans-Convertor: {yournamespace}yourelement, yourclass

where

Name: is fully qualified name of the class of your convertor, that is class implementing Convertor interface

NetBeans-Convertor: declaration of your convertor

yournamespace is XML namespace which your convertor is capable to read

yourelement is element name from the XML namespace which your convertor is capable to read

yourclass is fully qualified name of the class which instances (but not subclasses!) is your convertor capable to persist. This is the only attribute which is optional and if omitted it means that your convertor is not capable to persist any class.

The Convertor infrastructure will use the information from manifest to create instance of your convertor and will call your convertor only with parameters matching the declared criteria.

It is guaranteed that read(org.w3c.dom.Element) method will be called only with element from the declared namespace and with the declared name. The object created by read method does not have to be assignable to class in NetBeans-Convertor attribute. It can be object of any type.

It is guaranteed that write(org.w3c.dom.Document, java.lang.Object) method will be called only if the object's class is equal to class declared in NetBeans-Convertor attribute and only if the convertor's classloader is equal to, or a descendant of, the classloader used to load the object's class. If NetBeans-Convertor attribute does not specify class name the write method will never be called. The element created by write method is not constrained by the value of NetBeans-Convertor attribute. It can be element with arbitrary name and namespace.

The JAR Manifest can contain multiple convertors. One convertor can be registered for multiple namespaces/elements. In such a case the name of the NetBeans-Convertor attribute must be suffixed by "-" and number, eg.:

Name: com/yourdomain/YourConvertor.class NetBeans-Convertor: {yourdomain.com/firstns}firstelement, com.yourdomain.FirstClass NetBeans-Convertor-2: {yourdomain.com/secondns}secondreadonlyelement NetBeans-Convertor-3: {yourdomain.com/thirdns}thirdelement, com.yourdomain.ThirdClass

Recommendations for convertor implementors:

It is strongly recommended to keep all details of the Java memory representation (implementation class names, field names, etc.) out of the storage format. Otherwise you run into the problems whenever you refactor the implementation class internally.

See also SimplyConvertible for information about how to persist your object without writing your own Convertor.

Method Summary

Object read(Element element)
Creates object from the element.

Element write(Document doc, Object inst)
Converts the object to element.

Method Summary
`Object`	`read(Element element)` Creates object from the element.
`Element`	`write(Document doc, Object inst)` Converts the object to element.

Method Detail

read

Object read(Element element)

Creates object from the element.

Parameters:: element - element which namespace and name will correspond to the namespace and name with which this convertor was registered
Returns:: instance of the object created from the element; cannot be null; can be of arbitrary type
Throws:: ConvertorException - can throw this exception when there is runtime problem with conversion of element to object

write

Element write(Document doc,
              Object inst)

Converts the object to element. This method will be only called when NetBeans-Convertor attribute declares a class.

Parameters:: doc - document to which the returned element should belong; inst - object to convert; the class of the instance will be always equal to the class specified in NetBeans-Convertor attribute
Returns:: element describing converted object; cannot be null; returned element can be of any name and namespace
Throws:: ConvertorException - can throw this exception when there is runtime problem with conversion of object to element