feat: add service locator API initial draft (#230)

Signed-off-by: Nathan Klick <nathan@swirldslabs.com>

fullstack-base-api/src/main/java/com/hedera/fullstack/base/api/collections/KeyValuePair.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.base.api.collections;
+
+import java.util.Objects;
+
+/**
+ * A simple key and value pair. The key must not be {@code null}; however, the value may be {@code null}.
+ * The {@link #equals(Object)} and {@link #hashCode()} methods are implemented to compare only the key.
+ *
+ * @param <K> the type of the key or left argument of the pair. The key must not be {@code null}.
+ * @param <V> the type of the value or right argument of the pair.
+ */
+public record KeyValuePair<K, V>(K key, V value) {
+    public KeyValuePair {
+        Objects.requireNonNull(key, "key must not be null");
+    }
+
+    /**
+     * Creates a new {@code KeyValuePair} with the given key and value.
+     *
+     * @param <K>   the type of the key or left argument of the pair. The key must not be {@code null}.
+     * @param <V>   the type of the value or right argument of the pair.
+     * @param key   the key. Must not be {@code null}.
+     * @param value the value. May be {@code null}.
+     * @return a new {@code KeyValuePair} with the given key and value.
+     */
+    public static <K, V> KeyValuePair<K, V> of(final K key, final V value) {
+        return new KeyValuePair<>(key, value);
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) return true;
+        if (!(o instanceof KeyValuePair<?, ?> that)) return false;
+        return Objects.equals(key, that.key);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(key);
+    }
+}

fullstack-base-api/src/main/java/com/hedera/fullstack/base/api/collections/Pair.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.base.api.collections;
+
+/**
+ * A simple pair of related or unrelated values. The values may be of the same type or different types. Both values may
+ * be {@code null}.
+ *
+ * @param <L>   type of the left value.
+ * @param <R>   type of the right value.
+ * @param left  the left value.
+ * @param right the right value.
+ */
+public record Pair<L, R>(L left, R right) {
+
+    /**
+     * Creates a new {@code Pair} with the given left and right values.
+     *
+     * @param <L>   type of the left value.
+     * @param <R>   type of the right value.
+     * @param left  the left value.
+     * @param right the right value.
+     * @return a new {@code Pair} with the given left and right values.
+     */
+    public static <L, R> Pair<L, R> of(final L left, final R right) {
+        return new Pair<>(left, right);
+    }
+}

fullstack-base-api/src/main/java/com/hedera/fullstack/base/api/reflect/ClassConstructionException.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2023 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.fullstack.base.api.reflect;
+
+/**
+ * Exception thrown when a service cannot be constructed by a ServiceSupplier.
+ */
+public class ClassConstructionException extends RuntimeException {
+
+    /**
+     * Constructs a new runtime exception with the specified detail message.
+     * The cause is not initialized, and may subsequently be initialized by a
+     * call to {@link #initCause}.
+     *
+     * @param message the detail message. The detail message is saved for
+     *                later retrieval by the {@link #getMessage()} method.
+     */
+    public ClassConstructionException(final String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a new runtime exception with the specified detail message and
+     * cause.  <p>Note that the detail message associated with
+     * {@code cause} is <i>not</i> automatically incorporated in
+     * this runtime exception's detail message.
+     *
+     * @param message the detail message (which is saved for later retrieval
+     *                by the {@link #getMessage()} method).
+     * @param cause   the cause (which is saved for later retrieval by the
+     *                {@link #getCause()} method).  (A {@code null} value is
+     *                permitted, and indicates that the cause is nonexistent or
+     *                unknown.)
+     */
+    public ClassConstructionException(final String message, final Throwable cause) {
+        super(message, cause);
+    }
+}