001/**
002 * SealedScalarDomain.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
023import net.sf.jaccumulator.AlgebraicStructure;
024
025/**
026 * A read-only contract for an {@link AlgebraicStructure algebraic} structure
027 * within which {@link Scalar Scalars} can be embedded
028 *
029 * @since JAccumulator 4.0
030 * @author Nicole Tedesco (<a href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
031 */
032public interface SealedScalarDomain extends SealedScalarBag
033{
034    /**
035     * @return the relative size of the implementation's {@code boolean}
036     *         bit tuple
037     */
038    public NumericPrecision getPrecision();
039
040    /**
041     * Induce the maximum domain value into the target
042     *
043     * @param <S>
044     *        the target type
045     * @param aTarget
046     *        a target into which this domain's maximum value will be induced
047     * @return the target
048     * @throws UnsupportedOperationException
049     *         this target primitive cannot be changed
050     * @throws IllegalStateException
051     *         this target primitive cannot be changed at this time
052     * @throws NullPointerException
053     *         a {@code null} value was provided when none was expected
054     * @throws NoSuchElementException
055     *         an expected parameter was not found in the parameter source
056     */
057    public <S extends Scalar<?>> S induceScalarMaximum(
058        final S aTarget )
059        throws NullPointerException,
060            NoSuchElementException,
061            UnsupportedOperationException,
062            IllegalStateException;
063
064    /**
065     * Induce the minimum domain value into the target
066     *
067     * @param <S>
068     *        the target type
069     * @param aTarget
070     *        a target into which this domain's minimum value will be induced
071     * @return the target
072     * @throws UnsupportedOperationException
073     *         this target primitive cannot be changed
074     * @throws IllegalStateException
075     *         this target primitive cannot be changed at this time
076     * @throws NullPointerException
077     *         a {@code null} value was provided when none was expected
078     * @throws NoSuchElementException
079     *         an expected parameter was not found in the parameter source
080     */
081    public <S extends Scalar<?>> S induceScalarMinimum(
082        final S aTarget )
083        throws NullPointerException,
084            NoSuchElementException,
085            UnsupportedOperationException,
086            IllegalStateException;
087}