001    /*
002     * Jpkg - Java library and tools for operating system package creation.
003     *
004     * Copyright (c) 2007-2008 Three Rings Design, Inc.
005     * All rights reserved.
006     *
007     * Redistribution and use in source and binary forms, with or without
008     * modification, are permitted provided that the following conditions
009     * are met:
010     * 1. Redistributions of source code must retain the above copyright
011     *    notice, this list of conditions and the following disclaimer.
012     * 2. Redistributions in binary form must reproduce the above copyright
013     *    notice, this list of conditions and the following disclaimer in the
014     *    documentation and/or other materials provided with the distribution.
015     * 3. Neither the name of the copyright owner nor the names of contributors
016     *    may be used to endorse or promote products derived from this software
017     *    without specific prior written permission.
018     *
019     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
020     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
021     * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
022     * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
023     * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
024     * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
025     * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
026     * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
027     * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
028     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
029     * POSSIBILITY OF SUCH DAMAGE.
030     */
031    package com.threerings.antidote.field;
032    
033    import org.apache.tools.ant.types.Reference;
034    
035    import com.threerings.antidote.Mutable;
036    import com.threerings.antidote.RequiresValidation;
037    import com.threerings.antidote.RequiresValidationException;
038    
039    /**
040     * Wraps a {@link Field} object and provides methods to handle the mutability of that object and any
041     * {@link ReferenceField} aspects of that {@link Field}.
042     */
043    public interface FieldWrapper<F extends ReferenceField>
044        extends Mutable, Field
045    {
046        /**
047         * Set the wrapped {@link Field}. Provided so that the wrapped {@link Field} may be set
048         * whenever an Ant setter method is called, which may be after this {@link FieldWrapper} was
049         * constructed. It is a violation to set the wrapped {@link Field} more than once and the
050         * {@link FieldWrapper} will fail in {@link RequiresValidation#validate()}.
051         */
052        public void setField (F wrapped);
053    
054        /**
055         * Returns the {@link Field} held by this {@link FieldWrapper}. If the held {@link Field} is set
056         * that object will be returned. If the {@link Field} is set and is a {@link Reference} to
057         * another {@link Field}, the referenced {@link Field} will be returned. Finally, if the {@link Field}
058         * is not set, {@link RequiresValidationException} will be thrown. Use {@link Mutable#isSet()} or
059         * {@link Mutable#isNotSet()} to determine the status of the held {@link Field} before calling
060         * this method.
061         * @throws RequiresValidationException if the held {@link Field} is not set.
062         */
063        public F getField ();
064    
065        /**
066         * Return the parent {@link Field} of the wrapped {@link Field}.
067         */
068        public Field getParent ();
069    }