The Convertor SPI defines interface describing the convertor.

Content

Writing your first convertor
Using SimplyConvertible instead of writing convertor
Existing convertors
SPI in details

Writing your first convertor

Implementing a convertor is fairly simple task. Two things must be done:

Learn by example

1.) let say you have an object like this:

  package com.mycompany.book;

  class Book {

    private String author;
    private String title;

    public Book(String author, String title) { ... };
 
    public String getAuthor() { ... };
    public void setAuthor(String author) { ... };

    public String getTitle() { ... };
    public void setTitle(String title) { ... };

  }  

2.) make up a unique namespace identifier and root element name

  String NAMESPACE = "http://www.mycompany.com/namespace/book";
  String ELEMENT = "book";

3.) implement Convertor interface. It has two methods which implementation is straightforward

  package com.mycompany.book;

  public class BookConvertor implements Convertor {
 
    public BookConvertor() {
    }
   
    public Object read(Element element) {
      String author;
      String title;

      // read author and title from element or its child elements
      // whatever way you store it and like it

      return new Book(author, title);
    }
       
    public Element write(Document doc, Object inst) {
      Book book = (Book)inst;
      Element element = doc.createElementNS(NAMESPACE, BOOK);
          
      // write author and title whatever way you prefer
      // to the element and return that element
          
      return element;
    }
       
  }

The example of fully working simple convertor can be found at:
4.) register your convertor to the system

The convertor is registered in JAR Manifest by following lines:

  Name: com/mycompany/book/BookConvertor.class
  NetBeans-Convertor: {http://www.mycompany.com/namespace/book}book, com.mycompany.book.Book

This declarative registration gives system all the necessary information about input and output of your convertor and how to instantiate it. And that's all. Now you can convert your Book instances as described in API package overview or by some other APIs like Registry API.

The more details about Convertor interface, its semantics and JAR Manifest registration can be found in Javadoc for Convertor class.

Other examples

Other examples can be found in unit tests. In folder openide/convertor/test/unit/src/org/netbeans/api/convertor/data can be found Ant build script for building three separate JARs each containing one convertor example and its registration. There is also example of usage of SimplyConvertible and compound convertor which are discussed in next chapters.

Using SimplyConvertible instead of writing convertor

SimplyConvertible is way how to persist object without implementing your own convertor.

Learn by example

1.) let say we have the same Book object as defined in chapter before.

In order to make the object persistable the class must implement SimplyConvertible interface and two of its methods. Below is code which has to be added to Book class:

  class Book implements SimplyConvertible {
   
    private static final String AUTHOR = "author";
    private static final String TITLE = "title";
       
    public void read(Properties p) {
      author = p.getProperty(AUTHOR);
      title = p.getProperty(TITLE);
    }
     
    public void write(Properties p) {
      p.setProperty(AUTHOR, author);
      p.setProperty(TITLE, title);
    }

    // and the rest ...
  }  

2.) make up a unique namespace identifier and root element name

  String NAMESPACE = "http://www.mycompany.com/namespace/book2";
  String ELEMENT = "book2";

3.) register your SimplyConvertible object to the system

  Name: com/mycompany/book/Book.class
  NetBeans-Simply-Convertible: {http://www.mycompany.com/namespace/book2}book2

That's all. The resulting persistent format of a book instance will look like:

<book2 xmlns="http://www.mycompany.com/namespace/book2">
    <author>A Book Author</author>
    <title>A Book Title</title>
</book2> 

The example of fully working SimplyConvertible example can be found at:
The more details about SimplyConvertible interface, its semantics and JAR Manifest registration can be found in Javadoc for SimplyConvertible class.

Existing convertors

The Convertor module provides at the moment one additional convertor for general usage: Instance convertor.

Instance convertor

This convertor allows easy way to register immutable instances to the system because it does not support saving. There are four possible usages:

1.) instantiate class by its public default constructor:

<instance xmlns="http://www.netbeans.org/ns/registry">
    <class>com.mycompany.SomeClass</class>
</instance>
 
2.) instantiate class by calling a public static factory method:

<instance xmlns="http://www.netbeans.org/ns/registry">
    <method>com.mycompany.SomeClass.getDefault</method>
</instance>

The object created by this method does not have to be assignable to the class of the static factory method.

3.) instantiate class by its public constructor with Properties parameter:

<instance xmlns="http://www.netbeans.org/ns/registry">
    <class>com.mycompany.SomeClass</class>
    <property name="prop1">Value of Prop1</property>
    <property name="prop2">Value of Prop2</property>
</instance>
 
The key-value pairs specified by <property> tags will be parsed and put into Properties instance passed to the constructor.

4.) instantiate class by calling a public static factory method with Properties parameter

Same as in #3 only the method is called instead of constructor. Again, the object created by this method does not have to be assignable to the class of the static factory method.

SPI in details

Are compound convertors supported?

There is no explicit support for them, but compound convertor can be easily written using the existing Convertors API. See compound convertor examples at: