001/**
002 * MutableUnlimitedDecimalValue.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.unlimiteds;
020
021import java.math.BigDecimal;
022
023/**
024 * A changeable unlimited {@link BigDecimal decimal} property value
025 *
026 * @param <VALUE>
027 *        this value 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 MutableUnlimitedDecimalValue<VALUE extends MutableUnlimitedDecimalValue<VALUE>>
033{
034    /**
035     * Set this property to the specified unlimited {@link BigDecimal decimal}
036     * value and answer this object (facilitates chaining)
037     *
038     * @param aValue
039     *        an unlimited {@link BigDecimal decimal} value
040     * @return this object (facilitates operation chaining)
041     * @throws UnsupportedOperationException
042     *         if this object's value cannot be changed
043     * @throws IllegalArgumentException
044     *         if the specified value was incommensurate with this object's
045     *         specification
046     * @throws ArithmeticException
047     *         the numeric value provided was incompatible with with algebraic
048     *         interpretation of this object
049     * @throws NullPointerException
050     *         a {@code null} value was provided though this object does not
051     *         accept {@code null} values
052     */
053    public VALUE setReal( final BigDecimal aValue )
054        throws UnsupportedOperationException,
055            IllegalArgumentException,
056            ArithmeticException,
057            NullPointerException;
058
059    /**
060     * Decrement the real value of this object then return the original value
061     * prior to decrementing
062     *
063     * @return the original value of this real
064     * @throws UnsupportedOperationException
065     *         if this object's value cannot be changed
066     * @throws IllegalArgumentException
067     *         if the new value was incommensurate with this object's
068     *         specification
069     * @throws ArithmeticException
070     *         the new numeric value was incompatible with with algebraic
071     *         interpretation of this object
072     */
073    public BigDecimal unlimitedDecimalPostDecrement()
074        throws UnsupportedOperationException,
075            ArithmeticException,
076            IllegalArgumentException;
077
078    /**
079     * Increment the real value of this object then return the original value
080     * prior to incrementing
081     *
082     * @return the original value of this real
083     * @throws UnsupportedOperationException
084     *         if this object's value cannot be changed
085     * @throws IllegalArgumentException
086     *         if the new value was incommensurate with this object's
087     *         specification
088     * @throws ArithmeticException
089     *         the new numeric value was incompatible with with algebraic
090     *         interpretation of this object
091     */
092    public BigDecimal unlimitedDecimalPostIncrement()
093        throws UnsupportedOperationException,
094            ArithmeticException,
095            IllegalArgumentException;
096
097}