001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.hivemind.schema;
016    
017    import org.apache.hivemind.Location;
018    import org.apache.hivemind.internal.Module;
019    
020    /**
021     * Object which can translate a string into an object value.  This is used to
022     * translate attribute values (or element content) from strings into
023     * numbers, booleans or other constructs before assigning the final value
024     * to a propery.  Translation occurs after symbol substitution.
025     * 
026     * <p>
027     * Translator classes should have a public constructor that takes no
028     * arguments.  They may optionally have a second constructor
029     * that takes a single string as a parameter.  When the
030     * {@link org.apache.hivemind.parse.DescriptorParser} encounters
031     * a <code>translator</code> of the form 
032     * "<code><i>translator-id</i>,<i>initialization-string</i></code>"
033     * (example: "int,min=0") it will use the second constructor, passing
034     * the initialization string.
035     * 
036     * <p>
037     * Generally, initializion strings are of the form
038     * <code><i>key</i>=<i>value</i>[,<i>key</i>=<i>value</i>]*</code>.
039     * Each initializer has a set of keys it recognizes, other keys are simply
040     * ignored.
041     *
042     * @author Howard Lewis Ship
043     */
044    public interface Translator
045    {
046        /**
047         * Invoked by a {@link org.apache.hivemind.schema.Rule} 
048         * to translate an inputValue into an appropriate object.
049         * Substitution symbols will already have been expanded before this method is
050         * invoked.
051         * 
052         * @param contributingModule the module from which the input value originates
053         * @param propertyType the type of the property to be assigned by this translator; smart translators may
054         * be able to automatically convert from string to the correct type
055         * @param inputValue the value to be translated, either an attribute value or the content of the element
056         * @param location the location of the inputValue; used to set the location of created objects,
057         * or when reporting errors
058         */
059        public Object translate(
060            Module contributingModule,
061            Class propertyType,
062            String inputValue,
063            Location location);
064    }