001/**
002 * SealedAccumulator.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;
020
021import java.util.NoSuchElementException;
022
023import net.sf.jaccumulator.primitives.Primitive;
024import net.sf.jaccumulator.primitives.SealedPrimitive;
025import net.sf.jupperware.association.AssociativeList;
026
027/**
028 * A read-only {@link Accumulator}
029 * 
030 * @param <ACCUMULATOR>
031 *        this {@link Accumulator} type
032 * @since JAccumulator 4.0
033 * @author Nicole Tedesco (<a
034 *         href="mailto:nicole@tedesco.name">nicole@tedesco.name</a>)
035 */
036public interface SealedAccumulator<ACCUMULATOR extends SealedAccumulator<ACCUMULATOR>>
037    extends
038        SealedPrimitive<ACCUMULATOR>,
039        AccumulatorReplicator<ACCUMULATOR>
040{
041    /**
042     * A convenience function to return the first, or zeroth, relationship in
043     * this Accumulator's {@link Accumulator #members() collection}
044     * 
045     * @return the first, or zeroth, relationship in this Accumulator's
046     *         {@link Accumulator #members() collection}
047     * @throws NoSuchElementException
048     *         this Accumulator's relationship collection was empty
049     */
050    public Accumulator<?> first() throws NoSuchElementException;
051
052    /**
053     * @return this Accumulator's target {@link Primitive}
054     */
055    public Primitive<?> getTarget();
056
057    /**
058     * Compare this Accumulator for equality against another. Two Accumulators
059     * are equal if the values of their {@link #getTarget() target} Primitives
060     * are equal, and the contents of their {@link SealedAccumulator#members()
061     * members} collections are equal.
062     * 
063     * @param anAccumulator
064     * @return {@code true} if the values of this Accumulator's
065     *         {@link #getTarget() target} Primitive if equal to the target
066     *         Primitive of the specified Accumulator, and if the content of the
067     *         {@link SealedAccumulator#members() members} collections are both
068     *         equal
069     */
070    public boolean isEqualToAccumulator(
071        final SealedAccumulator<?> anAccumulator );
072
073    /**
074     * @return {@code true} if the target {@link Primitive} can be replaced
075     */
076    public boolean isTargetReplaceable();
077
078    /**
079     * A convenience function to return the last, or highest order, relationship
080     * in this Accumulator's {@link Accumulator #members() collection}
081     * 
082     * @return the last, or highest order, relationship in this Accumulator's
083     *         {@link Accumulator #members() collection}
084     * @throws NoSuchElementException
085     *         this Accumulator's relationship collection was empty
086     */
087    public Accumulator<?> last() throws NoSuchElementException;
088
089    /**
090     * @return the relationship collection
091     */
092    public AssociativeList<Accumulator<?>,Accumulator<?>> members();
093
094    /**
095     * A convenience alias for {@link #last()}
096     * 
097     * @return the last, or highest order, relationship in this Accumulator's
098     *         {@link Accumulator #members() collection}
099     * @throws NoSuchElementException
100     *         this Accumulator's relationship collection was empty
101     */
102    public Accumulator<?> peek() throws NoSuchElementException;
103
104    /**
105     * Answer the name of the function associated with this Accumulator type
106     * 
107     * @return the name of the function associated with this Accumulator type
108     */
109    public String toFunctionName();
110}