<change id="method.factory">

        <api name="settings_api"/>

        <summary>Instances may have factory methods</summary>

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

        <date day="15" month="3" year="2013"/>

        <author login="jtulach"/>

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

        <description>

            No need for the instances to have default constructor anymore.

            One can tell the system to use different factory method.

        </description>

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

        <issue number="227050"/>

    </change>

/*

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

 *

 * Copyright 2013 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 2013 Sun Microsystems, Inc.

 */

package org.netbeans.api.settings;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

import org.netbeans.spi.settings.Convertor;

/** Specifies an alternative factory method to use (rather than constructor)

 * to create the instance. Use in orchestration with 

 * {@link ConvertAsProperties} or on any class that is processed by serializing

 * {@link Convertor}s.

 * 

 * @since 1.40

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

 */

@Target(ElementType.TYPE)

@Retention(RetentionPolicy.RUNTIME)

public @interface FactoryMethod {

    /**

     * Name of factory method to use instead of default constructor. Sometimes, for

     * example when dealing with singletons, it may be desirable to control how

     * an instance of given class is created. In such case one can create a

     * factory method (takes no arguments and returns instance of desired type)

     * in the class annotated by {@link ConvertAsProperties} annotation.

     */

    String value();

}

import javax.lang.model.element.ElementKind;

import org.netbeans.api.settings.FactoryMethod;

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

            FactoryMethod m = e.getAnnotation(FactoryMethod.class);

            if (m == null) {

                continue;

            }

            boolean found = false;

            for (Element ch : e.getEnclosedElements()) {

                if (ch.getKind() != ElementKind.METHOD) {

                    continue;

                }

                if (!m.value().equals(ch.getSimpleName().toString())) {

                    continue;

                }

                ExecutableElement ee = (ExecutableElement)ch;

                if (ee.getParameters().size() > 0) {

                    throw new LayerGenerationException("Factory method " + m.value() + " must have no parameters", ee);

                }

                if (!ee.getModifiers().contains(Modifier.STATIC)) {

                    throw new LayerGenerationException("Factory method " + m.value() + " has to be static", ee);

                }

                if (!processingEnv.getTypeUtils().isSameType(ee.getReturnType(), e.asType())) {

                    throw new LayerGenerationException("Factory method " + m.value() + " must return " + e.getSimpleName(), ee);

                }

                found = true;

            }

            if (!found) {

                throw new LayerGenerationException("Method named " + m.value() + " was not found in this class", e);

            }

        }

import java.lang.reflect.InvocationTargetException;

import org.netbeans.api.settings.FactoryMethod;

    static Object newInstance(Class<?> clazz) throws IllegalArgumentException, 

    InstantiationException, NoSuchMethodException, InvocationTargetException, 

    IllegalAccessException {

        FactoryMethod fm = clazz.getAnnotation(FactoryMethod.class);

        if (fm != null) {

            Method method;

            try {

                method = clazz.getMethod(fm.value());

            } catch (NoSuchMethodException ex) {

                method = clazz.getDeclaredMethod(fm.value());

            }

            method.setAccessible(true);

            return method.invoke(null);

        }

        Constructor<?> c = clazz.getDeclaredConstructor();

        c.setAccessible(true);

        return c.newInstance();

    }

/*

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

 *

 * Copyright 2013 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 2013 Sun Microsystems, Inc.

 */

package org.netbeans.modules.settings.convertors;

import java.io.ByteArrayOutputStream;

import java.io.File;

import java.io.IOException;

import org.netbeans.junit.NbTestCase;

import org.openide.util.test.AnnotationProcessorTestUtils;

/**

 *

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

 */

public class FactoryMethodTest extends NbTestCase {

    private File src;

    private File dst;

    public FactoryMethodTest(String name) {

        super(name);

    }

    @Override

    protected void setUp() throws Exception {

        clearWorkDir();

        src = new File(getWorkDir(), "src");

        src.mkdirs();

        dst = new File(getWorkDir(), "dst");

        dst.mkdirs();

    }

    public void testMethodOfGivenNameMustExists() throws IOException {

        AnnotationProcessorTestUtils.makeSource(src, "tst.Bean", 

            "import org.netbeans.api.settings.FactoryMethod;",

            "@FactoryMethod(\"create\")",

            "public class Bean {",

            "}"

        );

        ByteArrayOutputStream os = new ByteArrayOutputStream();

        boolean res = AnnotationProcessorTestUtils.runJavac(src, null, dst, null, os);

        assertFalse("Compilation fails", res);

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

        if (out.indexOf(" Method named create was not found") == -1) {

            fail("Should warn about missing method\n" + out);

        }

    }

