com.memority.citadel.shared.api.im.HasValues Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of citadel-api Show documentation
This artifact provides the API classes that are necessary to implement general configuration Rules on the Memority IM platform.
There is a newer version: 3.43.1
Show newest version
/*
 * Copyright (c) 2016-2023 Memority. All Rights Reserved.
 *
 * This file is part of Memority Citadel API , a Memority project.
 *
 * This file is released under the Memority Public Artifacts End-User License Agreement,
 * see 
 * Unauthorized copying of this file, via any medium is strictly prohibited.
 */
package com.memority.citadel.shared.api.im;

import java.util.List;
import java.util.Set;

/**
 * A generic interface for classes that hold data, that provides a common access to an object properties
 * with a clean interface and well defined semantics.
 */
public interface HasValues {
    /**
     * Return the values as a list, even if the property is mono-valued. This method
     * never returns null.
     * 
     * Returns an empty list in the following cases:
     * 

     *     if the attribute is not found
     *     if the attribute does not have any value
     * 
     *
     * @param name the property name
     * @return the list of values, may be empty but never null
     */
    List values(String name);

    /**
     * Same as {@link HasValues#values(String)}, but with an automatic cast to the given
     * typeClass.
     *
     * @see #values(String)
     * @param name the property name
     * @param typeClass the class for the expected value type
     * @param  the expected value type
     * @return the list of values, may be empty but never null
     * @throws ClassCastException if the actual value cannot be cast to the given typeClass
     */
    @SuppressWarnings("unchecked")
    default  List values(String name, Class typeClass) {
        List values = values(name);
        for (Object value : values) {
            if (value == null) {
                continue;
            }
            if (!typeClass.isAssignableFrom(value.getClass())) {
                throw new ClassCastException(String.format("Actual value type of '%s' is '%s' (incompatible with '%s')",
                        name, value.getClass(), typeClass));
            }
        }
        return (List)values;
    }

    /**
     * Return a single property value of the property with the given name:
     * 
     *     If the property is mono-valued, return its value, which may be null
     *     If the property is multi-valued, return the first value, unless there is no value in which case return null
     * 
     *
     * This method should be used preferably on properties which are known to be mono-valued.
     *
     * @param name the property name
     * @return a single value of the property
     */
    Object value(String name);

    /**
     * Same as {@link HasValues#value(String)}, but with an automatic cast to the given
     * typeClass.
     *
     * @see #value(String)
     * @param name the property name
     * @param typeClass the class for the expected attribute value type
     * @param  the expected value type
     * @return the value or first value if multiple values, maybe null
     * @throws ClassCastException if the actual value cannot be cast to the given typeClass
     */
    default  T value(String name, Class typeClass) {
        Object value = value(name);

        if (value == null) {
            return null;
        }

        if (!typeClass.isAssignableFrom(value.getClass())) {
            throw new ClassCastException(String.format("Actual value type of '%s' is '%s' (incompatible with '%s')",
                    name, value.getClass(), typeClass));
        }

        @SuppressWarnings("unchecked")
        T result = (T) value;
        return result;
    }

    /**
     * Returns true if and only if this object has a value for the given name.
     *
     * @param name the property name
     * @return true if there is a value for the given name, false otherwise
     */
    boolean hasValue(String name);

    /**
     * Returns true if and only if this object has a property with the given name. The property value
     * may or may not be null.
     * @param name the property name
     * @return true if there is a property of this name, false otherwise
     */
    boolean has(String name);

    /**
     * Returns the list of property names held by this object.
     *
     * @return the list of property names, maybe empty but never null
     */
    Set names();
}