<change id="convert.as.javabean">

        <api name="settings_spi"/>

        <summary>@ConvertAsJavaBean annotation</summary>

        <version major="1" minor="20"/>

        <date day="7" month="8" year="2009"/>

        <author login="jtulach"/>

        <compatibility addition="yes" binary="compatible" deletion="no" deprecation="no" modification="yes" semantic="compatible" source="compatible"/>

        <description>

            Easy way to use JavaBean's archiver for persistence of objects.

        </description>

        <class package="org.netbeans.api.settings" name="ConvertAsJavaBean"/>

        <issue number="169620"/>

    </change>

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 2002-2003 Sun

 * Microsystems, Inc. All Rights Reserved.

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 */

package org.netbeans.api.settings;

import java.beans.PropertyChangeListener;

import java.beans.XMLDecoder;

import java.beans.XMLEncoder;

import java.lang.annotation.Documented;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

/** Specifies the kind of persistence to use of the annotated class.

 * Uses {@link XMLDecoder} and {@link XMLEncoder} to store and read

 * values of the class (and by default also its subclasses).

 * <p>

 * The format uses getters and setters of the bean and usually needs

 * default constructor:

 * <pre>

 * <code>@</code>ConvertAsJavaBean

 * <font class="type">public class</font> YourObject {

 *   <font class="type">public</font> YourObject() {}

 *   <font class="type">public</font> <font class="type">String</font> <font class="function-name">getName</font>();

 *   <font class="type">public void</font> <font class="function-name">setName</font>(<font class="type">String</font> <font class="variable-name">name</font>);

 * }

 * </pre>

 * If the bean supports {@link PropertyChangeListener} notifications and

 * contains <code>addPropertyChangeListener</code> method, the system

 * starts to listen on existing objects and in case a property change

 * is delivered, the new state of the object is persisted again.

 *

 * @author Jaroslav Tulach <jtulach@netbeans.org>

 * @since 1.20

 */

@Retention(RetentionPolicy.SOURCE)

@Target(ElementType.TYPE)

@Documented

public @interface ConvertAsJavaBean {

    /** Shall subclasses of this class be also converted as JavaBeans? */

    boolean subclasses() default true;

}

import org.netbeans.api.settings.ConvertAsJavaBean;

import org.netbeans.modules.settings.Env;

        for (Element e : env.getElementsAnnotatedWith(ConvertAsJavaBean.class)) {

            ConvertAsJavaBean reg = e.getAnnotation(ConvertAsJavaBean.class);

            String convElem = instantiableClassOrMethod(e, false);

            File f = layer(e).file("xml/memory/" + convElem.replace('.', '/'));

            f.stringvalue("settings.providerPath", "xml/lookups/NetBeans/DTD_XML_beans_1_0.instance");

            if (reg.subclasses()) {

                f.boolvalue(Env.EA_SUBCLASSES, true);

            }

            f.write();

        }

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 2002-2003 Sun

 * Microsystems, Inc. All Rights Reserved.

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 */

package org.netbeans.modules.settings.convertors;

import java.beans.PropertyChangeListener;

import java.beans.XMLDecoder;

import java.beans.XMLEncoder;

import java.io.BufferedReader;

import java.io.ByteArrayOutputStream;

import java.io.IOException;

import java.nio.CharBuffer;

import java.util.logging.Level;

import java.util.logging.Logger;

import java.util.regex.Matcher;

import java.util.regex.Pattern;

import org.netbeans.spi.settings.Convertor;

import org.netbeans.spi.settings.Saver;

import org.openide.util.Exceptions;

import org.openide.util.io.ReaderInputStream;

/** Convertor using {@link  java.beans.XMLEncoder} and

 * {@link  java.beans.XMLDecoder}.

 *

 * @author  Jaroslav Tulach

 */

public final class XMLBeanConvertor extends Convertor implements PropertyChangeListener {

    /** create convertor instance; should be used in module layers

     * @param providerFO provider file object

     */

    public static Convertor create() {

        return new XMLBeanConvertor();

    }

    public XMLBeanConvertor() {

    }

    public Object read(java.io.Reader r) throws IOException, ClassNotFoundException {

        java.io.

        BufferedReader buf = new BufferedReader(r, 4096);

        CharBuffer arr = CharBuffer.allocate(2048);

        buf.mark(arr.capacity());

        buf.read(arr);

        arr.flip();

        Matcher m = Pattern.compile("<java").matcher(arr);

        if (m.find()) {

            buf.reset();

            buf.skip(m.start());

        } else {

            buf.reset();

        }

        XMLDecoder d = new XMLDecoder(new ReaderInputStream(buf, "UTF-8"));

        return d.readObject();

    }

