001/*
002 * VM-Operator
003 * Copyright (C) 2024 Michael N. Lipp
004 * 
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
017 */
018
019package org.jdrupes.vmoperator.manager.events;
020
021import java.util.Collection;
022import java.util.Optional;
023import java.util.Set;
024import org.jgrapes.core.Channel;
025
026/**
027 * Supports the lookup of a channel by a name (an id). As a convenience,
028 * it is possible to additionally associate arbitrary data with the entry
029 * (and thus with the channel). Note that this interface defines a
030 * read-only view of the dictionary.
031 *
032 * @param <K> the key type
033 * @param <C> the channel type
034 * @param <A> the type of the associated data
035 */
036public interface ChannelDictionary<K, C extends Channel, A> {
037
038    /**
039     * Combines the channel and the associated data.
040     *
041     * @param <C> the channel type
042     * @param <A> the type of the associated data
043     * @param channel the channel
044     * @param associated the associated
045     */
046    @SuppressWarnings("PMD.ShortClassName")
047    public record Value<C extends Channel, A>(C channel, A associated) {
048    }
049
050    /**
051     * Returns all known keys.
052     *
053     * @return the keys
054     */
055    Set<K> keys();
056
057    /**
058     * Return all known values.
059     *
060     * @return the collection
061     */
062    Collection<Value<C, A>> values();
063
064    /**
065     * Returns the channel and associates data registered for the key
066     * or an empty optional if no entry exists.
067     * 
068     * @param key the key
069     * @return the result
070     */
071    Optional<Value<C, A>> value(K key);
072
073    /**
074     * Return all known channels.
075     *
076     * @return the collection
077     */
078    default Collection<C> channels() {
079        return values().stream().map(v -> v.channel).toList();
080    }
081
082    /**
083     * Returns the channel registered for the key or an empty optional
084     * if no mapping exists.
085     *
086     * @param key the key
087     * @return the optional
088     */
089    default Optional<C> channel(K key) {
090        return value(key).map(b -> b.channel);
091    }
092
093    /**
094     * Returns all known associated data.
095     *
096     * @return the collection
097     */
098    default Collection<A> associated() {
099        return values().stream()
100            .filter(v -> v.associated() != null)
101            .map(v -> v.associated).toList();
102    }
103
104    /**
105     * Return the data associated with the entry for the channel.
106     *
107     * @param key the key
108     * @return the data
109     */
110    default Optional<A> associated(K key) {
111        return value(key).map(b -> b.associated);
112    }
113}