001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.commons.conversion;
018
019import java.util.*;
020
021/**
022 * Functional interface representing a single type conversion used by {@link CachingConverter}.
023 *
024 * <p>
025 * The {@code args} parameter carries any type arguments needed for parameterized output types.
026 * For example, when converting to a {@link List}, {@code args[0]} would be the element type.
027 * For a {@link Map}, {@code args[0]} is the key type and {@code args[1]} is the value type.
028 *
029 * <p>
030 * A single cached {@code Conversion} function can serve all parameterizations of the same raw output
031 * type by accepting different {@code args} values at runtime.
032 *
033 * @param <I> The input type.
034 * @param <O> The output type.
035 */
036@FunctionalInterface
037public interface Conversion<I,O> {
038
039   /**
040    * Converts the input object to the output type.
041    *
042    * @param in The input object.
043    * @param memberOf The outer instance for non-static inner class construction, or <jk>null</jk>.
044    * @param session The converter session providing contextual objects such as {@link TimeZone} or
045    *    {@link Locale}, or <jk>null</jk> if no session is available.
046    * @param args Optional type arguments for parameterized output types (e.g. element type for collections).
047    * @return The converted object.
048    */
049   O to(I in, Object memberOf, ConverterSession session, Class<?>... args);
050}