org.microbean.bean.Reducible Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of microbean-bean Show documentation
microBean™ Bean: Utility classes for implementing beans.
There is a newer version: 0.0.12
/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
 *
 * Copyright © 2024 microBean™.
 *
 * 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 org.microbean.bean;

import java.util.List;
import java.util.Objects;

import java.util.concurrent.ConcurrentHashMap;

import java.util.function.BiFunction;
import java.util.function.Function;

/**
 * A {@linkplain FunctionalInterface functional interface} whose implementations can reduce an unspecified notional
 * collection of elements to a single element according to some criteria.
 *
 * This interface is related to, but should not be confused with, the {@link Reducer} interface, which can be used to
 * build {@link Reducible} instances.
 *
 * @param  the type of criteria
 *
 * @param  the element type
 *
 * @author Laird Nelson
 *
 * @see #reduce(Object)
 *
 * @see Reducer
 */
@FunctionalInterface
public interface Reducible {


  /**
   * Given a criteria object, which may be {@code null}, returns an object that represents the reduction of a
   * notional collection of objects.
   *
   * Most {@link Reducible} implementations will return determine values from invocations of this method, but there
   * is no requirement to do so.
   *
   * @param criteria the criteria; may be {@code null} to indicate no criteria
   *
   * @return a single object, or {@code null}
   *
   * @exception ReductionException if reduction could not occur or if an error occurs
   */
  public T reduce(final C criteria);


  /*
   * Static methods.
   */


  public static  Reducible of(final Selectable selectable,
                                          final Reducer r) {
    return of(selectable, r, Reducer::fail);
  }

  public static  Reducible of(final Selectable selectable,
                                          final Reducer r,
                                          final BiFunction, ? super C, ? extends E> failureHandler) {
    Objects.requireNonNull(selectable, "selectable");
    Objects.requireNonNull(r, "r");
    final BiFunction, ? super C, ? extends E> fh = Objects.requireNonNull(failureHandler, "failureHandler");
    return c -> r.reduce(selectable.select(c), c, fh);
  }

  public static  Reducible ofCaching(final Selectable selectable,
                                                 final Reducer r) {
    return ofCaching(selectable, r, Reducer::fail);
  }

  public static  Reducible ofCaching(final Selectable selectable,
                                                 final Reducer r,
                                                 final BiFunction, ? super C, ? extends E> failureHandler) {
    return ofCaching(selectable, r, failureHandler, new ConcurrentHashMap()::computeIfAbsent);
  }

  public static  Reducible ofCaching(final Selectable selectable,
                                                 final Reducer r,
                                                 final BiFunction, ? super C, ? extends E> failureHandler,
                                                 final BiFunction, ? extends E> computeIfAbsent) {
    final Reducible rd = of(selectable, r, failureHandler);
    return c -> computeIfAbsent.apply(c, rd::reduce);
  }

}