Debian Codegraph @

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Parameters.java

raw
1 /*
2 * Copyright (c) 2021 Red Hat and others
3 *
4 * This program and the accompanying materials are made available under the
5 * Apache Software License 2.0 which is available at:
6 * https://www.apache.org/licenses/LICENSE-2.0.
7 *
8 * SPDX-License-Identifier: Apache-2.0
9 */
10
11 package jakarta.enterprise.inject.build.compatible.spi;
12
13 /**
14 * A {@code String}-keyed parameter map. The parameter mappings are defined
15 * by a synthetic component builder. The CDI container passes the parameter map
16 * to functions defined by the same synthetic component builder, whenever
17 * it needs to invoke those functions. That is:
18 *
19 * <ul>
20 * <li>a synthetic bean {@linkplain SyntheticBeanCreator creation} and
21 * {@linkplain SyntheticBeanDisposer destruction} function, defined by
22 * {@link SyntheticBeanBuilder};</li>
23 * <li>a synthetic observer {@linkplain SyntheticObserver notification}
24 * function, defined by {@link SyntheticObserverBuilder}.</li>
25 * </ul>
26 *
27 * Parameter values are transferred from the builder to the {@code Parameters}-accepting
28 * function without a change. For example, if the builder defines an {@code int} parameter,
29 * it must be looked up as {@code int} and cannot be looked up as {@code long}.
30 * <p>
31 * Values of primitive types may be looked up either using the primitive type (such as
32 * {@code int.class}), or using the corresponding wrapper type ({@code Integer.class}).
33 * The return value is always of the wrapper type, so that {@code null} can be returned
34 * when the parameter does not exist. Note that this does not apply to arrays
35 * of primitive types; an {@code int[]} cannot be looked up as {@code Integer[]}.
36 * This is because arrays are reference types and so {@code null} can be returned.
37 * <p>
38 * Class-typed parameters are available as instances of {@link Class}, even if an instance
39 * of {@code ClassInfo} was passed to the builder.
40 * <p>
41 * Annotation-typed parameters are available as instances of the annotation type,
42 * even if an instance of {@code AnnotationInfo} was passed to the builder.
43 */
44 public interface Parameters {
45 /**
46 * Returns the value of a parameter with given {@code key}. The value is expected to be of given {@code type}.
47 *
48 * @param key the parameter key; must not be {@code null}
49 * @param type the parameter type; must not be {@code null}
50 * @param <T> the parameter type
51 * @return the parameter value, or {@code null} if parameter with given {@code key} does not exist
52 * @throws ClassCastException if the parameter exists, but is of a different type
53 */
54 <T> T get(String key, Class<T> type);
55
56 /**
57 * Returns the value of a parameter with given {@code key}. The value is expected to be of given {@code type}.
58 * If the parameter does not exist, returns {@code defaultValue}.
59 *
60 * @param key the parameter key; must not be {@code null}
61 * @param type the parameter type; must not be {@code null}
62 * @param defaultValue the value to return if parameter with given {@code key} does not exist
63 * @param <T> the parameter type
64 * @return the parameter value, or {@code defaultValue} if parameter with given {@code key} does not exist
65 * @throws ClassCastException if the parameter exists, but is of a different type
66 */
67 <T> T get(String key, Class<T> type, T defaultValue);
68 }