001
002/*
003 * Units of Measurement Common Library
004 * Copyright (c) 2005-2016, Jean-Marie Dautelle, Werner Keil, V2COM.
005 *
006 * All rights reserved.
007 *
008 * Redistribution and use in source and binary forms, with or without modification,
009 * are permitted provided that the following conditions are met:
010 *
011 * 1. Redistributions of source code must retain the above copyright notice,
012 *    this list of conditions and the following disclaimer.
013 *
014 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions
015 *    and the following disclaimer in the documentation and/or other materials provided with the distribution.
016 *
017 * 3. Neither the name of JSR-363 nor the names of its contributors may be used to endorse or promote products
018 *    derived from this software without specific prior written permission.
019 *
020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
021 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
022 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
023 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
024 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
027 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
029 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
030 */
031package tec.uom.lib.common.function;
032
033import javax.measure.Quantity;
034
035/**
036 * Represents an operation on a single {@link Quantity} that produces a
037 * result of type {@link Quantity}.
038 * <p>
039 * Examples might be an operator that rounds the amount to the nearest 1000, or
040 * one that performs other quantity operations.
041 * <p>
042 * 
043 * <pre>
044 * // Example
045 * result = thisOperator.apply(quantity);
046 * </pre>
047 *  
048 * <h1>Implementation specification</h1>
049 * The implementation must take the input object and apply it. The
050 * implementation defines the logic of the operator and is responsible for
051 * documenting that logic. It may use any method on {@code Quantity} to
052 * determine the result.
053 * <p>
054 * The input object must not be altered. Instead, an altered copy of the
055 * original must be returned. This provides equivalent, safe behavior for
056 * immutable and mutable quantities.
057 * <p>
058 * This method may be called from multiple threads in parallel. It must be
059 * thread-safe when invoked.
060 * 
061 * <p>
062 * This interface is modeled after {@code java.util.function.UnaryOperator} in Java SE 8, 
063 * but intended to be Java ME compatible as well.
064 * 
065 * @author Werner Keil
066 * 
067 * @version 0.2, September 4, 2016
068 */
069public interface QuantityOperator<Q extends Quantity<Q>> {
070
071    /**
072     * Applies the operator on the given quantity.
073     * @param quantity the quantity to be operated on.
074     * @return the applied quantity.
075     */
076    Quantity<Q> apply(Quantity<Q> quantity);
077}