org.cp.elements.lang.Transformer Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of cp-elements Show documentation

Java Simplified. Extensions and Useful Constructs for the Java Platform. Codeprimate Elements (a.k.a. cp-elements) is a Java library and micro-framework used to simplify the development of software applications written in Java. Elements packages several APIs into one library in order to address various application concerns and aspects of software design and development collectively and conveniently. Elements is a highly simple, yet robust and proven library built on solid OO principles, software design patterns and best practices to effectively solve common and reoccurring problems in software development.

There is a newer version: 2.0.0-M1

Show newest version

/*
 * Copyright 2016 Author or Authors.
 *
 * 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.cp.elements.lang;

import java.util.function.UnaryOperator;

import org.cp.elements.data.conversion.Converter;

/**
 * The {@link Transformer} interface defines a contract for implementing {@link Class classes}
 * who's {@link Object implementations} transform data from one value to another value
 * of the same {@link Class type}.
 *
 * The transformed value of {@link Class type T} could be a more qualified, precise or accurate {@link Object value}
 * than the {@link Object original value}.  For example, transforming an {@link Integer} into a {@link Double}
 * with more precision using a {@link Transformer Transformer<Number>}.
 *
 * Another use case for a {@link Transformer} might be to {@literal Decorate}, or enhance the functionality
 * of an {@link Object} yet still retain the same {@link Class interface}.
 *
 * Use a {@link Converter Converter<S, T>} if you want to "convert", or adapt a value from one {@link Class type}
 * to another {@link Class type}.
 *
 * The {@link Transformer} interface is equivalent to the {@link UnaryOperator} in Java.
 *
 * @author John J. Blum
 * @param  {@link Class type} of the data value (datum) to transform as well as the transformed data value (datum).
 * @see java.lang.FunctionalInterface
 * @see java.util.function.UnaryOperator
 * @since 1.0.0
 */
@FunctionalInterface
public interface Transformer extends UnaryOperator {

  /**
   * Identify {@link Transformer} returning the {@link Object value} to transform unaltered.
   *
   * @param  {@link Class type} of the {@link Object value} to transform.
   * @return the Identity {@link Transformer}.
   * @see java.util.function.UnaryOperator#identity()
   */
  static  Transformer identity() {
    return value -> value;
  }

  /**
   * Applies this {@link Transformer} to the given {@link T value} producing a new result
   * of the same {@link Class type T}.
   *
   * @param value {@link T value} to transform.
   * @return the {@link T transformed value}.
   * @see #transform(Object)
   */
  @Override
  default T apply(T value) {
    return transform(value);
  }

  /**
   * Transforms the given {@link T value} of {@link Class type T} into another {@link T value}
   * of the same {@link Class type T}.
   *
   * @param value {@link T value} to transform.
   * @return the {@link T transformed value}.
   */
  T transform(T value);

}