com.memority.citadel.shared.api.im.HasMutableValues 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;

/**
 * A generic interface for classes that hold data, that provides a common write access to an object properties
 * with a clean interface and well-defined semantics.
 */
public interface HasMutableValues extends HasValues {
    /**
     * Set the value of the named property to the given single value.
     *
     * @param name the property name
     * @param newValue the new value, maybe null
     * @param  the property value type
     */
     void setValue(String name, T newValue);

    /**
     * Set the value of the named property to the given multiple values.
     *
     * @param name the property name
     * @param newValues the new values, maybe empty, but not null
     * @param  the property value type
     */
     void setValues(String name, List newValues);

    /**
     * Same as addValue(name, additionalValue, false, false)
     *
     * @param name the property name
     * @param additionalValue the new value to add, cannot be null
     * @param  the property value type
     * @return true if this action changed the property value, false otherwise
     */
    default  boolean addValue(String name, T additionalValue) {
        return addValue(name, additionalValue, false, false);
    }

    /**
     * Add the given additional value to the given property. The property should be a list, otherwise an
     * {@link IllegalArgumentException} will be thrown. Operation can be configured to only add distinct values,
     * and to optionally sort the resulting list.
     *
     * @param name the property name
     * @param additionalValue the value to be added
     * @param distinct whether to add the value if it is already in the list
     * @param sorted whether to sort the resulting list
     * @param  the property value type
     * @return true if this action changed the property value, false otherwise
     */
     boolean addValue(String name, T additionalValue, boolean distinct, boolean sorted);

    /**
     * Shortcut to {@link #addValues(String, List, boolean, boolean)}, with {@code distinct = false} and {@code sorted = false}
     *
     * @param name the property name
     * @param additionalValues the new values to add, cannot be nor contain null
     * @param  the property value type
     * @return true if this action changed the property value, false otherwise
     */
    default  boolean addValues(String name, List additionalValues) {
        return addValues(name, additionalValues, false, false);
    }

    /**
     * Add the given additional value to the given property.
     *
     * @param name the property name
     * @param additionalValues the new values to add, cannot be nor contain null
     * @param distinct if {@code true} then only distinct values are retained
     * @param sorted if {@code true} then values are sorted according to their natural order
     * @param  the property value type
     * @return true if this action changed the property value, false otherwise
     */
     boolean addValues(String name, List additionalValues, boolean distinct, boolean sorted);

    /**
     * Remove the given value from the property values. The property should be a list, otherwise an
     * {@link IllegalArgumentException} will be thrown.
     *
     * @param name the property name
     * @param valueToRemove the value to remove
     * @param  the property value type
     * @return true if this action changed the property value, false otherwise
     */
     boolean removeValue(String name, T valueToRemove);

    /**
     * Same as {@link #removeValue(String, Object)}, only multiple values are removed at a time.
     * @param name the property name
     * @param valuesToRemove the values to remove
     * @param  the property value type
     * @return true if this action changed the property value, false otherwise
     */
     boolean removeValues(String name, List valuesToRemove);

    /**
     * Remove all values of the property with the given name.  A subsequent call to {@link #hasValue(String)} will yield false,
     * however a call to {@link #has(String)} will still yield true and the property name will be listed by {@link #names()}.
     *
     * @param name the name of the property to clear
     * @return true if this action changed the property value, false otherwise
     */
    boolean remove(String name);

    /**
     * Completely remove the property with the given name. A subsequent call to {@link #has(String)} will yield false
     *
     * @param name the name of the property to delete
     * @return true if this action actually deleted the property, false otherwise
     */
    boolean delete(String name);
}