001    /*
002     * Copyright (c) 2007-2015 Concurrent, Inc. All Rights Reserved.
003     *
004     * Project and contact information: http://www.cascading.org/
005     *
006     * This file is part of the Cascading project.
007     *
008     * Licensed under the Apache License, Version 2.0 (the "License");
009     * you may not use this file except in compliance with the License.
010     * You may obtain a copy of the License at
011     *
012     *     http://www.apache.org/licenses/LICENSE-2.0
013     *
014     * Unless required by applicable law or agreed to in writing, software
015     * distributed under the License is distributed on an "AS IS" BASIS,
016     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017     * See the License for the specific language governing permissions and
018     * limitations under the License.
019     */
020    
021    package cascading.property;
022    
023    import java.util.Map;
024    import java.util.Properties;
025    
026    /**
027     * Class Props is the base class for frameworks specific properties helper classes.
028     * <p/>
029     * Use the sub-classes to either create a {@link Properties} instance with custom or default values to be passed
030     * to any sub-system that requires a Map or Properties instance of properties and values.
031     * <p/>
032     * Note some Props sub-classes have static accessors. It is recommended the fluent instance methods be used instead
033     * of the static methods. All static accessors may be deprecated in future versions.
034     */
035    public abstract class Props
036      {
037      /**
038       * Method buildProperties returns a new {@link Properties} instance with all property values for this type.
039       * <p/>
040       * If no values have been set, all default properties and values will be returned.
041       *
042       * @return a new Properties instance
043       */
044      public Properties buildProperties()
045        {
046        return buildProperties( (Properties) null );
047        }
048    
049      /**
050       * Method buildProperties returns a new {@link Properties} instance with all property values for this type
051       * using the given Map of property values as defaults. The given Map will not be modified.
052       * <p/>
053       * If no values have been set, all default properties and values will be returned.
054       *
055       * @return a new Properties instance
056       */
057      public Properties buildProperties( Map<Object, Object> defaultProperties )
058        {
059        return buildProperties( PropertyUtil.createProperties( defaultProperties, null ) );
060        }
061    
062      /**
063       * Method buildProperties returns a new {@link Properties} instance with all property values for this type
064       * using the given Iterable<Map.Entry<String, String>> of property values as defaults. The given Iterable will not be modified.
065       * <p/>
066       * If no values have been set, all default properties and values will be returned.
067       *
068       * @return a new Properties instance
069       */
070      public Properties buildProperties( Iterable<Map.Entry<String, String>> defaultProperties )
071        {
072        return buildProperties( PropertyUtil.createProperties( defaultProperties ) );
073        }
074    
075      /**
076       * Method buildProperties returns a new {@link Properties} instance with all property values for this type
077       * using the given Properties instance of property values as defaults. The given Map will not be modified.
078       * <p/>
079       * If no values have been set, all default properties and values will be returned.
080       *
081       * @return a new Properties instance
082       */
083      public Properties buildProperties( Properties defaultProperties )
084        {
085        defaultProperties = defaultProperties != null ? new Properties( defaultProperties ) : new Properties();
086    
087        addPropertiesTo( defaultProperties );
088    
089        return defaultProperties;
090        }
091    
092      public ConfigDef setProperties( ConfigDef configDef )
093        {
094        return setProperties( configDef, ConfigDef.Mode.REPLACE );
095        }
096    
097      public ConfigDef setProperties( ConfigDef configDef, ConfigDef.Mode mode )
098        {
099        Properties properties = buildProperties();
100    
101        for( String name : properties.stringPropertyNames() )
102          configDef.setProperty( mode, name, properties.getProperty( name ) );
103    
104        return configDef;
105        }
106    
107      protected abstract void addPropertiesTo( Properties properties );
108      }