<summary>Enable correct cleanup of properties in Project Property dialog of an extension of JSE Project</summary>

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

            <date day="10" month="10" year="2012"/>

            <author login="psomol"/>

            <compatibility addition="yes"/>

            <description>

                Added interface <code>J2SECustomPropertyHandler</code> with methods <code>save()</code>

                and <code>cleanup()</code> to enable correct saving of properties added by JSE Project extending 

                modules, and correct memory cleanup when property dialog is closed. If a JSE Project extending 

                module adds/modifies panels in Project Property panels, then a mechanism is needed to ensure 

                that all user-modified properties are correctly stored in project.properties and private.properties 

                when OK pressed, but also to ensure that extension-specific temporary structures are freed on

                dialog close. <code>J2SECustomPropertyHandler</code> replaces <code>J2SECustomPropertySaver</code>

                which proved insufficient to handle proper memory management. <code>J2SECustomPropertySaver</code>

                is thus to be considered deprecated, although technically it is still supported.

            </description>

            <class package="org.netbeans.modules.java.j2seproject.api" name="J2SECustomPropertyHandler"/>

            <issue number="219746"/>

        </change>

        <change>

            <api name="jseprojects"/>

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

 * 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.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.java.j2seproject.api;

import org.netbeans.api.project.Project;

/**

 * Property handler to be implemented by J2SE Project extension modules

 * that introduce new project properties. Registered handlers are

 * used to save extended propertes in addition to standard J2SE Project properties

 * if modified by user in Project Properties dialog, and to ensure memory

 * cleanup at the time when property dialog is closed.

 * Implementation of the interface should be registered using 

 * {@link org.netbeans.spi.project.ProjectServiceProvider}.

 * 

 * Note: replaces J2SECustomPropertySaver which should not be used any more

 * 

 * @author Petr Somol

 * @since 1.56

 */

public interface J2SECustomPropertyHandler {

    /**

     * Method is called when OK is pressed in JSE Project Properties dialog

     * and properties supplied by JSE Project extension module 

     * (thus not handled by JSE Project itself)

     * need to be stored in project.properties and private.properties.

     * 

     * @param p project whose extension properties are to be saved

     */

    void save(Project p);

    /**

     * Method is called when JSE Project Properties dialog is closed

     * to clean up structures holding project properties specific to

     * JSE Project extension module (JFXProjectProperties, JWSProjectProperties)

     * for the dialog lifetime.

     * 

     * @param p project whose extension properties are to be cleaned up

     */

    void cleanup(Project p);

}

 * @deprecated use J2SECustomPropertyHandler instead

@Deprecated

import org.netbeans.modules.java.api.common.project.ui.customizer.ProjectSharability;

            for (J2SECustomPropertyHandler saver : project.getLookup().lookupAll(J2SECustomPropertyHandler.class)) {

                saver.save(project);

            }

            // the following is deprecated

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

 * 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.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.java.j2seproject.api;

import java.beans.PropertyChangeListener;

import java.io.IOException;

import java.util.Map;

import javax.swing.JPanel;

import javax.swing.JTextField;

import javax.swing.JToggleButton;

import javax.swing.text.Document;

import org.junit.BeforeClass;

import org.junit.Test;

import static org.junit.Assert.*;

import org.netbeans.api.project.Project;

import org.netbeans.junit.MockServices;

import org.netbeans.spi.project.support.ant.EditableProperties;

import org.netbeans.spi.project.support.ant.PropertyEvaluator;

import org.netbeans.spi.project.support.ant.ui.StoreGroup;

import org.openide.util.Exceptions;

import org.openide.util.Lookup;

/**

 * Test of SPI class org.netbeans.modules.java.j2seproject.api.J2SECustomPropertyHandler

 * 

 * @author Petr Somol

 */

public class J2SECustomPropertyHandlerTest {

    public J2SECustomPropertyHandlerTest() {

    }

    @BeforeClass

    public static void setUpClass() throws Exception {

        MockServices.setServices(MockProjectExtenderPropertiesHandler.class);

    }

    private static MockProjectExtenderProperties extProperties = MockProjectExtenderProperties.getInstance();    

    /**

     * Simulates property storage.

     */

    private static EditableProperties storedProperties = new EditableProperties(true);

