001/**
002 * Copyright (C) 2006-2022 Talend Inc. - www.talend.com
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.talend.sdk.component.api.service.factory;
017
018import static java.util.Optional.ofNullable;
019import static java.util.stream.Collectors.toMap;
020
021import java.util.Map;
022import java.util.function.Function;
023import java.util.stream.Stream;
024
025/**
026 * Allows to create an instance from a classname and a set of properties.
027 * The implementation handles the coercing if needed.
028 *
029 * Note that it doesn't reuse the configuration format (for now) since it is intended
030 * to be used to convert some configuration (UI) properties to an instance.
031 */
032public interface ObjectFactory {
033
034    /**
035     * Creates an instance builder.
036     * 
037     * @param className the class of the instance to create.
038     * @return a builder you can configure before instantiating the instance.
039     */
040    ObjectFactoryInstance createInstance(String className);
041
042    interface ObjectFactoryInstance {
043
044        /**
045         * Set that the properties can be injected into fields directly, default uses fields
046         * but not private ones.
047         * 
048         * @return this.
049         */
050        ObjectFactoryInstance withFieldInjection();
051
052        /**
053         * Set that the properties can NOT be injected into fields directly.
054         *
055         * @return this.
056         */
057        ObjectFactoryInstance withoutFieldInjection();
058
059        /**
060         * If called the unsupported properties will be ignored otherwise {@link ObjectFactoryInstance#create(Class)}
061         * will fail with an exception.
062         *
063         * @return this.
064         */
065        ObjectFactoryInstance ignoreUnknownProperties();
066
067        /**
068         * @param properties the properties to use to configure the instance.
069         * @return this.
070         */
071        ObjectFactoryInstance withProperties(Map<String, ?> properties);
072
073        /**
074         * Shortcut for {@link ObjectFactoryInstance#withProperties(Map)}.
075         * Note that if there are conflicting keys the last one is used.
076         *
077         * @param stream a stream of properties.
078         * @param keyExtractor how to extract the key from the incoming stream.
079         * @param valueExtractor how to extract the value from the incoming stream.
080         * @param <T> the type of the created object.
081         * @return this.
082         */
083        default <T> ObjectFactoryInstance withProperties(final Stream<T> stream, final Function<T, String> keyExtractor,
084                final Function<T, ?> valueExtractor) {
085            return withProperties(ofNullable(stream)
086                    .orElseGet(Stream::empty)
087                    .collect(toMap(keyExtractor, valueExtractor, (a, b) -> a)));
088        }
089
090        /**
091         * @param parentType the type to cast the instance to.
092         * @param <T> the expected type of the returned instance.
093         * @return the created instance.
094         */
095        <T> T create(final Class<T> parentType);
096    }
097}