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.function;
018
019/**
020 * A functional interface representing a supplier of results that may throw a checked exception.
021 *
022 * <p>
023 * This interface extends the standard Java {@link java.util.function.Supplier} pattern to allow
024 * the {@link #get()} method to throw checked exceptions. This is useful when you need to pass
025 * suppliers that may throw exceptions (such as I/O operations) to methods that expect functional
026 * interfaces.
027 *
028 * <h5 class='section'>Features:</h5>
029 * <ul class='spaced-list'>
030 *    <li>Functional interface - can be used with lambda expressions and method references
031 *    <li>Exception support - allows checked exceptions to be thrown
032 *    <li>Compatible with Supplier - can be used where Supplier is expected (exceptions are wrapped)
033 * </ul>
034 *
035 * <h5 class='section'>Use Cases:</h5>
036 * <ul class='spaced-list'>
037 *    <li>Suppliers that perform I/O operations (file reading, network calls)
038 *    <li>Suppliers that may throw business logic exceptions
039 *    <li>Lazy initialization that may fail
040 *    <li>Resource creation that may throw exceptions
041 * </ul>
042 *
043 * <h5 class='section'>Usage:</h5>
044 * <p class='bjava'>
045 *    <jc>// Lambda with exception</jc>
046 *    ThrowingSupplier&lt;String&gt; <jv>fileReader</jv> = () -&gt; {
047 *       <jk>return new</jk> String(Files.readAllBytes(Paths.get(<js>"data.txt"</js>)));
048 *    };
049 *
050 *    <jc>// Method reference</jc>
051 *    ThrowingSupplier&lt;Connection&gt; <jv>dbConnection</jv> = <jv>dataSource</jv>::getConnection;
052 *
053 *    <jc>// Usage in try-catch</jc>
054 *    <jk>try</jk> {
055 *       String <jv>content</jv> = <jv>fileReader</jv>.get();
056 *    } <jk>catch</jk> (Exception <jv>e</jv>) {
057 *       <jc>// Handle exception</jc>
058 *    }
059 * </p>
060 *
061 * <h5 class='section'>Comparison with Supplier:</h5>
062 * <ul class='spaced-list'>
063 *    <li><b>Supplier:</b> Cannot throw checked exceptions (must catch and wrap)
064 *    <li><b>ThrowingSupplier:</b> Can throw checked exceptions directly
065 *    <li><b>Supplier:</b> Used for standard functional programming patterns
066 *    <li><b>ThrowingSupplier:</b> Used when operations may fail with checked exceptions
067 * </ul>
068 *
069 * <h5 class='section'>See Also:</h5><ul>
070 *    <li class='jc'>{@link ThrowingFunction} - Function that throws exceptions
071 *    <li class='jc'>{@link ThrowingConsumer} - Consumer that throws exceptions
072 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauCommonsBasics">juneau-commons Basics</a>
073 * </ul>
074 *
075 * @param <T> The type of results supplied by this supplier.
076 */
077@FunctionalInterface
078public interface ThrowingSupplier<T> {
079
080   /**
081    * Gets a result, potentially throwing a checked exception.
082    *
083    * <h5 class='section'>Example:</h5>
084    * <p class='bjava'>
085    *    ThrowingSupplier&lt;String&gt; <jv>supplier</jv> = () -&gt; {
086    *       <jk>if</jk> (<jv>fileNotFound</jv>) {
087    *          <jk>throw new</jk> FileNotFoundException(<js>"File not found"</js>);
088    *       }
089    *       <jk>return</jk> <js>"content"</js>;
090    *    };
091    *
092    *    <jk>try</jk> {
093    *       String <jv>result</jv> = <jv>supplier</jv>.get();
094    *    } <jk>catch</jk> (FileNotFoundException <jv>e</jv>) {
095    *       <jc>// Handle exception</jc>
096    *    }
097    * </p>
098    *
099    * @return A result.
100    * @throws Exception If an error occurs during result computation.
101    */
102   T get() throws Exception;
103}