    public void write(java.io.Writer w, Object inst) throws IOException {

        ByteArrayOutputStream out = new ByteArrayOutputStream();

        XMLEncoder e = new XMLEncoder(out);

        e.writeObject(inst);

        e.close();

        String data = new String(out.toByteArray(), "UTF-8");

        data = data.replaceFirst("<java", "<!DOCTYPE xmlbeans PUBLIC \"-//NetBeans//DTD XML beans 1.0//EN\" \"http://www.netbeans.org/dtds/xml-beans-1_0.dtd\">\n<java");

        w.write(data);

    }

    /** an object listening on the setting changes */

    private Saver saver;

    public void registerSaver(Object inst, Saver s) {

        if (saver != null) {

            XMLSettingsSupport.err.warning("[Warning] Saver already registered");

            return;

        }

        // add propertyChangeListener

        try {

            java.lang.reflect.Method method = inst.getClass().getMethod(

                "addPropertyChangeListener", // NOI18N

                new Class[] {PropertyChangeListener.class});

            method.invoke(inst, new Object[] {this});

            this.saver = s;

        } catch (NoSuchMethodException ex) {

            XMLSettingsSupport.err.warning(

            "ObjectChangesNotifier: NoSuchMethodException: " + // NOI18N

            inst.getClass().getName() + ".addPropertyChangeListener"); // NOI18N

        } catch (IllegalAccessException ex) {

            Exceptions.printStackTrace(ex);

        } catch (java.lang.reflect.InvocationTargetException ex) {

            Exceptions.printStackTrace(ex);

        }

    }

    public void unregisterSaver(Object inst, Saver s) {

        if (saver == null) return;

        if (saver != s) {

            XMLSettingsSupport.err.warning("[Warning] trying unregistered unknown Saver");

            return;

        }

        try {

            java.lang.reflect.Method method = inst.getClass().getMethod(

                "removePropertyChangeListener", // NOI18N

                new Class[] {PropertyChangeListener.class});

            method.invoke(inst, new Object[] {this});

            this.saver = null;

        } catch (NoSuchMethodException ex) {

            XMLSettingsSupport.err.fine(

            "ObjectChangesNotifier: NoSuchMethodException: " + // NOI18N

            inst.getClass().getName() + ".removePropertyChangeListener"); // NOI18N

            // just changes done through gui will be saved

        } catch (IllegalAccessException ex) {

            Exceptions.printStackTrace(ex);

            // just changes done through gui will be saved

        } catch (java.lang.reflect.InvocationTargetException ex) {

            Exceptions.printStackTrace(ex);

            // just changes done through gui will be saved

        }

    }

    public void propertyChange(java.beans.PropertyChangeEvent evt) {

        if (saver == null) {

            return;

        }

        if (acceptSave()) {

            try {

                saver.requestSave();

            } catch (IOException ex) {

                Logger.getLogger(XMLBeanConvertor.class.getName()).log(Level.WARNING, null, ex);

            }

        } else {

            saver.markDirty();

        }

    }

    private boolean acceptSave() {

        return true;

    }

}

<?xml encoding="UTF-8" ?>

<!--

DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.

The contents of this file are subject to the terms of either the GNU

General Public License Version 2 only ("GPL") or the Common

Development and Distribution License("CDDL") (collectively, the

"License"). You may not use this file except in compliance with the

License. You can obtain a copy of the License at

http://www.netbeans.org/cddl-gplv2.html

or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

specific language governing permissions and limitations under the

License.  When distributing the software, include this License Header

Notice in each file and include the License file at

nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this

particular file as subject to the "Classpath" exception as provided

by Sun in the GPL Version 2 section of the License file that

accompanied this code. If applicable, add the following below the

License Header, with the fields enclosed by brackets [] replaced by

your own identifying information:

"Portions Copyrighted [year] [name of copyright owner]"

Contributor(s):

The Original Software is NetBeans. The Initial Developer of the Original

Software is Sun Microsystems, Inc. Portions Copyright 2002 Sun

Microsystems, Inc. All Rights Reserved.

If you wish your version of this file to be governed by only the CDDL

or only the GPL Version 2, indicate your decision by adding

"[Contributor] elects to include this software in this distribution

under the [CDDL or GPL Version 2] license." If you do not indicate a

single choice of license, a recipient has the option to distribute

your version of this file under either the CDDL, the GPL Version 2 or

to extend the choice of license to its licensees as provided above.

However, if you add GPL Version 2 code and therefore, elected the GPL

Version 2 license, then the option applies only if the new code is

