1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.juneau.commons.function;
18
19 /**
20 * A functional interface identical to {@link Runnable} but allows the {@link #run()} method to throw checked exceptions.
21 *
22 * <p>
23 * This interface is useful when you need to pass arbitrary code snippets to methods that expect a {@link Runnable},
24 * but your code may throw checked exceptions. Unlike {@link Runnable}, the {@link #run()} method can throw any
25 * {@link Throwable}, making it suitable for exception testing and fluent API patterns.
26 *
27 * <h5 class='section'>Features:</h5>
28 * <ul class='spaced-list'>
29 * <li>Functional interface - can be used with lambda expressions and method references
30 * <li>Exception support - allows checked exceptions to be thrown
31 * <li>Fluent API friendly - enables passing code snippets in method chains
32 * <li>Testing support - useful for exception testing scenarios
33 * </ul>
34 *
35 * <h5 class='section'>Use Cases:</h5>
36 * <ul class='spaced-list'>
37 * <li>Exception testing - verifying that code throws expected exceptions
38 * <li>Fluent interfaces - passing code snippets to builder methods
39 * <li>Conditional execution - wrapping code that may throw exceptions
40 * <li>Error handling - passing error-prone code to handlers
41 * </ul>
42 *
43 * <h5 class='section'>Usage:</h5>
44 * <p class='bjava'>
45 * <jc>// Exception testing</jc>
46 * Snippet <jv>code</jv> = () -> {
47 * <jk>throw new</jk> IllegalArgumentException(<js>"Expected error"</js>);
48 * };
49 * <jsm>assertThrown</jsm>(IllegalArgumentException.<jk>class</jk>, <jv>code</jv>);
50 *
51 * <jc>// Fluent API usage</jc>
52 * <jv>builder</jv>
53 * .setValue(<js>"test"</js>)
54 * .onError(() -> {
55 * <jk>throw new</jk> ValidationException(<js>"Invalid value"</js>);
56 * })
57 * .build();
58 *
59 * <jc>// Conditional execution with exceptions</jc>
60 * <jk>if</jk> (<jv>shouldExecute</jv>) {
61 * <jv>executeSafely</jv>(() -> {
62 * <jk>throw new</jk> IOException(<js>"File not found"</js>);
63 * });
64 * }
65 * </p>
66 *
67 * <h5 class='section'>Comparison with Runnable:</h5>
68 * <ul class='spaced-list'>
69 * <li><b>Runnable:</b> Cannot throw checked exceptions (must catch and wrap)
70 * <li><b>Snippet:</b> Can throw any {@link Throwable} (checked or unchecked)
71 * <li><b>Runnable:</b> Used for standard Java concurrency patterns
72 * <li><b>Snippet:</b> Used for exception testing and fluent APIs
73 * </ul>
74 *
75 * <h5 class='section'>See Also:</h5><ul>
76 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauEcosystemOverview">Juneau Ecosystem Overview</a>
77 * </ul>
78 */
79 public interface Snippet {
80
81 /**
82 * Executes arbitrary code and optionally throws an exception.
83 *
84 * <p>
85 * This method is the functional method of this interface. It can throw any {@link Throwable},
86 * including checked exceptions, which distinguishes it from {@link Runnable#run()}.
87 *
88 * <h5 class='section'>Example:</h5>
89 * <p class='bjava'>
90 * Snippet <jv>snippet</jv> = () -> {
91 * <jc>// Code that may throw exceptions</jc>
92 * <jk>if</jk> (<jv>invalid</jv>) {
93 * <jk>throw new</jk> IllegalArgumentException(<js>"Invalid state"</js>);
94 * }
95 * };
96 *
97 * <jv>snippet</jv>.run(); <jc>// May throw IllegalArgumentException</jc>
98 * </p>
99 *
100 * @throws Throwable Any throwable (checked or unchecked).
101 */
102 void run() throws Throwable;
103 }