001/**
002 * ScalarInductor.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.scalars;
020
021import java.util.NoSuchElementException;
022
023/**
024 * Imparts scalar values into other scalars
025 *
026 * @param <SCALAR>
027 *        this scalar type (used to facilitate operation chaining)
028 * @since JAccumulator 4.0
029 * @author Nicole Tedesco (<a
030 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
031 */
032public interface ScalarInductor<SCALAR extends ScalarInductor<SCALAR>>
033{
034    /**
035     * Decrement the value of this scalar then induce its original value into
036     * the specified target
037     *
038     * @param <S>
039     *        the target type
040     * @param aTarget
041     *        a target into which the current value of this scalar will be
042     *        induced, prior to decrementing
043     * @return the target
044     * @throws UnsupportedOperationException
045     *         this target primitive cannot be changed
046     * @throws IllegalStateException
047     *         this target primitive cannot be changed at this time
048     * @throws NullPointerException
049     *         a {@code null} value was provided when none was expected
050     * @throws NoSuchElementException
051     *         an expected parameter was not found in the parameter source
052     */
053    public <S extends Scalar<?>> S inducePostDecrement(
054        final S aTarget )
055        throws NullPointerException,
056            NoSuchElementException,
057            UnsupportedOperationException,
058            IllegalStateException;
059
060    /**
061     * Increment the value of this scalar then induce its original value into
062     * the specified target
063     *
064     * @param <S>
065     *        the target type
066     * @param aTarget
067     *        a target into which the current value of this scalar will be
068     *        induced, prior to incrementing
069     * @return the target
070     * @throws UnsupportedOperationException
071     *         this target primitive cannot be changed
072     * @throws IllegalStateException
073     *         this target primitive cannot be changed at this time
074     * @throws NullPointerException
075     *         a {@code null} value was provided when none was expected
076     * @throws NoSuchElementException
077     *         an expected parameter was not found in the parameter source
078     */
079    public <S extends Scalar<?>> S inducePostIncrement(
080        final S aTarget )
081        throws NullPointerException,
082            NoSuchElementException,
083            UnsupportedOperationException,
084            IllegalStateException;
085
086    /**
087     * Induce the current value of this scalar into the specified target
088     *
089     * @param <S>
090     *        the target type
091     * @param aTarget
092     *        a target into which the current value of this scalar will be
093     *        induced
094     * @return the target
095     * @throws UnsupportedOperationException
096     *         this target primitive cannot be changed
097     * @throws IllegalStateException
098     *         this target primitive cannot be changed at this time
099     * @throws NullPointerException
100     *         a {@code null} value was provided when none was expected
101     * @throws NoSuchElementException
102     *         an expected parameter was not found in the parameter source
103     */
104    public <S extends Scalar<?>> S induceScalarValue(
105        final S aTarget )
106        throws NullPointerException,
107            NoSuchElementException,
108            UnsupportedOperationException,
109            IllegalStateException;
110}