made subject to such option by the copyright holder.

-->

<!ELEMENT java (

    object   | 

    void     | 

    string   |  

    class    | 

    null     | 

    array    | 

    boolean  | 

    byte     | 

    char     | 

    short    | 

    int      | 

    long     | 

    float    |  

    double

)*>

<!ATTLIST java 

    version  CDATA  #IMPLIED

    class    CDATA  #IMPLIED

>

<!ELEMENT boolean (#PCDATA)>

<!ELEMENT byte    (#PCDATA)>

<!ELEMENT char    (#PCDATA)>

<!ELEMENT short   (#PCDATA)>

<!ELEMENT int     (#PCDATA)>

<!ELEMENT long    (#PCDATA)>

<!ELEMENT float   (#PCDATA)>

<!ELEMENT double  (#PCDATA)>

<!ELEMENT string  (#PCDATA)>

<!ELEMENT class   (#PCDATA)>

<!ELEMENT null    (#PCDATA)>

<!ELEMENT object (

    object   | 

    void     | 

    string   |  

    class    | 

    null     | 

    array    | 

    boolean  | 

    byte     | 

    char     | 

    short    | 

    int      | 

    long     | 

    float    |  

    double

)*>

<!ATTLIST object 

    id       ID     #IMPLIED

    idref    IDREF  #IMPLIED

    class    CDATA  #IMPLIED

    field    CDATA  #IMPLIED

    method   CDATA  #IMPLIED

    property CDATA  #IMPLIED

    index    CDATA  #IMPLIED

>

<!ELEMENT array (

    object   | 

    void     | 

    string   |  

    class    | 

    null     | 

    array    | 

    boolean  | 

    byte     | 

    char     | 

    short    | 

    int      | 

    long     | 

    float    |  

    double

)*>

<!ATTLIST array 

    id       ID     #IMPLIED

    class    CDATA  #IMPLIED

    length   CDATA  #IMPLIED

>

<!ELEMENT void (

    object   | 

    void     | 

    string   |  

    class    | 

    null     | 

    array    | 

    boolean  | 

    byte     | 

    char     | 

    short    | 

    int      | 

    long     | 

    float    |  

    double

)*>

<!ATTLIST void 

    id       ID     #IMPLIED

    class    CDATA  #IMPLIED

    method   CDATA  #IMPLIED

    property CDATA  #IMPLIED

    index    CDATA  #IMPLIED

>

            	<!-- Convertor handling XML beans -->

                <file name="DTD_XML_beans_1_0.instance">

                    <attr name="instanceCreate" methodvalue="org.netbeans.api.settings.Factory.create"/>

                    <attr name="settings.convertor" methodvalue="org.netbeans.modules.settings.convertors.XMLBeanConvertor.create"/>

                    <attr name="hint.originalPublicID" stringvalue="-//NetBeans//DTD XML beans 1.0//EN"/>

              </file>

            	<file name="DTD_XML_beans_1_0" url="javabeans-1_0.dtd">

                    <attr name="hint.originalPublicID" stringvalue="-//NetBeans//DTD XML beans 1.0//EN"/>

            	</file>

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 2002 Sun

 * Microsystems, Inc. All Rights Reserved.

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 */

package org.netbeans.modules.settings.convertors;

import java.io.*;

import org.netbeans.api.settings.ConvertAsJavaBean;

import org.netbeans.junit.NbTestCase;

import org.openide.cookies.InstanceCookie;

import org.openide.filesystems.FileObject;

import org.openide.filesystems.FileUtil;

import org.openide.loaders.DataFolder;

import org.openide.loaders.DataObject;

import org.openide.loaders.InstanceDataObject;

import org.openide.modules.ModuleInfo;

import org.openide.util.Lookup;

import org.openide.util.test.AnnotationProcessorTestUtils;

/** Checks usage of annotation to assign XML properties convertor.

 *

 * @author Jaroslav Tulach

 */

public final class ConvertAsBeanTest extends NbTestCase {

    /** Creates a new instance of XMLPropertiesConvertorTest */

    public ConvertAsBeanTest(String name) {

        super(name);

    }

    @Override

    protected void setUp() throws Exception {

        clearWorkDir();

        Lookup.getDefault().lookup(ModuleInfo.class);

    }

    public void testReadWrite() throws Exception {

        AnnoFoo foo = new AnnoFoo();

        foo.setName("xxx");

        DataFolder test = DataFolder.findFolder(FileUtil.getConfigRoot());

        DataObject obj = InstanceDataObject.create(test, null, foo, null);

        final FileObject pf = obj.getPrimaryFile();

        final String content = pf.asText();

        if (content.indexOf("<string>xxx</string>") == -1) {

            fail(content);

        }

        obj.setValid(false);

        DataObject newObj = DataObject.find(pf);

        if (newObj == obj) {

            fail("Strange, objects shall differ");

        }

        InstanceCookie ic = newObj.getLookup().lookup(InstanceCookie.class);

        assertNotNull("Instance cookie found", ic);

        Object read = ic.instanceCreate();

        assertNotNull("Instance created", read);

        assertEquals("Correct class", AnnoFoo.class, read.getClass());

        AnnoFoo readFoo = (AnnoFoo)read;

        assertEquals("property changed", "xxx", readFoo.getName());

    }

    public void testReadWriteOnSubclass() throws Exception {

        HooFoo foo = new HooFoo();

        foo.setName("xxx");

        DataFolder test = DataFolder.findFolder(FileUtil.getConfigRoot());

        DataObject obj = InstanceDataObject.create(test, null, foo, null);

        final FileObject pf = obj.getPrimaryFile();

        final String content = pf.asText();

        if (content.indexOf("<string>xxx</string>") == -1) {

            fail(content);

        }

        obj.setValid(false);

        DataObject newObj = DataObject.find(pf);

        if (newObj == obj) {

            fail("Strange, objects shall differ");

        }

        InstanceCookie ic = newObj.getLookup().lookup(InstanceCookie.class);

        assertNotNull("Instance cookie found", ic);

        Object read = ic.instanceCreate();

        assertNotNull("Instance created", read);

        assertEquals("Correct class", HooFoo.class, read.getClass());

        HooFoo readFoo = (HooFoo)read;

        assertEquals("property changed", "xxx", readFoo.getName());

    }

    @ConvertAsJavaBean(

    )

    public static class AnnoFoo extends Object {

        private String name;

        public String getName() {

            return name;

        }

        public void setName(String name) {

            this.name = name;

        }

    } // end of AnnoFoo

    public static class HooFoo extends AnnoFoo {

        private int count;

        public int getCount() {

            return count;

        }

        public void setCount(int count) {

            this.count = count;

        }

    } // end of HooFoo

    @ConvertAsJavaBean(

        subclasses=false

    )

    public static class JuuFoo extends Object {

        private String name;

        public String getName() {

            return name;

        }

        public void setName(String name) {

            this.name = name;

        }

    } // end of JuuFoo

    public static class NotFoo extends JuuFoo {

        private int count;

        public int getCount() {

            return count;

        }

        public void setCount(int count) {

            this.count = count;

        }

    } // end of NotFoo

    public void testReadWriteNotForSubclasses() throws Exception {

        NotFoo foo = new NotFoo();

        foo.setName("xxx");

        DataFolder test = DataFolder.findFolder(FileUtil.getConfigRoot());

        try {

            DataObject obj = InstanceDataObject.create(test, null, foo, null);

            final FileObject pf = obj.getPrimaryFile();

            final String content = pf.asText();

            fail(content);

        } catch (NotSerializableException ex) {

            // OK

        }

    }

    public void testVerifyHaveDefaultConstructor() throws Exception {

        AnnotationProcessorTestUtils.makeSource(getWorkDir(), "x.y.Kuk",

            "import org.netbeans.api.settings.ConvertAsJavaBean;\n" +

            "@ConvertAsJavaBean()\n" +

            "public class Kuk {\n" +

            "  public Kuk(int i) {}\n" +

            "}\n"

        );

        ByteArrayOutputStream err = new ByteArrayOutputStream();

        boolean res = AnnotationProcessorTestUtils.runJavac(getWorkDir(), null, getWorkDir(), null, err);

        assertFalse("Should fail", res);

        if (err.toString().indexOf("x.y.Kuk must have a no-argument constructor") == -1) {

            fail("Wrong error message:\n" + err.toString());

        }

    }

    public void testInterfacesCannotBeAnnotated() throws Exception {

        AnnotationProcessorTestUtils.makeSource(getWorkDir(), "x.y.Kuk",

            "import org.netbeans.api.settings.ConvertAsJavaBean;\n" +

            "@ConvertAsJavaBean()\n" +

            "public interface Kuk {\n" +

            "  public int buk(int i);\n" +

            "}\n"

        );

        ByteArrayOutputStream err = new ByteArrayOutputStream();

        boolean res = AnnotationProcessorTestUtils.runJavac(getWorkDir(), null, getWorkDir(), null, err);

        assertFalse("Should fail", res);

        if (err.toString().indexOf("is not loadable") == -1) {

            fail("Wrong error message:\n" + err.toString());

        }

    }

}