com.helger.commons.collection.attr.IAttributeContainer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ph-commons Show documentation
Java 1.8+ Library with tons of utility classes required in all projects
The newest version!
/*
 * Copyright (C) 2014-2024 Philip Helger (www.helger.com)
 * philip[at]helger[dot]com
 *
 * 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.helger.commons.collection.attr;

import java.util.Map;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

import com.helger.commons.CGlobal;
import com.helger.commons.ValueEnforcer;
import com.helger.commons.annotation.ReturnsMutableCopy;
import com.helger.commons.annotation.ReturnsMutableObject;
import com.helger.commons.callback.CallbackList;
import com.helger.commons.callback.ICallback;
import com.helger.commons.collection.impl.ICommonsMap;
import com.helger.commons.equals.EqualsHelper;
import com.helger.commons.state.EChange;
import com.helger.commons.state.EContinue;
import com.helger.commons.traits.IGetterByKeyTrait;

/**
 * Base interface for a generic read-only attribute container. It maps keys to
 * values.

 * Note: don't implement Iterable<Map.Entry<...>>
 * because this would make the object ambiguous to e.g.
 * HashCodeGenerator
 *
 * @author Philip Helger
 * @param 
 *        Key type
 * @param 
 *        Value type
 */
public interface IAttributeContainer  extends ICommonsMap , IGetterByKeyTrait 
{
  @FunctionalInterface
  interface IBeforeSetValueCallback  extends ICallback
  {
    /**
     * Invoked before a new value is set
     *
     * @param aName
     *        The attribute key. May not be null.
     * @param aNewValue
     *        The new value to be set. May be null.
     * @return {@link EContinue#CONTINUE} if the value can be set,
     *         false if the value cannot be set.
     */
    @Nonnull
    EContinue beforeSetValue (@Nonnull KEYTYPE aName, @Nullable VALUETYPE aNewValue);
  }

  @FunctionalInterface
  interface IAfterSetValueCallback  extends ICallback
  {
    /**
     * Method that is invoked after a value changed.
     *
     * @param aName
     *        The changed key. Neither null nor empty.
     * @param aOldValue
     *        The old value. May be null.
     * @param aNewValue
     *        The new value. May be null in which case the value
     *        was removed.
     */
    void afterSetValue (@Nonnull KEYTYPE aName, @Nullable VALUETYPE aOldValue, @Nullable VALUETYPE aNewValue);
  }

  /**
   * Get the attribute value associated to the given attribute name.
   *
   * @param aName
   *        the attribute name
   * @return null if no such value exists
   */
  @Nullable
  default VALUETYPE getValue (@Nullable final KEYTYPE aName)
  {
    return get (aName);
  }

  /**
   * Get the attribute value associated to the given attribute name.

   * Avoid throwing TypeConverterException by providing a default value.
   *
   * @param aName
   *        the attribute name
   * @return The attribute value or
   *         {@link com.helger.commons.CGlobal#ILLEGAL_UINT} if no such
   *         attribute exists
   */
  @Override
  default int getAsInt (@Nullable final KEYTYPE aName)
  {
    return getAsInt (aName, CGlobal.ILLEGAL_UINT);
  }

  /**
   * Get the attribute value associated to the given attribute name.

   * Avoid throwing TypeConverterException by providing a default value.
   *
   * @param aName
   *        the attribute name
   * @return The attribute value or
   *         {@link com.helger.commons.CGlobal#ILLEGAL_ULONG} if no such
   *         attribute exists
   */
  @Override
  default long getAsLong (@Nullable final KEYTYPE aName)
  {
    return getAsLong (aName, CGlobal.ILLEGAL_ULONG);
  }

  /**
   * Get the attribute value associated to the given attribute name.

   * Avoid throwing TypeConverterException by providing a default value.
   *
   * @param aName
   *        the attribute name
   * @return The attribute value or
   *         {@link com.helger.commons.CGlobal#ILLEGAL_UINT} if no such
   *         attribute exists
   */
  @Override
  default float getAsFloat (@Nullable final KEYTYPE aName)
  {
    return getAsFloat (aName, CGlobal.ILLEGAL_UINT);
  }

  /**
   * Get the attribute value associated to the given attribute name.
   *
   * @param aName
   *        the attribute name
   * @return The attribute value or
   *         {@link com.helger.commons.CGlobal#ILLEGAL_UINT} if no such
   *         attribute exists
   */
  @Override
  default double getAsDouble (@Nullable final KEYTYPE aName)
  {
    return getAsDouble (aName, CGlobal.ILLEGAL_UINT);
  }

  /**
   * Get the attribute value associated to the given attribute name.

   * Avoid throwing TypeConverterException by providing a default value.
   *
   * @param aName
   *        the attribute name
   * @return The attribute value or false if no such attribute
   *         exists
   */
  @Override
  default boolean getAsBoolean (@Nullable final KEYTYPE aName)
  {
    return getAsBoolean (aName, false);
  }

  /**
   * @return Callbacks to be invoked before values are set. May not be
   *         null.
   */
  @Nonnull
  @ReturnsMutableObject
  CallbackList > beforeSetValueCallbacks ();

  /**
   * @return Callbacks to be invoked after values are set. May not be
   *         null.
   */
  @Nonnull
  @ReturnsMutableObject
  CallbackList > afterSetValueCallbacks ();

  /**
   * Set/overwrite an attribute value including before and after callbacks.
   *
   * @param aName
   *        The name of the attribute. May not be null.
   * @param aNewValue
   *        The new value of the attribute. May be null.
   * @return {@link EChange#CHANGED} if something changed,
   *         {@link EChange#UNCHANGED} otherwise.
   * @see #beforeSetValueCallbacks()
   * @see #afterSetValueCallbacks()
   * @see #removeObject(Object)
   */
  @Nonnull
  default EChange putIn (@Nonnull final KEYTYPE aName, @Nullable final VALUETYPE aNewValue)
  {
    ValueEnforcer.notNull (aName, "Name");

    // Before change checking callback
    if (beforeSetValueCallbacks ().forEachBreakable (x -> x.beforeSetValue (aName, aNewValue)).isBreak ())
      return EChange.UNCHANGED;

    // Set and compare
    final VALUETYPE aOldValue = put (aName, aNewValue);
    if (EqualsHelper.equals (aNewValue, aOldValue))
      return EChange.UNCHANGED;

    // After change callback
    afterSetValueCallbacks ().forEach (x -> x.afterSetValue (aName, aOldValue, aNewValue));
    return EChange.CHANGED;
  }

  @Nonnull
  default EChange putAllIn (@Nullable final Map  aAttrs)
  {
    EChange eChange = EChange.UNCHANGED;
    if (aAttrs != null)
      for (final Map.Entry  aEntry : aAttrs.entrySet ())
        eChange = eChange.or (putIn (aEntry.getKey (), aEntry.getValue ()));
    return eChange;
  }

  @Nonnull
  @ReturnsMutableCopy
  IAttributeContainer  getClone ();
}