    /**

     * Simulates reaction to clicking OK in Project Properties dialog.

     * Both standard and extended properties thus need to be saved.

     */

    public void invokeCentralizedSave() {

        // first save standard project properties

        System.out.println("invokeCentralizedSave():");

        // then invoke all registered CustomPropertyHandlers to save all extended properties

        Project thisProjectMockup = null;

        for (J2SECustomPropertyHandler saver : Lookup.getDefault().lookupAll(J2SECustomPropertyHandler.class)) {

            saver.save(thisProjectMockup);

        }

    }

    /**

     * Simulates reaction to closing the Project Properties dialog.

     */

    public void invokeCentralizedCleanup() {

        System.out.println("invokeCentralizedCleanup():");

        // then invoke all registered CustomPropertyHandlers to clean whatever necessary

        Project thisProjectMockup = null;

        for (J2SECustomPropertyHandler cleaner : Lookup.getDefault().lookupAll(J2SECustomPropertyHandler.class)) {

            cleaner.cleanup(thisProjectMockup);

        }

    }

    /**

     * Test of save method, of class J2SECustomPropertyHandler.

     */

    @Test

    public void testCentralizedPropertiesSave() {

        MockupCategory1Panel panel1 = new MockupCategory1Panel();

        MockupCategory2Panel panel2 = new MockupCategory2Panel();

        System.out.println("testCentralizedPropertiesSave():");

        assertEquals(storedProperties.size(), 0);

        invokeCentralizedSave();

        assertEquals(storedProperties.size(), 2); // empty document is not saved

        assertEquals(storedProperties.get("mock.property1"), "false"); 

        assertEquals(storedProperties.get("mock.property2"), "false"); 

        assertNull(storedProperties.get("mock.property3")); 

        System.out.println("OK"); 

        // simulate user invoked property change in first Category panel followed by click on OK button

        panel1.simulateUserButtonAction();

        invokeCentralizedSave();

        assertEquals(storedProperties.size(), 2); // empty document is not saved

        assertEquals(storedProperties.get("mock.property1"), "true"); 

        assertEquals(storedProperties.get("mock.property2"), "false"); 

        assertNull(storedProperties.get("mock.property3")); 

        System.out.println("OK"); 

        // simulate user invoked property change in second Category panel followed by click on OK button

        panel2.simulateUserButtonAction();

        invokeCentralizedSave();

        assertEquals(storedProperties.size(), 2); // empty document is not saved

        assertEquals(storedProperties.get("mock.property1"), "true"); 

        assertEquals(storedProperties.get("mock.property2"), "true"); 

        assertNull(storedProperties.get("mock.property3")); 

        System.out.println("OK"); 

        // simulate user invoked property change in first and second Category panel followed by click on OK button

        panel1.simulateUserButtonAction();

        panel2.simulateUserTextFieldAction("USER WROTE THIS"); 

        invokeCentralizedSave();

        assertEquals(storedProperties.size(), 3);

        assertEquals(storedProperties.get("mock.property1"), "false"); 

        assertEquals(storedProperties.get("mock.property2"), "true"); 

        assertEquals(storedProperties.get("mock.property3"), "USER WROTE THIS"); 

        System.out.println("OK"); 

        // simulate Cancel in properties dialog

        panel1.simulateUserButtonAction();

        panel2.simulateUserButtonAction();

        panel2.simulateUserTextFieldAction("USER WROTE SOMETHING ELSE"); 

        invokeCentralizedCleanup();

        assertNull(MockProjectExtenderProperties.extProperties);

        assertEquals(storedProperties.size(), 3);

        assertEquals(storedProperties.get("mock.property1"), "false"); 

        assertEquals(storedProperties.get("mock.property2"), "true"); 

        assertEquals(storedProperties.get("mock.property3"), "USER WROTE THIS"); 

        System.out.println("OK"); 

    }

    /**

     * Extended properties centralized property handler service.

     */

    public static final class MockProjectExtenderPropertiesHandler implements J2SECustomPropertyHandler {

        @Override

        public void save(Project p) {

            // in real p would be used to lookup the correct ProjectExtenderProperties instance

            MockProjectExtenderProperties prop = MockProjectExtenderProperties.getInstanceIfExists();

            if(prop != null) {

                try {

                    prop.store();

                } catch (IOException ex) {

                    Exceptions.printStackTrace(ex);

                }

            }

        }

