001/**
002 * RealInductor.java
003 *
004 * Copyright (c) 2004-2012, Nicole C. Tedesco.  All rights reserved.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at:
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package net.sf.jaccumulator.reals;
020
021import java.util.NoSuchElementException;
022
023/**
024 * Imparts real values into other reals
025 *
026 * @since JAccumulator 4.0
027 * @author Nicole Tedesco (<a
028 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
029 */
030public interface RealInductor<REAL extends RealInductor<REAL>>
031{
032    /**
033     * Decrement the value of this real then induce its original value into
034     * the specified target
035     *
036     * @param <R>
037     *        the target type
038     * @param aTarget
039     *        a target into which the current value of this real will be
040     *        induced, prior to decrementing
041     * @return the target
042     * @throws UnsupportedOperationException
043     *         this target primitive cannot be changed
044     * @throws IllegalStateException
045     *         this target primitive cannot be changed at this time
046     * @throws NullPointerException
047     *         a {@code null} value was provided when none was expected
048     * @throws NoSuchElementException
049     *         an expected parameter was not found in the parameter source
050     */
051    public <R extends Real<?>> R inducePostDecrement(
052        final R aTarget )
053        throws NullPointerException,
054            NoSuchElementException,
055            UnsupportedOperationException,
056            IllegalStateException;
057
058    /**
059     * Increment the value of this real then induce its original value into
060     * the specified target
061     *
062     * @param <R>
063     *        the target type
064     * @param aTarget
065     *        a target into which the current value of this real will be
066     *        induced, prior to incrementing
067     * @return the target
068     * @throws UnsupportedOperationException
069     *         this target primitive cannot be changed
070     * @throws IllegalStateException
071     *         this target primitive cannot be changed at this time
072     * @throws NullPointerException
073     *         a {@code null} value was provided when none was expected
074     * @throws NoSuchElementException
075     *         an expected parameter was not found in the parameter source
076     */
077    public <R extends Real<?>> R inducePostIncrement(
078        final R aTarget )
079        throws NullPointerException,
080            NoSuchElementException,
081            UnsupportedOperationException,
082            IllegalStateException;
083
084    /**
085     * Induce the current value of this real into the specified target
086     *
087     * @param <R>
088     *        the target type
089     * @param aTarget
090     *        a target into which the current value of this real will be
091     *        induced
092     * @return the target
093     * @throws UnsupportedOperationException
094     *         this target primitive cannot be changed
095     * @throws IllegalStateException
096     *         this target primitive cannot be changed at this time
097     * @throws NullPointerException
098     *         a {@code null} value was provided when none was expected
099     * @throws NoSuchElementException
100     *         an expected parameter was not found in the parameter source
101     */
102    public <R extends Real<?>> R induceRealValue(
103        final R aTarget )
104        throws NullPointerException,
105            NoSuchElementException,
106            UnsupportedOperationException,
107            IllegalStateException;
108}