Egothor/conflux
2
0
Fork 0
Code Issues Pull Requests Actions Packages Releases 9 Wiki Activity

Initial version.

Browse Source 
Signed-off-by: Leo Galambos <lg@hq.egothor.org>
This commit is contained in:
Leo Galambos
2025-07-03 22:30:33 +02:00
parent a194dab5e4
commit 54b21586c7
19 changed files with 2754 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
src/main/java/conflux/Ctx.java Normal file
View File

@@ -0,0 +1,202 @@
/**
* Copyright (C) 2025, Leo Galambos
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. All advertising materials mentioning features or use of this software must
* display the following acknowledgement:
* This product includes software developed by the Egothor project.
*
* 4. Neither the name of the copyright holder nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
package conflux;
import java.lang.ref.WeakReference;
import java.util.List;
import java.util.Map;
import java.util.Objects;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CopyOnWriteArrayList;
/**
* A globally accessible, type-safe context for sharing data between independent
* parts of an application. Supports listeners that are notified whenever a
* registered key's value changes.
*
* This implementation guarantees:
* <ul>
* <li>Strongly typed keys using {@link Key}</li>
* <li>One consistent type per key name</li>
* <li>Support for weak-referenced listeners to avoid memory leaks</li>
* <li>Thread-safe operations</li>
* </ul>
*
* Usage:
*
* <pre>
* Key<Integer> COUNT = Key.of("count", Integer.class);
* Ctx.INSTANCE.put(COUNT, 42);
* int v = Ctx.INSTANCE.get(COUNT);
* </pre>
*
* @author Leo Galambos
*/
public enum Ctx {
/**
* Singleton instance of the context.
*/
INSTANCE;
private final Map<Key<?>, Object> values = new ConcurrentHashMap<>();
private final Map<String, Class<?>> keyTypes = new ConcurrentHashMap<>();
private final Map<Key<?>, List<WeakReference<Listener<?>>>> listeners = new ConcurrentHashMap<>();
/**
* Stores or updates the value for a given key. If the key is used for the first
* time, its type is recorded. If the key has been used before with a different
* type, an exception will be thrown.
*
* After setting the value, any registered listeners for that key will be
* notified (if the value was modified).
*
* @param key the key
* @param value the value to store
* @param <T> the type of the value
* @throws IllegalStateException if the key is reused with a different type
*/
public <T> void put(Key<T> key, T value) {
keyTypes.compute(key.name(), (k, existingType) -> {
if (existingType == null) {
return key.type();
} else {
if (!existingType.equals(key.type())) {
throw new IllegalStateException(
"Key '" + key.name() + "' already associated with type " + existingType.getName());
}
return existingType;
}
});
@SuppressWarnings("unchecked")
T previous = (T) values.put(key, value);
if (Objects.deepEquals(value, previous)) {
// no change
return;
}
// notify listeners
var list = listeners.get(key);
if (list != null) {
for (var ref : list) {
var listener = ref.get();
if (listener != null) {
@SuppressWarnings("unchecked")
Listener<T> typedListener = (Listener<T>) listener;
typedListener.valueChanged(value);
}
}
// clean up dead weak references
list.removeIf(ref -> ref.get() == null);
}
}
/**
* Retrieves the value for the given key, or {@code null} if not set.
*
* @param key the key
* @param <T> the type
* @return the stored value or null
*/
@SuppressWarnings("unchecked")
public <T> T get(Key<T> key) {
return (T) values.get(key);
}
/**
* Checks if a value exists for the given key.
*
* @param key the key
* @return true if a value is present
*/
public boolean contains(Key<?> key) {
return values.containsKey(key);
}
/**
* Removes the value and any listeners for the given key.
*
* @param key the key
* @return the removed value, or null if absent
*/
public Object remove(Key<?> key) {
keyTypes.remove(key.name());
var removed = values.remove(key);
listeners.remove(key);
return removed;
}
/**
* Clears all keys and listeners from the context.
*/
public void clear() {
values.clear();
keyTypes.clear();
listeners.clear();
}
/**
* Registers a listener to be notified whenever the value for the key changes.
* The listener is weakly referenced to avoid preventing its garbage collection.
*
* @param key the key
* @param listener the listener
* @param <T> the type
*/
public <T> void addListener(Key<T> key, Listener<T> listener) {
listeners.computeIfAbsent(key, k -> new CopyOnWriteArrayList<>()).add(new WeakReference<>(listener));
}
/**
* Unregisters a previously registered listener for the key.
*
* @param key the key
* @param listener the listener to remove
* @param <T> the type
*/
public <T> void removeListener(Key<T> key, Listener<T> listener) {
var list = listeners.get(key);
if (list != null) {
list.removeIf(ref -> {
var l = ref.get();
return l == null || l.equals(listener);
});
if (list.isEmpty()) {
listeners.remove(key);
}
}
}
}

97
src/main/java/conflux/Key.java Normal file
View File

@@ -0,0 +1,97 @@
/**
* Copyright (C) 2025, Leo Galambos
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. All advertising materials mentioning features or use of this software must
* display the following acknowledgement:
* This product includes software developed by the Egothor project.
*
* 4. Neither the name of the copyright holder nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
package conflux;
/**
* Represents a strongly typed key for storing and retrieving values in the
* {@link Ctx} context.
*
* @param <T> the type of value associated with this key
* @author Leo Galambos
*/
public final class Key<T> { // NOPMD by Leo Galambos on 7/3/25, 10:29 PM
private final String name;
private final Class<T> type;
private Key(String name, Class<T> type) {
this.name = name;
this.type = type;
}
/**
* Creates a new typed key.
*
* @param name a unique key name
* @param type the class of the key's value type
* @param <T> the type
* @return a new {@code Key}
*/
public static <T> Key<T> of(String name, Class<T> type) { // NOPMD by Leo Galambos on 7/3/25, 10:29 PM
return new Key<>(name, type);
}
/**
* Returns the name of the key.
*
* @return the name
*/
public String name() {
return name;
}
/**
* Returns the type of the key.
*
* @return the type
*/
public Class<T> type() {
return type;
}
@Override
public int hashCode() {
return name.hashCode();
}
@Override
public boolean equals(Object obj) {
return obj instanceof Key<?> other && name.equals(other.name);
}
@Override
public String toString() {
return "Key[" + name + ", " + type.getSimpleName() + "]";
}
}

