001    /*
002     * Jpkg - Java library and tools for operating system package creation.
003     *
004     * Copyright (c) 2007 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.property;
032    
033    import java.util.ArrayList;
034    import java.util.List;
035    
036    import com.threerings.antidote.RequiresValidation;
037    import com.threerings.antidote.Violation;
038    import com.threerings.antidote.field.Field;
039    
040    import static com.threerings.antidote.MutabilityHelper.objectIsNotSet;
041    import static com.threerings.antidote.MutabilityHelper.objectIsSet;
042    import static com.threerings.antidote.MutabilityHelper.requiresValidation;
043    
044    
045    /**
046     * A base implementation for {@link Property} objects to extend from. Generic type indicates the
047     * type of object being held by the property after validation.
048     */
049    public abstract class BaseProperty<T>
050        implements Property<T>, RequiresValidation
051    {
052        /**
053         * Construct a new BaseProperty.
054         * @param name The name of this property.
055         * @param field The {@link Field} holding this property.
056         */
057        public BaseProperty (String name, Field field)
058        {
059            this(name, field, null);
060        }
061    
062        /**
063         * Construct a new BaseProperty with a default value.
064         * @param name The name of this property.
065         * @param field The {@link Field} holding this property.
066         * @param defaultValue The default value for the field.
067         */
068        public BaseProperty (String name, Field field, T defaultValue)
069        {
070            _name = name;
071            _field = field;
072            _defaultValue = defaultValue;
073        }
074    
075        // from Property
076        public final String getPropertyName ()
077        {
078            return _name;
079        }
080    
081        // from Property
082        public final Field getField ()
083        {
084            return _field;
085        }
086    
087        // from Property
088        public final T getValue ()
089        {
090            requiresValidation(_validatedValue);
091            return _validatedValue;
092        }
093    
094        // from Mutable
095        public boolean isSet ()
096        {
097            return objectIsSet(_rawValue);
098        }
099    
100        // from Mutable
101        public boolean isNotSet ()
102        {
103            return objectIsNotSet(_rawValue);
104        }
105    
106        /**
107         * Implement validate() in the base abstract class ensuring correct behavior. Provide accessors
108         * to the list of violations in protected methods.
109         * @see #appendViolation(Violation)
110         */
111        // from RequiresValidation
112        public final List<Violation> validate ()
113        {
114            // if the raw value has not been set, use the default value if set. otherwise append a
115            // violation and stop processing, skipping property specific validation.
116            if (isNotSet()) {
117                if (objectIsSet(_defaultValue)) {
118                    _validatedValue = _defaultValue;
119    
120                } else {
121                    appendViolation(new UnsetPropertyViolation(this));
122                }
123    
124            } else {
125                _validatedValue = validateProperty();
126            }
127            return _violations;
128        }
129    
130        /**
131         * Sets the raw String value of the property. It is intended that this method would be called
132         * from an Ant setter method.
133         */
134        public final void setValue (String value)
135        {
136            _rawValue = value;
137        }
138    
139        /**
140         * Give each {@link Property} a chance to do property specific validation and return the
141         * validated value. If the raw value could not turned into a valid value, this will return null.
142         */
143        protected abstract T validateProperty ();
144    
145        /**
146         * Add a violation to the list of violations returned when this {@link Property} is validated.
147         */
148        protected void appendViolation (Violation violation)
149        {
150            _violations.add(violation);
151        }
152    
153        /**
154         * Provides concrete classes access to the raw user value.
155         */
156        protected final String getRawValue ()
157        {
158            return _rawValue;
159        }
160    
161        /** The name of this property. */
162        private final String _name;
163    
164        /** The {@link Field} holding this property. */
165        private final Field _field;
166    
167        /** The value assigned to this property in its original string form. Can be null. */
168        private String _rawValue;
169    
170        /** Holds the value after it has been validated from the raw value. */
171        private T _validatedValue;
172    
173        /** The optional default value for the property if the property is unset. */
174        private T _defaultValue;
175    
176        /** The list of any validation violations for this {@link Property}. */
177        private final List<Violation> _violations = new ArrayList<Violation>();
178    }