SimplyConvertible (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 SimplyConvertible

public interface SimplyConvertible

SimplyConvertible is way how to persist your object by Convertor infrastructure without writing any convertor.

Three things must be done to make this happen:

your class must have public default constructor

your class must implement SimplyConvertible interface

you must register your class in JAR Manifest

Default public constructor is necessary because Convertor infrastructure will use it to create instance of your class.

SimplyConvertible interface has two methods. The write(java.util.Properties) method will be called on your object whenever your instance needs to be persist. The method will pass you empty Properties object to which you can store all relevant data of your instance. All String properties will be then persisted by the Convertor infrastructure. Second method is read(java.util.Properties) method which does opposite. Instance of your class is first created by default constructor and then this method will pass you Properties object with all properties which you stored in write() method. That allows you to reinitialize your instance to the state before it was persisted. The Convertor infrastructure guarantees that it will not call the read() method more than once and it will call it immediatelly after the instance was created by your default constructor.

The Properties object content will be persisted as XML namespace aware fragment with following structure:

<yourelement xmlns="yournamespace"> <propertykey1>propertyvalue1</propertykey1> <propertykey2>propertyvalue2</propertykey2> <propertykeyN>propertyvalueN</propertykeyN> </yourelement>

Property keys are used as XML element names and so the same restrictions as for XML element names are valid for property keys. Similarly the property values need to be valid XML text content (i.e. no control characters, newlines will be normalized, etc.). Invalid property key or property value will result in runtime ConvertorException. The XML elements are created in lexicographical order according to property keys.

Declarative registration looks like:

Name: com/yourdomain/YourClass.class NetBeans-Simply-Convertible: {yournamespace}yourelement

where

Name: is fully qualified name of your class which implements SimplyConvertible interface

NetBeans-Simply-Convertible: declaration of simply convertible

yournamespace is XML namespace to which your class will be persisted

yourelement is element name to which your class will be persisted

Although it was said that simply convertible object must implement SimplyConvertible interface there are cases when this is not desirable and so it does not have implement it. For example it might be desirable to hide fact that object is simply convertible when object is part of an API contract. In such a case you do not have to implement SimplyConvertible interface. However your object must have two methods with the same signatures as SimplyConvertible methods have and default constructor. The methods and constructor do not have to have public access.

See also Convertor for information about how to write regular convertor.

Method Summary

void read(Properties p)
Read object state from the given Properties instance.

void write(Properties p)
Write object state to the given Properties instance.

Method Summary
`void`	`read(Properties p)` Read object state from the given Properties instance.
`void`	`write(Properties p)` Write object state to the given Properties instance.

Method Detail

read

void read(Properties p)

Read object state from the given Properties instance. The method will be called only once by Convertor infrastructure just after the instance was created by default constructor.

Parameters:: p - properties instance with properties stored by write() method
Throws:: ConvertorException - can throw this exception when content of Properties instance is malformed

write

void write(Properties p)

Write object state to the given Properties instance. The Convertor infrastructure will take care about persistence of content of Properties instance. Non-String properties are forbidden. For naming restrictions on property keys and values see the class Javadoc.

Parameters:: p - empty properties instance for the data to be persisted