        @Override

        public void cleanup(Project p) {

            // in real p would be used to lookup the correct ProjectExtenderProperties instance

            MockProjectExtenderProperties prop = MockProjectExtenderProperties.getInstanceIfExists();

            if(prop != null) {

                prop.cleanup();

            }

        }

    }

    /**

     * Class managing properties specific to the project extension module.

     */

    public static final class MockProjectExtenderProperties {

        private static MockProjectExtenderProperties extProperties = null;

        public static final String PROPERTY1 = "mock.property1"; 

        public static final String PROPERTY2 = "mock.property2"; 

        public static final String PROPERTY3 = "mock.property3"; 

        private JToggleButton.ToggleButtonModel model1;

        private JToggleButton.ToggleButtonModel model2;

        private Document model3;

        private StoreGroup mockPropGroup = new StoreGroup();

        public JToggleButton.ToggleButtonModel getModel1() {

            return model1;

        }

        public JToggleButton.ToggleButtonModel getModel2() {

            return model2;

        }

        public Document getModel3() {

            return model3;

        }

        MockProjectExtenderProperties() {

            EditableProperties mockCentralProperties = new EditableProperties(true);

            MockPropertyEvaluator pe = new MockPropertyEvaluator(mockCentralProperties);

            model1 = mockPropGroup.createToggleButtonModel(pe, PROPERTY1);

            model2 = mockPropGroup.createToggleButtonModel(pe, PROPERTY2);

            model3 = mockPropGroup.createStringDocument(pe, PROPERTY3);

        }

        public static MockProjectExtenderProperties getInstanceIfExists() {

            if(extProperties != null) {

                return extProperties;

            }

            return null;

        }

        public static MockProjectExtenderProperties getInstance() {

            if(extProperties == null) {

                extProperties = new MockProjectExtenderProperties();

            }

            return extProperties;

        }

        /**

         * Method implementing actual saving of extended properties.

         */

        public void store() throws IOException {

            try {

                mockPropGroup.store(storedProperties);

                // in reality cache or save to *.properties file

                if(false) {

                    throw new IOException();

                }

            } catch (IOException ioex) {}

        }   

        /**

         * Clean up temporary memory structures.

         */

        public void cleanup() {

            extProperties = null;

        }   

    }

    public static final class MockupCategory1Panel extends JPanel {

        JToggleButton button = new JToggleButton();

        MockupCategory1Panel() {

            button.setModel(extProperties.getModel1());

        }

        public void simulateUserButtonAction() {

            button.doClick();

        }

    }

    public static final class MockupCategory2Panel extends JPanel {

        JToggleButton button = new JToggleButton();

        JTextField textField  = new JTextField();

        MockupCategory2Panel() {

            button.setModel(extProperties.getModel2());

            textField.setDocument(extProperties.getModel3());

        }

        public void simulateUserButtonAction() {

            button.doClick();

        }

        public void simulateUserTextFieldAction(String str) {

            textField.setText(str);

        }

    }

    public static final class MockPropertyEvaluator implements PropertyEvaluator {

        private final EditableProperties ep;

        MockPropertyEvaluator(EditableProperties ep) {

            this.ep = ep;

        }

        @Override

        public String getProperty(String prop) {

            return ep.getProperty(prop);

        }

        @Override

        public String evaluate(String text) {

            return null;

        }

        @Override

        public Map<String, String> getProperties() {

            return null;

        }

        @Override

        public void addPropertyChangeListener(PropertyChangeListener listener) {

        }

        @Override

        public void removePropertyChangeListener(PropertyChangeListener listener) {

        }

    }

}

     * @deprecated J2SECustomPropertyHandler handles cleanup of project properties both after OK and Cancel

    @Deprecated

    <folder name="Projects">

        <folder name="org-netbeans-modules-java-j2seproject">

            <folder name="Lookup">

                <file name="org-netbeans-modules-javafx2-project-ui-JFXProjectPropertiesHandler.instance">

                    <attr name="instanceClass" stringvalue="org.netbeans.modules.javafx2.project.ui.JFXProjectPropertiesHandler"/>

                    <attr name="instanceCreate" methodvalue="org.netbeans.modules.projectapi.LazyLookupProviders.forProjectServiceProvider"/>

                    <attr name="instanceOf" stringvalue="org.netbeans.modules.java.j2seproject.api.J2SECustomPropertyHandler"/>

                </file>

                <file name="org-netbeans-modules-javafx2-project-ui-JFXProjectPropertiesSaver.instance_hidden"/>

            </folder>

        </folder>

    </folder>

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

 * 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.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.javafx2.project.ui;