    public void testMethodOfGivenNameMustHaveNoArguments() throws IOException {

        AnnotationProcessorTestUtils.makeSource(src, "tst.Bean", 

            "import org.netbeans.api.settings.FactoryMethod;",

            "@FactoryMethod(\"create\")",

            "public class Bean {",

            "  public static Bean create(boolean x) { return null; }",

            "}"

        );

        ByteArrayOutputStream os = new ByteArrayOutputStream();

        boolean res = AnnotationProcessorTestUtils.runJavac(src, null, dst, null, os);

        assertFalse("Compilation fails", res);

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

        if (out.indexOf("no parameters") == -1) {

            fail("Should warn about arguments of the method\n" + out);

        }

    }

    public void testMethodOfGivenNameMustBeStatic() throws IOException {

        AnnotationProcessorTestUtils.makeSource(src, "tst.Bean", 

            "import org.netbeans.api.settings.FactoryMethod;",

            "@FactoryMethod(\"create\")",

            "public class Bean {",

            "  public Bean create() { return null; }",

            "}"

        );

        ByteArrayOutputStream os = new ByteArrayOutputStream();

        boolean res = AnnotationProcessorTestUtils.runJavac(src, null, dst, null, os);

        assertFalse("Compilation fails", res);

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

        if (out.indexOf("has to be static") == -1) {

            fail("Should warn method not being static\n" + out);

        }

    }

    public void testMethodOfGivenNameMustHaveTheSameReturnType() throws IOException {

        AnnotationProcessorTestUtils.makeSource(src, "tst.Bean", 

            "import org.netbeans.api.settings.FactoryMethod;",

            "@FactoryMethod(\"create\")",

            "public class Bean {",

            "  public static String create() { return null; }",

            "}"

        );

        ByteArrayOutputStream os = new ByteArrayOutputStream();

        boolean res = AnnotationProcessorTestUtils.runJavac(src, null, dst, null, os);

        assertFalse("Compilation fails", res);

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

        if (out.indexOf("must return Bean") == -1) {

            fail("Should about wrong return type\n" + out);

        }

    }

}

import org.netbeans.api.settings.FactoryMethod;

    public void testFactoryMethod() throws IOException, ClassNotFoundException {

        DataFolder df = DataFolder.findFolder(FileUtil.getConfigRoot().createFolder("testFactoryMethod"));

        FileObject fo = df.getPrimaryFile().createData("test.settings");

        OutputStream os = fo.getOutputStream();

        os.write((

"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n" +

"<!DOCTYPE settings PUBLIC \"-//NetBeans//DTD Session settings 1.0//EN\" \"http://www.netbeans.org/dtds/sessionsettings-1_0.dtd\">\n" +

"<settings version=\"1.0\">\n" +

"  <instance class=\"" + FactoryBase.class.getName() + "\"/>\n" +

"</settings>\n"

        ).getBytes("UTF-8"));

        os.close();

        InstanceCookie ido = DataObject.find(fo).getCookie(InstanceCookie.class);

        FactoryBase fb = (FactoryBase) ido.instanceCreate();

        assertNotNull("Re-created OK!", fb);

    }

    @FactoryMethod("create")

    public static class FactoryBase implements Serializable {

        private FactoryBase() {

            throw new IllegalStateException("Don't call my default constructor");

        }

        FactoryBase(boolean ok) {

        }

        static FactoryBase create() {

            return new FactoryBase(true);

        }

    }

import java.lang.ref.Reference;

import java.lang.ref.WeakReference;

import java.util.Properties;

import static junit.framework.Assert.assertEquals;

import static junit.framework.Assert.assertNotNull;

import org.netbeans.api.settings.ConvertAsProperties;

import org.netbeans.api.settings.FactoryMethod;

import org.openide.filesystems.Repository;

    public void testFactoryMethod() throws Exception {

        FileObject dtdFO = Repository.getDefault().getDefaultFileSystem().

            findResource("/xml/lookups/abc/x.instance");

        assertNotNull("Provider not found", dtdFO);

        Convertor c = XMLPropertiesConvertor.create(dtdFO);

        assertNotNull("Convertor created", c);

        DataFolder folder = DataFolder.findFolder(root);

        FactoryBase inst = FactoryBase.create();

        InstanceDataObject ido = InstanceDataObject.create(folder, null, inst, null);

        assertSame("Instance is there", inst, ido.instanceCreate());

        Reference<Object> ref = new WeakReference<Object>(inst);

        inst = null;

        assertGC("Instance can disappear", ref);

        Object obj = ido.instanceCreate();

        assertEquals("One can re-create it without default constructor", FactoryBase.class, obj.getClass());

    }

    @ConvertAsProperties(dtd = "-//abc/x")

    @FactoryMethod("create")

    public static class FactoryBase implements Serializable {

        public FactoryBase() {

            throw new IllegalStateException("Don't call my default constructor");

        }

        FactoryBase(boolean ok) {

        }

        public static FactoryBase create() {

            return new FactoryBase(true);

        }

        void readProperties(Properties p) {

        }

        void writeProperties(Properties p) {

        }

    }