001/**
002 * SealedScalarBag.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;
024import net.sf.jaccumulator.SealedAlgebraicStructure;
025
026
027/**
028 * A read-only {@link AlgebraicStructure algebraic} structure with a
029 * {@link Scalar scalar} ordinality (element count)
030 *
031 * @since JAccumulator 4.0
032 * @author Nicole Tedesco (<a
033 *         href="mailto:nicole@tedesco.name">nicole@tedesco.name</a>)
034 */
035public interface SealedScalarBag
036    extends
037        SealedAlgebraicStructure
038{
039    /**
040     * Update the target {@link Scalar scalar} with the element count in this
041     * structure
042     *
043     * @param <S>
044     *        the target type
045     * @param aTarget
046     *        the target to update
047     * @return the <i>target</i> scalar (facilitates operation chaining)
048     * @throws UnsupportedOperationException
049     *         this target cannot be changed
050     * @throws IllegalStateException
051     *         this target 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 induceScalarSize(
058        final S aTarget )
059        throws NullPointerException,
060            NoSuchElementException,
061            UnsupportedOperationException,
062            IllegalStateException;
063}