52
src/main/java/conflux/Listener.java Normal file
View File

@@ -0,0 +1,52 @@
/**
* Copyright (C) 2025, Leo Galambos
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. All advertising materials mentioning features or use of this software must
* display the following acknowledgement:
* This product includes software developed by the Egothor project.
*
* 4. Neither the name of the copyright holder nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
package conflux;
/**
* Functional interface for receiving value change notifications from the
* {@link Ctx} for a specific key.
*
* @param <T> the type of the observed value
* @author Leo Galambos
*/
@FunctionalInterface
public interface Listener<T> {
/**
* Called whenever the observed value changes.
*
* @param newValue the new value
*/
void valueChanged(T newValue);
}

162
src/test/java/conflux/CtxTest.java Normal file
View File

@@ -0,0 +1,162 @@
/**
* Copyright (C) 2025, Leo Galambos
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3. All advertising materials mentioning features or use of this software must
* display the following acknowledgement:
* This product includes software developed by the Egothor project.
*
* 4. Neither the name of the copyright holder nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
package conflux;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
import java.util.Arrays;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
/**
* Unit tests for the {@link Ctx} class. Covers put/get, type safety, and
* listener notifications.
*
* @author Leo Galambos
*/
public class CtxTest {
private Key<Integer> intKey;
private Key<String> stringKey;
private Key<byte[]> byteArrayKey;
@BeforeEach
void setup() {
intKey = Key.of("count", Integer.class);
stringKey = Key.of("status", String.class);
byteArrayKey = Key.of("buffer", byte[].class);
Ctx.INSTANCE.clear();
}
@Test
void testPutAndGet() {
System.out.println("testPutAndGet");
Ctx.INSTANCE.put(intKey, 42);
Integer result = Ctx.INSTANCE.get(intKey);
assertEquals(42, result);
System.out.println("...ok");
}
@Test
void testContainsAndRemove() {
System.out.println("testContainsAndRemove");
assertFalse(Ctx.INSTANCE.contains(intKey));
Ctx.INSTANCE.put(intKey, 100);
assertTrue(Ctx.INSTANCE.contains(intKey));
Object removed = Ctx.INSTANCE.remove(intKey);
assertEquals(100, removed);
assertFalse(Ctx.INSTANCE.contains(intKey));
System.out.println("...ok");
}
@Test
void testClear() {
System.out.println("testClear");
Ctx.INSTANCE.put(intKey, 1);
Ctx.INSTANCE.put(stringKey, "OK");
Ctx.INSTANCE.clear();
assertFalse(Ctx.INSTANCE.contains(intKey));
assertFalse(Ctx.INSTANCE.contains(stringKey));
System.out.println("...ok");
}
@Test
void testTypeSafety() {
System.out.println("testTypeSafety");
Ctx.INSTANCE.put(intKey, 5);
Exception ex = assertThrows(IllegalStateException.class, () -> {
Key<String> sameNameDifferentType = Key.of("count", String.class);
Ctx.INSTANCE.put(sameNameDifferentType, "oops");
});
assertTrue(ex.getMessage().contains("already associated with type"));
System.out.println("...ok");
}
@Test
void testListenerNotification() {
System.out.println("testListenerNotification");
var results = new StringBuilder();
Listener<Integer> listener = v -> results.append(v);
Ctx.INSTANCE.addListener(intKey, listener);
Ctx.INSTANCE.put(intKey, 11);
Ctx.INSTANCE.put(intKey, 22);
Ctx.INSTANCE.put(intKey, 22);
Ctx.INSTANCE.put(intKey, 33);
assertEquals("112233", results.toString());
System.out.println("...ok");
}
@Test
void testListenerNotificationWithArrays() {
System.out.println("testListenerNotificationWithArrays");
var results = new StringBuilder();
Listener<byte[]> listener = v -> results.append(Arrays.toString(v));
Ctx.INSTANCE.addListener(byteArrayKey, listener);
final byte[] _11 = { 1, 1 };
final byte[] _22 = { 2, 2 };
final byte[] _22x = { 2, 2 };
final byte[] _33 = { 3, 3 };
Ctx.INSTANCE.put(byteArrayKey, _11);
Ctx.INSTANCE.put(byteArrayKey, _22);
Ctx.INSTANCE.put(byteArrayKey, _22x);
Ctx.INSTANCE.put(byteArrayKey, _33);
assertEquals("[1, 1][2, 2][3, 3]", results.toString());
System.out.println("...ok");
}
@Test
void testListenerWeakReference() {
System.out.println("testListenerWeakReference");
var flag = new boolean[] { false };
{
Listener<Integer> tmpListener = v -> flag[0] = true;
Ctx.INSTANCE.addListener(intKey, tmpListener);
}
System.gc(); // encourage GC
Ctx.INSTANCE.put(intKey, 123);
// cannot fully verify weakref GC predictably in unit tests
assertTrue(flag[0] || !flag[0]);
System.out.println("...ok");
}
}