/*
 * Copyright (c) OSGi Alliance (2017, 2018). All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.osgi.util.converter;

import java.lang.reflect.Type;

import org.osgi.annotation.versioning.ProviderType;

/**
 * A builder to create a new converter with modified behavior based on an
 * existing converter. The modified behavior is specified by providing rules
 * and/or conversion functions. If multiple rules match they will be visited in
 * sequence of registration. If a rule's function returns {@code null} the next
 * rule found will be visited. If none of the rules can handle the conversion,
 * the original converter will be used to perform the conversion.
 *
 * @author $Id$
 */
@ProviderType
public interface ConverterBuilder {
	/**
	 * Build the specified converter. Each time this method is called a new
	 * custom converter is produced based on the rules registered with the
	 * builder.
	 *
	 * @return A new converter with the rules provided to the builder.
	 */
	Converter build();

	/**
	 * Register a custom error handler. The custom error handler will be called
	 * when the conversion would otherwise throw an exception. The error handler
	 * can either throw a different exception or return a value to be used for
	 * the failed conversion.
	 *
	 * @param func The function to be used to handle errors.
	 * @return This converter builder for further building.
	 */
	ConverterBuilder errorHandler(ConverterFunction func);

	/**
	 * Register a conversion rule for this converter. Note that only the target
	 * type is specified, so the rule will be visited for every conversion to
	 * the target type.
	 *
	 * @param type The type that this rule will produce.
	 * @param func The function that will handle the conversion.
	 * @return This converter builder for further building.
	 */
	ConverterBuilder rule(Type type, ConverterFunction func);

	/**
	 * Register a conversion rule for this converter.
	 *
	 * @param rule A rule implementation.
	 * @return This converter builder for further building.
	 */
	ConverterBuilder rule(TargetRule rule);

	/**
	 * Register a catch-all rule, will be called of no other rule matches.
	 *
	 * @param func The function that will handle the conversion.
	 * @return This converter builder for further building.
	 */
	ConverterBuilder rule(ConverterFunction func);
}