站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > NetBeans API Javadoc (Current Development Version)

org.netbeans.spi.convertor (Convertor) - NetBeans API Javadoc (Current Development Version)

Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
org.netbeans.modules.convertor/1 1.3
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    

Package org.netbeans.spi.convertor

The Convertor SPI defines interface describing the convertor.

See:
          Description

Interface Summary
Convertor Base interface for object conversion to XML namespace aware fragment and conversion of this fragment back to the object.
SimplyConvertible SimplyConvertible is way how to persist your object by Convertor infrastructure without writing any convertor.
 

Package org.netbeans.spi.convertor Description

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:

Overview   Package  Class  Use  Tree  Deprecated  Index  Help 
org.netbeans.modules.convertor/1 1.3
 PREV PACKAGE   NEXT PACKAGE FRAMES    NO FRAMES    
Built on May 28 2007.  |  Portions Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.