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 * Provides contextual objects to {@link Conversion} functions at call time.
023 *
024 * <p>
025 * A {@code ConverterSession} is passed through the {@link Conversion#to(Object, Object, ConverterSession, Class[])}
026 * method and allows conversion lambdas to retrieve session-scoped objects such as a {@link TimeZone},
027 * {@link Locale}, or media type without requiring those objects to be captured in the lambda closure.
028 *
029 * <p>
030 * Implementations look up contextual objects by type (and optionally by name). If no matching object is
031 * registered for the requested type the method returns {@link Optional#empty()}.
032 *
033 * <h5 class='section'>Example:</h5>
034 * <p class='bjava'>
035 *    <jc>// A Conversion lambda that reads TimeZone from the session.</jc>
036 *    Conversion&lt;String, Calendar&gt; <jv>conv</jv> = (<jv>in</jv>, <jv>memberOf</jv>, <jv>session</jv>, <jv>args</jv>) -&gt; {
037 *       var <jv>tz</jv> = <jv>session</jv> != <jk>null</jk>
038 *          ? <jv>session</jv>.get(TimeZone.<jk>class</jk>).orElse(TimeZone.<jsm>getDefault</jsm>())
039 *          : TimeZone.<jsm>getDefault</jsm>();
040 *       <jc>// ... parse in using tz ...</jc>
041 *       <jk>return null</jk>;
042 *    };
043 * </p>
044 *
045 * <h5 class='section'>See Also:</h5><ul>
046 *    <li class='jc'>{@link Conversion}
047 *    <li class='jc'>{@link Converter}
048 * </ul>
049 */
050public interface ConverterSession {
051
052   /**
053    * Returns a contextual object of the specified type, or {@link Optional#empty()} if none is registered.
054    *
055    * @param <T> The object type.
056    * @param c The object type to look up.
057    * @return The contextual object wrapped in an {@link Optional}, or {@link Optional#empty()} if not available.
058    */
059   <T> Optional<T> get(Class<T> c);
060
061   /**
062    * Returns a named contextual object of the specified type, or {@link Optional#empty()} if none is registered.
063    *
064    * <p>
065    * The default implementation ignores the name and delegates to {@link #get(Class)}.
066    * Override this method when multiple objects of the same type need to be distinguished by name.
067    *
068    * @param <T> The object type.
069    * @param name The object name, or <jk>null</jk> to match any.
070    * @param c The object type to look up.
071    * @return The contextual object wrapped in an {@link Optional}, or {@link Optional#empty()} if not available.
072    */
073   default <T> Optional<T> get(String name, Class<T> c) {
074      return get(c);
075   }
076}