/*

 * 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 only 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 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) {

            return clazz.getMethod(fm.value()).invoke(null);

        }

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

        c.setAccessible(true);

        return c.newInstance();

    }

import java.lang.ref.Reference;

import java.lang.ref.WeakReference;

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) {

        }

        public 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) {

        }

    }