import java.io.IOException;

import org.netbeans.api.project.Project;

import org.netbeans.modules.java.j2seproject.api.J2SECustomPropertyHandler;

import org.netbeans.modules.javafx2.project.JFXProjectProperties;

import org.netbeans.spi.project.ProjectServiceProvider;

import org.openide.util.Exceptions;

/**

 * Provides handler service for JavaFX 2.0 specific project properties

 * for use in standard J2SE Project Properties dialog so that all properties

 * can be properly saved in project.properties and private.properties when 

 * OK button is pressed and memory is cleaned on dialog close.

 * 

 * @author Petr Somol

 */

@ProjectServiceProvider(service=J2SECustomPropertyHandler.class, projectType="org-netbeans-modules-java-j2seproject")

public class JFXProjectPropertiesHandler implements J2SECustomPropertyHandler {

    public JFXProjectPropertiesHandler() {}

    @Override

    public void save(Project project) {

        JFXProjectProperties prop = JFXProjectProperties.getInstanceIfExists(project.getLookup());

        if(prop != null) {

            try {

                prop.store();

            } catch (IOException ex) {

                Exceptions.printStackTrace(ex);

            }

        }

    }

    @Override

    public void cleanup(Project project) {

        JFXProjectProperties prop = JFXProjectProperties.getInstanceIfExists(project.getLookup());

        if(prop != null) {

            JFXProjectProperties.cleanup(project.getLookup());

        }

    }

}

    <folder name="Projects">

        <folder name="org-netbeans-modules-java-j2seproject">

            <folder name="Lookup">

                <file name="org-netbeans-modules-javawebstart-ui-customizer-JWSProjectPropertiesHandler.instance">

                    <attr name="instanceClass" stringvalue="org.netbeans.modules.javawebstart.ui.customizer.JWSProjectPropertiesHandler"/>

                    <attr name="instanceCreate" methodvalue="org.netbeans.modules.projectapi.LazyLookupProviders.forProjectServiceProvider"/>

                    <attr name="instanceOf" stringvalue="org.netbeans.modules.java.j2seproject.api.J2SECustomPropertyHandler"/>

                </file>

                <file name="org-netbeans-modules-javawebstart-ui-customizer-JWSProjectPropertiesSaver.instance_hidden"/>

            </folder>

        </folder>

    </folder>

    @Deprecated

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

 * 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.

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.javawebstart.ui.customizer;

import org.netbeans.api.project.Project;

import org.netbeans.modules.java.j2seproject.api.J2SECustomPropertyHandler;

import org.netbeans.spi.project.ProjectServiceProvider;

/**

 * Provides handler service for WebStart specific project properties

 * for use in standard J2SE Project Properties dialog so that all properties

 * can be properly saved in project.properties and private.properties when

 * OK button is pressed, and memory gets cleaned when dialog gets closed. 

 * Note that this enables reaction to change of Java Platform.

 *

 * @author Petr Somol

 */

@ProjectServiceProvider(service=J2SECustomPropertyHandler.class, projectType="org-netbeans-modules-java-j2seproject")

public class JWSProjectPropertiesHandler implements J2SECustomPropertyHandler {

    public JWSProjectPropertiesHandler() {}

    @Override

    public void save(Project project) {

        JWSProjectProperties prop = JWSProjectProperties.getInstanceIfExists(project.getLookup());

        if(prop != null) {

            JWSProjectPropertiesUtils.updateMasterFiles(prop, project);

            JWSProjectPropertiesUtils.savePropsAndUpdateMetaFiles(prop, project);

        }

    }

    @Override

    public void cleanup(Project project) {

        JWSProjectProperties prop = JWSProjectProperties.getInstanceIfExists(project.getLookup());

        if(prop != null) {

            JWSProjectProperties.cleanup(project.getLookup());

        }

    }

}