001/**
002 * PrimitiveInductor.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"); you may not
007 * use this file except in compliance with the License. You may obtain a copy of
008 * 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, WITHOUT
014 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015 * License for the specific language governing permissions and limitations under
016 * the License.
017 */
018
019package net.sf.jaccumulator.primitives;
020
021import java.util.NoSuchElementException;
022
023/**
024 * Imparts {@link Primitive} values into other Primitives
025 * 
026 * @param <PRIMITIVE>
027 *        this 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 PrimitiveInductor<PRIMITIVE extends PrimitiveInductor<PRIMITIVE>>
033{
034    /**
035     * Decrement the value of this Primitive then induce its original value into
036     * the specified target
037     * 
038     * @param <P>
039     *        the target type
040     * @param aTarget
041     *        a target into which the current value of this Primitive 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 <P extends Primitive<?>> P inducePostDecrement( final P aTarget )
054        throws NullPointerException,
055            NoSuchElementException,
056            UnsupportedOperationException,
057            IllegalStateException;
058
059    /**
060     * Increment the value of this Primitive then induce its original value into
061     * the specified target
062     * 
063     * @param <P>
064     *        the target type
065     * @param aTarget
066     *        a target into which the current value of this Primitive will be
067     *        induced, prior to incrementing
068     * @return the target
069     * @throws UnsupportedOperationException
070     *         this target Primitive cannot be changed
071     * @throws IllegalStateException
072     *         this target Primitive cannot be changed at this time
073     * @throws NullPointerException
074     *         a {@code null} value was provided when none was expected
075     * @throws NoSuchElementException
076     *         an expected parameter was not found in the parameter source
077     */
078    public <P extends Primitive<?>> P inducePostIncrement( final P aTarget )
079        throws NullPointerException,
080            NoSuchElementException,
081            UnsupportedOperationException,
082            IllegalStateException;
083
084    /**
085     * Induce the maximum numeric value of the Primitive into the specified
086     * target
087     * 
088     * @param <P>
089     *        the target type
090     * @param aTarget
091     *        a target into which the maximum numeric value of the Primitive
092     *        will be induced
093     * @return the target
094     */
095    public <P extends Primitive<?>> P inducePrimitiveMaximum( final P aTarget )
096        throws NullPointerException,
097            NoSuchElementException,
098            UnsupportedOperationException,
099            IllegalStateException;
100
101    /**
102     * Induce the minimum numeric value of the Primitive into the specified
103     * target
104     * 
105     * @param <P>
106     *        the target type
107     * @param aTarget
108     *        a target into which the minimum numeric value of the Primitive
109     *        will be induced
110     * @return the target
111     * @throws UnsupportedOperationException
112     *         this target Primitive cannot be changed
113     * @throws IllegalStateException
114     *         this target Primitive cannot be changed at this time
115     * @throws NullPointerException
116     *         a {@code null} value was provided when none was expected
117     * @throws NoSuchElementException
118     *         an expected parameter was not found in the parameter source
119     */
120    public <P extends Primitive<?>> P inducePrimitiveMinimum( final P aTarget )
121        throws NullPointerException,
122            NoSuchElementException,
123            UnsupportedOperationException,
124            IllegalStateException;
125
126    /**
127     * Induce the current value of this Primitive into the specified target
128     * 
129     * @param <P>
130     *        the target type
131     * @param aTarget
132     *        a target into which the current value of this Primitive will be
133     *        induced
134     * @return the target
135     * @throws UnsupportedOperationException
136     *         this target Primitive cannot be changed
137     * @throws IllegalStateException
138     *         this target Primitive cannot be changed at this time
139     * @throws NullPointerException
140     *         a {@code null} value was provided when none was expected
141     * @throws NoSuchElementException
142     *         an expected parameter was not found in the parameter source
143     */
144    public <P extends Primitive<?>> P inducePrimitiveValue( final P aTarget )
145        throws NullPointerException,
146            NoSuchElementException,
147            UnsupportedOperationException,
148            IllegalStateException;
149}