vladium/util/IProperties.java

/* Copyright (C) 2003 Vladimir Roubtsov. All rights reserved.
 *
 * This program and the accompanying materials are made available under
 * the terms of the Common Public License v1.0 which accompanies this distribution,
 * and is available at http://www.eclipse.org/legal/cpl-v10.html
 *
 * $Id: IProperties.java,v 1.1.1.1.2.1 2004/07/08 10:52:10 vlad_r Exp $
 */
package com.vladium.util;

import java.io.PrintStream;
import java.io.PrintWriter;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Properties;
import java.util.Set;
import java.util.TreeSet;

// ----------------------------------------------------------------------------
/**
 * @author Vlad Roubtsov, (C) 2003
 */
public
interface IProperties
{
    // public: ................................................................

    /**
     * An IMapper is a stateless hook for mapping a arbitrary property key
     * to another (useful, for example, for property aliasing and defaulting).
     * Each IMapper must be completely stateless and could be shared between
     * multiple IProperties instances (and invoked from multiple concurrent threads).
     */
    interface IMapper
    {
        String getMappedKey (final String key);

    } // end of nested interface


    String getProperty (String key);
    String getProperty (String key, String dflt);
    boolean isOverridden (String key);

    IProperties copy ();
    Iterator /* String */ properties ();
    Properties toProperties ();
    /**
     * @param prefix [may not be null]
     */
    String [] toAppArgsForm (final String prefix);
    boolean isEmpty ();
    void list (PrintStream out);
    void list (PrintWriter out);

    String setProperty (String key, String value);


    abstract class Factory
    {
        /**
         * Creates an empty IProperties set with an optional property mapper.
         *
         * @param mapper [may be null]
         * @return an empty property set [never null]
         */
        public static IProperties create (final IMapper mapper)
        {
            return new PropertiesImpl (null, mapper);
        }

        /**
         * Converts a java.util.Properties instance to an IProperties instance,
         * with an optional property mapper. Note that 'properties' content is
         * shallowly cloned, so the result can be mutated independently from
         * the input.
         *
         * @param properties [may not be null]
         * @param mapper [may be null]
         * @return a property set based on 'properties' [never null]
         */
        public static IProperties wrap (final Properties properties, final IMapper mapper)
        {
            final HashMap map = new HashMap ();

            // always use propertyNames() for traversing java.util.Properties:

            for (Enumeration names = properties.propertyNames (); names.hasMoreElements (); )
            {
                final String n = (String) names.nextElement ();
                final String v = properties.getProperty (n);

                map.put (n, v);
            }

            return new PropertiesImpl (map, mapper); // note: map is a defensive clone
        }

        /**
         * Combines two property sets by creating a property set that chains 'overrides'
         * to 'base' for property delegation. Note that 'overrides' are cloned
         * defensively and so the result can be mutated independently of both inputs.
         *
         * @param overrides [may be null]
         * @param base [may be null]
         * @return [never null; an empty property set with a null mapper is created
         * if both inputs are null]
         */
        public static IProperties combine (final IProperties overrides, final IProperties base)
        {
            final IProperties result = overrides != null
                ? overrides.copy ()
                : create (null);

            // [assertion: result != null]

            ((PropertiesImpl) result).getLastProperties ().setDelegate ((PropertiesImpl) base);

            return result;
        }

        /*
         * Not MT-safe
         */
        private static final class PropertiesImpl implements IProperties, Cloneable
        {
            // ACCESSORS (IProperties):

            public String getProperty (final String key)
            {
                return getProperty (key, null);
            }

            public String getProperty (final String key, final String dflt)
            {
                String value = (String) m_valueMap.get (key);

                // first, try to delegate horizontally:
                if ((value == null) && (m_mapper != null))
                {
                    final String mappedKey = m_mapper.getMappedKey (key);

                    if (mappedKey != null)
                        value = (String) m_valueMap.get (mappedKey);
                }

                // next, try to delegate vertically:
                if ((value == null) && (m_delegate != null))
                {
                    value = m_delegate.getProperty (key, null);
                }

                return value != null ? value : dflt;
            }

            public boolean isOverridden (final String key)
            {
                return m_valueMap.containsKey (key);
            }

