001/**
002 * SealedAlgebraicStructure.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;
020
021import java.util.Collection;
022
023import net.sf.jaccumulator.scalars.Scalar;
024import net.sf.jaccumulator.texts.MutableTextValue;
025import net.sf.jaccumulator.unlimiteds.UnlimitedIntegerPrimitive;
026
027/**
028 * A write-only algebraic {@link AlgebraicStructure structure}
029 *
030 * @param <STRUCTURE>
031 *        this structure type (facilitates chaining)
032 * @since JAccumulator 4.0
033 * @author Nicole Tedesco (<a
034 *         href="mailto:Nicole@NicoleTedesco.com">Nicole@NicoleTedesco.com</a>)
035 */
036public interface MutableAlgebraicStructure<STRUCTURE>
037    extends Mutable
038{
039    /**
040     * Attempt to convert the implementation {@link Domain domain} of this
041     * structure to the closest available match for the proposed domain. Note
042     * that the domain of this implementation may <i>not</i> change as a result
043     * of calling this function if an available internal conversion is not
044     * available.
045     *
046     * @param aDomain
047     *        the proposed domain
048     * @return {@code this} object (facilitates operation chaining)
049     * @see StructureProperties#isConfigurable()
050     */
051    public STRUCTURE assertDomain( final Domain aDomain );
052
053    /**
054     * Same as {@link Collection#clear()}. So as to maintain compatibility, this
055     * function will not return the customary reference back to this structure.
056     *
057     * @throws UnsupportedOperationException if the elements of this structure
058     *      cannot be cleared
059     *
060     * @see #clearContents()
061     * @see Collection#clear()
062     * @see MutableTextValue#clearText();
063     */
064    public void clear() throws UnsupportedOperationException;
065
066    /**
067     * Clear all elements of this structure and answer this object (facilitates
068     * chaining}.<br/>
069     * <br/>
070     * For text primitives all characters will be removed in an exact analog to
071     * {@link Collection#clear() clear()}. For bit tuples such as {@link Scalar
072     * scalar} primitives, this will reset all bits {@link #setZero() zero}
073     * since those elements cannot be removed. For
074     * {@link UnlimitedIntegerPrimitive unlimited} primitives all bytes in the
075     * representation will be removed, producing zero.<br/>
076     * <br/>
077     * Primarily, this function is provided as an alternative to
078     * {@link MutableTextValue#clear() clear()}, which does not return a value.
079     * This function, in answering this object, facilitates operation chaining.
080     *
081     * @return this object (facilitates operation chaining)
082     * @throws UnsupportedOperationException
083     *         if this object's value cannot be changed
084     * @see #clear()
085     * @see Collection#clear()
086     * @see MutableTextValue#clearText();
087     */
088    public STRUCTURE clearContents() throws UnsupportedOperationException;
089}