            public IProperties copy ()
            {
                final PropertiesImpl _clone;
                try
                {
                    _clone = (PropertiesImpl) super.clone ();
                }
                catch (CloneNotSupportedException cnse)
                {
                    throw new Error (cnse.toString ()); // never happens
                }

                _clone.m_valueMap = (HashMap) m_valueMap.clone ();
                _clone.m_unmappedKeySet = null;

                // note: m_mapper field is not cloned by design (mappers are stateless/shareable)

                PropertiesImpl scan = _clone;
                for (PropertiesImpl delegate = m_delegate; delegate != null; delegate = delegate.m_delegate)
                {
                    final PropertiesImpl _delegateClone;
                    try
                    {
                        _delegateClone = (PropertiesImpl) delegate.clone ();
                    }
                    catch (CloneNotSupportedException cnse)
                    {
                        throw new Error (cnse.toString ()); // never happens
                    }

                    // note that the value map needs to be cloned not only for the
                    // outermost IProperties set but for the inner ones as well
                    // (to prevent independent mutation in them from showing through)

                    _delegateClone.m_valueMap = (HashMap) delegate.m_valueMap.clone ();
                    _delegateClone.m_unmappedKeySet = null; // ensure that the last delegate will have this field reset

                    scan.setDelegate (_delegateClone);
                    scan = _delegateClone;
                }

                return _clone;
            }

            public Iterator /* String */ properties ()
            {
                return unmappedKeySet ().iterator ();
            }

            public Properties toProperties ()
            {
                final Properties result = new Properties ();

                for (Iterator i = properties (); i.hasNext (); )
                {
                    final String n = (String) i.next ();
                    final String v = getProperty (n);

                    result.setProperty (n, v);
                }

                return result;
            }

            public boolean isEmpty ()
            {
                return m_valueMap.isEmpty () && ((m_delegate == null) || ((m_delegate != null) && m_delegate.isEmpty ()));
            }

            public String [] toAppArgsForm (final String prefix)
            {
                if (isEmpty ())
                    return IConstants.EMPTY_STRING_ARRAY;
                else
                {
                    if (prefix == null)
                        throw new IllegalArgumentException ("null input: prefix");

                    final List _result = new ArrayList ();
                    for (Iterator names = properties (); names.hasNext (); )
                    {
                        final String name = (String) names.next ();
                        final String value = getProperty (name, "");

                        _result.add (prefix.concat (name).concat ("=").concat (value));
                    }

                    final String [] result = new String [_result.size ()];
                    _result.toArray (result);

                    return result;
                }
            }

            public void list (final PrintStream out)
            {
                if (out != null)
                {
                    for (Iterator i = properties (); i.hasNext (); )
                    {
                        final String n = (String) i.next ();
                        final String v = getProperty (n);

                        out.println (n + ":\t[" + v + "]");
                    }
                }
            }

            public void list (final PrintWriter out)
            {
                if (out != null)
                {
                    for (Iterator i = properties (); i.hasNext (); )
                    {
                        final String n = (String) i.next ();
                        final String v = getProperty (n);

                        out.println (n + ":\t[" + v + "]");
                    }
                }
            }

            // MUTATORS:

            public String setProperty (final String key, final String value)
            {
                if (value == null)
                    throw new IllegalArgumentException ("null input: value");

                m_unmappedKeySet = null;

                return (String) m_valueMap.put (key, value);
            }


            PropertiesImpl (final HashMap values, final IMapper mapper)
            {
                m_mapper = mapper;
                m_valueMap = values != null ? values : new HashMap ();

                m_delegate = null;
            }


            Set unmappedKeySet ()
            {
                Set result = m_unmappedKeySet;
                if (result == null)
                {
                    result = new TreeSet ();
                    result.addAll (m_valueMap.keySet ());
                    if (m_delegate != null)
                        result.addAll (m_delegate.unmappedKeySet ());

                    m_unmappedKeySet = result;
                    return result;
                }

                return result;
            }

            // ACCESSORS:

            PropertiesImpl getLastProperties ()
            {
                PropertiesImpl result = this;

                for (PropertiesImpl delegate = m_delegate; delegate != null; delegate = delegate.m_delegate)
                {
                    // this does not detect all possible cycles:
                    if (delegate == this)
                        throw new IllegalStateException ("cyclic delegation detected");

                    result = delegate;
                }

                return result;
            }

            // MUTATORS:

            void setDelegate (final PropertiesImpl delegate)
            {
                m_delegate = delegate;

                m_unmappedKeySet = null;
            }


            private final IMapper m_mapper;
            private /*final*/ HashMap m_valueMap; // never null

            private PropertiesImpl m_delegate;
            private transient Set m_unmappedKeySet;

        } // end of nested class

    } // end of nested class

    // protected: .............................................................

    // package: ...............................................................

    // private: ...............................................................

} // end of class
// ----------------------------------------------------------------------------