Return-Path: X-Original-To: apmail-commons-dev-archive@www.apache.org Delivered-To: apmail-commons-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id AE7A0D08E for ; Tue, 6 Nov 2012 08:58:09 +0000 (UTC) Received: (qmail 72949 invoked by uid 500); 6 Nov 2012 08:58:09 -0000 Delivered-To: apmail-commons-dev-archive@commons.apache.org Received: (qmail 72766 invoked by uid 500); 6 Nov 2012 08:58:08 -0000 Mailing-List: contact dev-help@commons.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Commons Developers List" Delivered-To: mailing list dev@commons.apache.org Received: (qmail 72738 invoked by uid 99); 6 Nov 2012 08:58:07 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 06 Nov 2012 08:58:07 +0000 X-ASF-Spam-Status: No, hits=1.5 required=5.0 tests=HTML_MESSAGE,RCVD_IN_DNSWL_LOW,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: domain of beneritter@gmail.com designates 209.85.216.43 as permitted sender) Received: from [209.85.216.43] (HELO mail-qa0-f43.google.com) (209.85.216.43) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 06 Nov 2012 08:58:02 +0000 Received: by mail-qa0-f43.google.com with SMTP id b19so1521121qae.9 for ; Tue, 06 Nov 2012 00:57:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; bh=5lfTJPsvuW6c9E1SwrO34P4FHzsBvxC+iWYgaE6pyps=; b=sjQE1bA7DBqsJXql08UnGc7/iih+roo1li+GUJ4CPooOzsSaOI+xMEM2G9+ujAQ2+q t4NDi8QTsNohoLdkIcDpegkazbiPvsILW0gPypyGiOEPUofUyolI3OfT4xk4MCrKpc7A IAFJiWKjs+i/KV4fXtqR9h4rPJJ97x7S7NP8xh7oXveRMwQgwVN/UEBqj2zHT56vs27q xHOLHfy6y2L/xcZ6ZPSbGBcvWdxKxz7ihqmqJm7hqj8innn37G+kt5tiVW/85kRq0DzX amxl3AKXOPlOWisPnq9OYC2fscyc/B2p1Yv4AP13veNT1dXamC8MkY/nW3KoTY+ND9WQ KwKA== MIME-Version: 1.0 Received: by 10.224.111.78 with SMTP id r14mr590110qap.31.1352192261053; Tue, 06 Nov 2012 00:57:41 -0800 (PST) Received: by 10.49.76.68 with HTTP; Tue, 6 Nov 2012 00:57:40 -0800 (PST) In-Reply-To: <5098C7DC.3020402@oliver-heger.de> References: <20121105172902.4438223888E7@eris.apache.org> <5098C7DC.3020402@oliver-heger.de> Date: Tue, 6 Nov 2012 09:57:40 +0100 Message-ID: Subject: Re: svn commit: r1405889 - in /commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration: Configuration.java ImmutableConfiguration.java From: Benedikt Ritter To: Commons Developers List Content-Type: multipart/alternative; boundary=20cf3074d220635d2604cdcfcbcb X-Virus-Checked: Checked by ClamAV on apache.org --20cf3074d220635d2604cdcfcbcb Content-Type: text/plain; charset=ISO-8859-1 Hi Oliver, thanks for the clarification. I see where you are going with the design. What do you think of my proposal to implement the configuration interfaces like the java collections framework? I can think of Configurations.unmodifiableConfiguration(Configuration config). Benedikt 2012/11/6 Oliver Heger > Hi Benedikt, > > Am 05.11.2012 21:04, schrieb Benedikt Ritter: > > 2012/11/5 Benedikt Ritter >> >> Hi Oliver, >>> >>> >>> 2012/11/5 >>> >>> Author: oheger >>> >>>> Date: Mon Nov 5 17:29:01 2012 >>>> New Revision: 1405889 >>>> >>>> URL: http://svn.apache.org/viewvc?**rev=1405889&view=rev >>>> Log: >>>> Initial version of an immutable configuration interface. >>>> >>>> Added: >>>> >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**ImmutableConfiguration.java >>>> (with props) >>>> Modified: >>>> >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**Configuration.java >>>> >>>> Modified: >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**Configuration.java >>>> URL: >>>> http://svn.apache.org/viewvc/**commons/proper/configuration/** >>>> trunk/src/main/java/org/**apache/commons/configuration/** >>>> Configuration.java?rev=**1405889&r1=1405888&r2=1405889&**view=diff >>>> >>>> ==============================**==============================** >>>> ================== >>>> --- >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**Configuration.java >>>> (original) >>>> +++ >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**Configuration.java >>>> Mon Nov 5 17:29:01 2012 >>>> @@ -17,11 +17,6 @@ >>>> >>>> package org.apache.commons.**configuration; >>>> >>>> -import java.math.BigDecimal; >>>> -import java.math.BigInteger; >>>> -import java.util.Iterator; >>>> -import java.util.List; >>>> -import java.util.Properties; >>>> >>>> /** >>>> *

The main Configuration interface.

>>>> @@ -54,7 +49,7 @@ import java.util.Properties; >>>> * @author Commons Configuration team >>>> * @version $Id$ >>>> */ >>>> -public interface Configuration >>>> +public interface Configuration extends ImmutableConfiguration >>>> >>>> >>> A Configuration IS_A ImmutableConfiguration sounds rather akward. The >>> JavaDoc of ImmutableConfiguration says "The main interface for accessing >>> configuration data in a read-only fashion." Maybe ImmutableConfiguration >>> should be renamed to ReadOnlyConfiguration? >>> >>> Regards, >>> Benedikt >>> >>> >> Looking at the code base, there is no class that implements >> ImmutableConfiguration directly and Configuration is the only interface >> that extends ImmutableConfiguration. So maybe the two can be merged >> together? >> > > The ImmutableConfiguration interface has just been extracted from > Configuration in order to implement the feature of immutable > configurations. It contains all methods that do not manipulate the > configuration. A full-blown configuration extends this functionality by > additional update operations. > > It is true that currently all concrete Configuration implementations > support the extended interface with update operations. However, > ImmutableConfiguration is implemented by dynamic proxies which provide an > immutable view on an arbitrary Configuration object. > > Regarding the name: I am open for suggestions. ReadOnlyConfiguration, > ImmutableConfiguration, UnmodifiableConfiguration,... Maybe a native > speaker can comment? > > Oliver > > > >> Benedikt >> >> >> >>> >>> { >>>> /** >>>> * Return a decorator Configuration containing every key from the >>>> current >>>> @@ -90,24 +85,6 @@ public interface Configuration >>>> Configuration subset(String prefix); >>>> >>>> /** >>>> - * Check if the configuration is empty. >>>> - * >>>> - * @return {@code true} if the configuration contains no property, >>>> - * {@code false} otherwise. >>>> - */ >>>> - boolean isEmpty(); >>>> - >>>> - /** >>>> - * Check if the configuration contains the specified key. >>>> - * >>>> - * @param key the key whose presence in this configuration is to be >>>> tested >>>> - * >>>> - * @return {@code true} if the configuration contains a value for >>>> this >>>> - * key, {@code false} otherwise >>>> - */ >>>> - boolean containsKey(String key); >>>> - >>>> - /** >>>> * Add a property to the configuration. If it already exists then >>>> the value >>>> * stated here will be added to the configuration entry. For >>>> example, if >>>> * the property: >>>> @@ -147,452 +124,4 @@ public interface Configuration >>>> * Remove all properties from the configuration. >>>> */ >>>> void clear(); >>>> - >>>> - /** >>>> - * Gets a property from the configuration. This is the most basic >>>> get >>>> - * method for retrieving values of properties. In a typical >>>> implementation >>>> - * of the {@code Configuration} interface the other get methods >>>> (that >>>> - * return specific data types) will internally make use of this >>>> method. On >>>> - * this level variable substitution is not yet performed. The >>>> returned >>>> - * object is an internal representation of the property value for >>>> the passed >>>> - * in key. It is owned by the {@code Configuration} object. So a >>>> caller >>>> - * should not modify this object. It cannot be guaranteed that this >>>> object >>>> - * will stay constant over time (i.e. further update operations on >>>> the >>>> - * configuration may change its internal state). >>>> - * >>>> - * @param key property to retrieve >>>> - * @return the value to which this configuration maps the specified >>>> key, or >>>> - * null if the configuration contains no mapping for this >>>> key. >>>> - */ >>>> - Object getProperty(String key); >>>> - >>>> - /** >>>> - * Get the list of the keys contained in the configuration that >>>> match the >>>> - * specified prefix. For instance, if the configuration contains >>>> the >>>> - * following keys:
>>>> - * {@code db.user, db.pwd, db.url, window.xpos, window.ypos},
>>>> - * an invocation of {@code getKeys("db");}
>>>> - * will return the keys below:
>>>> - * {@code db.user, db.pwd, db.url}.
>>>> - * Note that the prefix itself is included in the result set if >>>> there is a >>>> - * matching key. The exact behavior - how the prefix is actually >>>> - * interpreted - depends on a concrete implementation. >>>> - * >>>> - * @param prefix The prefix to test against. >>>> - * @return An Iterator of keys that match the prefix. >>>> - * @see #getKeys() >>>> - */ >>>> - Iterator getKeys(String prefix); >>>> - >>>> - /** >>>> - * Get the list of the keys contained in the configuration. The >>>> returned >>>> - * iterator can be used to obtain all defined keys. Note that the >>>> exact >>>> - * behavior of the iterator's {@code remove()} method is specific >>>> to >>>> - * a concrete implementation. It may remove the >>>> corresponding >>>> - * property from the configuration, but this is not guaranteed. In >>>> any case >>>> - * it is no replacement for calling >>>> - * {@link #clearProperty(String)} for this property. So it is >>>> - * highly recommended to avoid using the iterator's {@code >>>> remove()} >>>> - * method. >>>> - * >>>> - * @return An Iterator. >>>> - */ >>>> - Iterator getKeys(); >>>> - >>>> - /** >>>> - * Get a list of properties associated with the given configuration >>>> key. >>>> - * This method expects the given key to have an arbitrary number of >>>> String >>>> - * values, each of which is of the form {code key=value}. These >>>> - * strings are split at the equals sign, and the key parts will >>>> become >>>> - * keys of the returned {@code Properties} object, the value parts >>>> - * become values. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated properties if key is found. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a String/List. >>>> - * >>>> - * @throws IllegalArgumentException if one of the tokens is >>>> - * malformed (does not contain an equals sign). >>>> - */ >>>> - Properties getProperties(String key); >>>> - >>>> - /** >>>> - * Get a boolean associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated boolean. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Boolean. >>>> - */ >>>> - boolean getBoolean(String key); >>>> - >>>> - /** >>>> - * Get a boolean associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated boolean. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Boolean. >>>> - */ >>>> - boolean getBoolean(String key, boolean defaultValue); >>>> - >>>> - /** >>>> - * Get a {@link Boolean} associated with the given configuration >>>> key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated boolean if key is found and has valid >>>> - * format, default value otherwise. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Boolean. >>>> - */ >>>> - Boolean getBoolean(String key, Boolean defaultValue); >>>> - >>>> - /** >>>> - * Get a byte associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated byte. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Byte. >>>> - */ >>>> - byte getByte(String key); >>>> - >>>> - /** >>>> - * Get a byte associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated byte. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Byte. >>>> - */ >>>> - byte getByte(String key, byte defaultValue); >>>> - >>>> - /** >>>> - * Get a {@link Byte} associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated byte if key is found and has valid >>>> format, >>>> default >>>> - * value otherwise. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> object that >>>> - * is not a Byte. >>>> - */ >>>> - Byte getByte(String key, Byte defaultValue); >>>> - >>>> - /** >>>> - * Get a double associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated double. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Double. >>>> - */ >>>> - double getDouble(String key); >>>> - >>>> - /** >>>> - * Get a double associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated double. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Double. >>>> - */ >>>> - double getDouble(String key, double defaultValue); >>>> - >>>> - /** >>>> - * Get a {@link Double} associated with the given configuration >>>> key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated double if key is found and has valid >>>> - * format, default value otherwise. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Double. >>>> - */ >>>> - Double getDouble(String key, Double defaultValue); >>>> - >>>> - /** >>>> - * Get a float associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated float. >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Float. >>>> - */ >>>> - float getFloat(String key); >>>> - >>>> - /** >>>> - * Get a float associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated float. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Float. >>>> - */ >>>> - float getFloat(String key, float defaultValue); >>>> - >>>> - /** >>>> - * Get a {@link Float} associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated float if key is found and has valid >>>> - * format, default value otherwise. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Float. >>>> - */ >>>> - Float getFloat(String key, Float defaultValue); >>>> - >>>> - /** >>>> - * Get a int associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated int. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Integer. >>>> - */ >>>> - int getInt(String key); >>>> - >>>> - /** >>>> - * Get a int associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated int. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Integer. >>>> - */ >>>> - int getInt(String key, int defaultValue); >>>> - >>>> - /** >>>> - * Get an {@link Integer} associated with the given configuration >>>> key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated int if key is found and has valid format, >>>> default >>>> - * value otherwise. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> object that >>>> - * is not a Integer. >>>> - */ >>>> - Integer getInteger(String key, Integer defaultValue); >>>> - >>>> - /** >>>> - * Get a long associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated long. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Long. >>>> - */ >>>> - long getLong(String key); >>>> - >>>> - /** >>>> - * Get a long associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated long. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Long. >>>> - */ >>>> - long getLong(String key, long defaultValue); >>>> - >>>> - /** >>>> - * Get a {@link Long} associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated long if key is found and has valid >>>> - * format, default value otherwise. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Long. >>>> - */ >>>> - Long getLong(String key, Long defaultValue); >>>> - >>>> - /** >>>> - * Get a short associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated short. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Short. >>>> - */ >>>> - short getShort(String key); >>>> - >>>> - /** >>>> - * Get a short associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated short. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Short. >>>> - */ >>>> - short getShort(String key, short defaultValue); >>>> - >>>> - /** >>>> - * Get a {@link Short} associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated short if key is found and has valid >>>> - * format, default value otherwise. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a Short. >>>> - */ >>>> - Short getShort(String key, Short defaultValue); >>>> - >>>> - /** >>>> - * Get a {@link BigDecimal} associated with the given configuration >>>> key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated BigDecimal if key is found and has valid >>>> format >>>> - */ >>>> - BigDecimal getBigDecimal(String key); >>>> - >>>> - /** >>>> - * Get a {@link BigDecimal} associated with the given configuration >>>> key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * >>>> - * @return The associated BigDecimal if key is found and has valid >>>> - * format, default value otherwise. >>>> - */ >>>> - BigDecimal getBigDecimal(String key, BigDecimal defaultValue); >>>> - >>>> - /** >>>> - * Get a {@link BigInteger} associated with the given configuration >>>> key. >>>> - * >>>> - * @param key The configuration key. >>>> - * >>>> - * @return The associated BigInteger if key is found and has valid >>>> format >>>> - */ >>>> - BigInteger getBigInteger(String key); >>>> - >>>> - /** >>>> - * Get a {@link BigInteger} associated with the given configuration >>>> key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * >>>> - * @return The associated BigInteger if key is found and has valid >>>> - * format, default value otherwise. >>>> - */ >>>> - BigInteger getBigInteger(String key, BigInteger defaultValue); >>>> - >>>> - /** >>>> - * Get a string associated with the given configuration key. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated string. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> object that >>>> - * is not a String. >>>> - */ >>>> - String getString(String key); >>>> - >>>> - /** >>>> - * Get a string associated with the given configuration key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated string if key is found and has valid >>>> - * format, default value otherwise. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> object that >>>> - * is not a String. >>>> - */ >>>> - String getString(String key, String defaultValue); >>>> - >>>> - /** >>>> - * Get an array of strings associated with the given configuration >>>> key. >>>> - * If the key doesn't map to an existing object an empty array is >>>> returned >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated string array if key is found. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a String/List of Strings. >>>> - */ >>>> - String[] getStringArray(String key); >>>> - >>>> - /** >>>> - * Get a List of strings associated with the given configuration >>>> key. >>>> - * If the key doesn't map to an existing object an empty List is >>>> returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @return The associated List. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a List. >>>> - */ >>>> - List getList(String key); >>>> - >>>> - /** >>>> - * Get a List of strings associated with the given configuration >>>> key. >>>> - * If the key doesn't map to an existing object, the default value >>>> - * is returned. >>>> - * >>>> - * @param key The configuration key. >>>> - * @param defaultValue The default value. >>>> - * @return The associated List of strings. >>>> - * >>>> - * @throws ConversionException is thrown if the key maps to an >>>> - * object that is not a List. >>>> - */ >>>> - List getList(String key, List defaultValue); >>>> } >>>> >>>> Added: >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**ImmutableConfiguration.java >>>> URL: >>>> http://svn.apache.org/viewvc/**commons/proper/configuration/** >>>> trunk/src/main/java/org/**apache/commons/configuration/** >>>> ImmutableConfiguration.java?**rev=1405889&view=auto >>>> >>>> ==============================**==============================** >>>> ================== >>>> --- >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**ImmutableConfiguration.java >>>> (added) >>>> +++ >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**ImmutableConfiguration.java >>>> Mon Nov 5 17:29:01 2012 >>>> @@ -0,0 +1,518 @@ >>>> +/* >>>> + * Licensed to the Apache Software Foundation (ASF) under one or more >>>> + * contributor license agreements. See the NOTICE file distributed >>>> with >>>> + * this work for additional information regarding copyright ownership. >>>> + * The ASF licenses this file to You under the Apache License, Version >>>> 2.0 >>>> + * (the "License"); you may not use this file except in compliance with >>>> + * the License. You may obtain a copy of the License at >>>> + * >>>> + * http://www.apache.org/**licenses/LICENSE-2.0 >>>> + * >>>> + * Unless required by applicable law or agreed to in writing, software >>>> + * distributed under the License is distributed on an "AS IS" BASIS, >>>> + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or >>>> implied. >>>> + * See the License for the specific language governing permissions and >>>> + * limitations under the License. >>>> + */ >>>> +package org.apache.commons.**configuration; >>>> + >>>> +import java.math.BigDecimal; >>>> +import java.math.BigInteger; >>>> +import java.util.Iterator; >>>> +import java.util.List; >>>> +import java.util.Properties; >>>> + >>>> +/** >>>> + *

The main interface for accessing configuration data in a >>>> read-only >>>> fashion.

>>>> + *

>>>> + * The major part of the methods defined in this interface deals with >>>> accessing >>>> + * properties of various data types. There is a generic {@code >>>> getProperty()} >>>> + * method, which returns the value of the queried property in its raw >>>> data >>>> + * type. Other getter methods try to convert this raw data type into a >>>> specific >>>> + * data type. If this fails, a {@code ConversionException} will be >>>> thrown.

>>>> + *

For most of the property getter methods an overloaded version >>>> exists that >>>> + * allows to specify a default value, which will be returned if the >>>> queried >>>> + * property cannot be found in the configuration. The behavior of the >>>> methods >>>> + * that do not take a default value in case of a missing property is >>>> not >>>> defined >>>> + * by this interface and depends on a concrete implementation. E.g. the >>>> + * {@link AbstractConfiguration} class, which is the base class >>>> + * of most configuration implementations provided by this package, per >>>> default >>>> + * returns null if a property is not found, but provides the >>>> + * {@link AbstractConfiguration#**setThrowExceptionOnMissing(** >>>> boolean) >>>> + * setThrowExceptionOnMissing()} >>>> + * method, with which it can be configured to throw a {@code >>>> NoSuchElementException} >>>> + * exception in that case. (Note that getter methods for primitive >>>> types >>>> in >>>> + * {@code AbstractConfiguration} always throw an exception for missing >>>> + * properties because there is no way of overloading the return >>>> value.)

>>>> + * >>>> + * @version $Id$ >>>> + * @since 2.0 >>>> + */ >>>> +public interface ImmutableConfiguration >>>> +{ >>>> + /** >>>> + * Check if the configuration is empty. >>>> + * >>>> + * @return {@code true} if the configuration contains no property, >>>> + * {@code false} otherwise. >>>> + */ >>>> + boolean isEmpty(); >>>> + >>>> + /** >>>> + * Check if the configuration contains the specified key. >>>> + * >>>> + * @param key the key whose presence in this configuration is to be >>>> tested >>>> + * >>>> + * @return {@code true} if the configuration contains a value for >>>> this >>>> + * key, {@code false} otherwise >>>> + */ >>>> + boolean containsKey(String key); >>>> + >>>> + /** >>>> + * Gets a property from the configuration. This is the most basic >>>> get >>>> + * method for retrieving values of properties. In a typical >>>> implementation >>>> + * of the {@code Configuration} interface the other get methods >>>> (that >>>> + * return specific data types) will internally make use of this >>>> method. On >>>> + * this level variable substitution is not yet performed. The >>>> returned >>>> + * object is an internal representation of the property value for >>>> the passed >>>> + * in key. It is owned by the {@code Configuration} object. So a >>>> caller >>>> + * should not modify this object. It cannot be guaranteed that this >>>> object >>>> + * will stay constant over time (i.e. further update operations on >>>> the >>>> + * configuration may change its internal state). >>>> + * >>>> + * @param key property to retrieve >>>> + * @return the value to which this configuration maps the specified >>>> key, or >>>> + * null if the configuration contains no mapping for this >>>> key. >>>> + */ >>>> + Object getProperty(String key); >>>> + >>>> + /** >>>> + * Get the list of the keys contained in the configuration that >>>> match the >>>> + * specified prefix. For instance, if the configuration contains >>>> the >>>> + * following keys:
>>>> + * {@code db.user, db.pwd, db.url, window.xpos, window.ypos},
>>>> + * an invocation of {@code getKeys("db");}
>>>> + * will return the keys below:
>>>> + * {@code db.user, db.pwd, db.url}.
>>>> + * Note that the prefix itself is included in the result set if >>>> there is a >>>> + * matching key. The exact behavior - how the prefix is actually >>>> + * interpreted - depends on a concrete implementation. >>>> + * >>>> + * @param prefix The prefix to test against. >>>> + * @return An Iterator of keys that match the prefix. >>>> + * @see #getKeys() >>>> + */ >>>> + Iterator getKeys(String prefix); >>>> + >>>> + /** >>>> + * Get the list of the keys contained in the configuration. The >>>> returned >>>> + * iterator can be used to obtain all defined keys. Note that the >>>> exact >>>> + * behavior of the iterator's {@code remove()} method is specific >>>> to >>>> + * a concrete implementation. It may remove the >>>> corresponding >>>> + * property from the configuration, but this is not guaranteed. In >>>> any case >>>> + * it is no replacement for calling >>>> + * {@link #clearProperty(String)} for this property. So it is >>>> + * highly recommended to avoid using the iterator's {@code >>>> remove()} >>>> + * method. >>>> + * >>>> + * @return An Iterator. >>>> + */ >>>> + Iterator getKeys(); >>>> + >>>> + /** >>>> + * Get a list of properties associated with the given configuration >>>> key. >>>> + * This method expects the given key to have an arbitrary number of >>>> String >>>> + * values, each of which is of the form {code key=value}. These >>>> + * strings are split at the equals sign, and the key parts will >>>> become >>>> + * keys of the returned {@code Properties} object, the value parts >>>> + * become values. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated properties if key is found. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a String/List. >>>> + * >>>> + * @throws IllegalArgumentException if one of the tokens is >>>> + * malformed (does not contain an equals sign). >>>> + */ >>>> + Properties getProperties(String key); >>>> + >>>> + /** >>>> + * Get a boolean associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated boolean. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Boolean. >>>> + */ >>>> + boolean getBoolean(String key); >>>> + >>>> + /** >>>> + * Get a boolean associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated boolean. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Boolean. >>>> + */ >>>> + boolean getBoolean(String key, boolean defaultValue); >>>> + >>>> + /** >>>> + * Get a {@link Boolean} associated with the given configuration >>>> key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated boolean if key is found and has valid >>>> + * format, default value otherwise. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Boolean. >>>> + */ >>>> + Boolean getBoolean(String key, Boolean defaultValue); >>>> + >>>> + /** >>>> + * Get a byte associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated byte. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Byte. >>>> + */ >>>> + byte getByte(String key); >>>> + >>>> + /** >>>> + * Get a byte associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated byte. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Byte. >>>> + */ >>>> + byte getByte(String key, byte defaultValue); >>>> + >>>> + /** >>>> + * Get a {@link Byte} associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated byte if key is found and has valid >>>> format, >>>> default >>>> + * value otherwise. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> object that >>>> + * is not a Byte. >>>> + */ >>>> + Byte getByte(String key, Byte defaultValue); >>>> + >>>> + /** >>>> + * Get a double associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated double. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Double. >>>> + */ >>>> + double getDouble(String key); >>>> + >>>> + /** >>>> + * Get a double associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated double. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Double. >>>> + */ >>>> + double getDouble(String key, double defaultValue); >>>> + >>>> + /** >>>> + * Get a {@link Double} associated with the given configuration >>>> key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated double if key is found and has valid >>>> + * format, default value otherwise. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Double. >>>> + */ >>>> + Double getDouble(String key, Double defaultValue); >>>> + >>>> + /** >>>> + * Get a float associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated float. >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Float. >>>> + */ >>>> + float getFloat(String key); >>>> + >>>> + /** >>>> + * Get a float associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated float. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Float. >>>> + */ >>>> + float getFloat(String key, float defaultValue); >>>> + >>>> + /** >>>> + * Get a {@link Float} associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated float if key is found and has valid >>>> + * format, default value otherwise. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Float. >>>> + */ >>>> + Float getFloat(String key, Float defaultValue); >>>> + >>>> + /** >>>> + * Get a int associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated int. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Integer. >>>> + */ >>>> + int getInt(String key); >>>> + >>>> + /** >>>> + * Get a int associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated int. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Integer. >>>> + */ >>>> + int getInt(String key, int defaultValue); >>>> + >>>> + /** >>>> + * Get an {@link Integer} associated with the given configuration >>>> key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated int if key is found and has valid format, >>>> default >>>> + * value otherwise. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> object that >>>> + * is not a Integer. >>>> + */ >>>> + Integer getInteger(String key, Integer defaultValue); >>>> + >>>> + /** >>>> + * Get a long associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated long. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Long. >>>> + */ >>>> + long getLong(String key); >>>> + >>>> + /** >>>> + * Get a long associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated long. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Long. >>>> + */ >>>> + long getLong(String key, long defaultValue); >>>> + >>>> + /** >>>> + * Get a {@link Long} associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated long if key is found and has valid >>>> + * format, default value otherwise. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Long. >>>> + */ >>>> + Long getLong(String key, Long defaultValue); >>>> + >>>> + /** >>>> + * Get a short associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated short. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Short. >>>> + */ >>>> + short getShort(String key); >>>> + >>>> + /** >>>> + * Get a short associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated short. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Short. >>>> + */ >>>> + short getShort(String key, short defaultValue); >>>> + >>>> + /** >>>> + * Get a {@link Short} associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated short if key is found and has valid >>>> + * format, default value otherwise. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a Short. >>>> + */ >>>> + Short getShort(String key, Short defaultValue); >>>> + >>>> + /** >>>> + * Get a {@link BigDecimal} associated with the given configuration >>>> key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated BigDecimal if key is found and has valid >>>> format >>>> + */ >>>> + BigDecimal getBigDecimal(String key); >>>> + >>>> + /** >>>> + * Get a {@link BigDecimal} associated with the given configuration >>>> key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * >>>> + * @return The associated BigDecimal if key is found and has valid >>>> + * format, default value otherwise. >>>> + */ >>>> + BigDecimal getBigDecimal(String key, BigDecimal defaultValue); >>>> + >>>> + /** >>>> + * Get a {@link BigInteger} associated with the given configuration >>>> key. >>>> + * >>>> + * @param key The configuration key. >>>> + * >>>> + * @return The associated BigInteger if key is found and has valid >>>> format >>>> + */ >>>> + BigInteger getBigInteger(String key); >>>> + >>>> + /** >>>> + * Get a {@link BigInteger} associated with the given configuration >>>> key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * >>>> + * @return The associated BigInteger if key is found and has valid >>>> + * format, default value otherwise. >>>> + */ >>>> + BigInteger getBigInteger(String key, BigInteger defaultValue); >>>> + >>>> + /** >>>> + * Get a string associated with the given configuration key. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated string. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> object that >>>> + * is not a String. >>>> + */ >>>> + String getString(String key); >>>> + >>>> + /** >>>> + * Get a string associated with the given configuration key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated string if key is found and has valid >>>> + * format, default value otherwise. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> object that >>>> + * is not a String. >>>> + */ >>>> + String getString(String key, String defaultValue); >>>> + >>>> + /** >>>> + * Get an array of strings associated with the given configuration >>>> key. >>>> + * If the key doesn't map to an existing object an empty array is >>>> returned >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated string array if key is found. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a String/List of Strings. >>>> + */ >>>> + String[] getStringArray(String key); >>>> + >>>> + /** >>>> + * Get a List of strings associated with the given configuration >>>> key. >>>> + * If the key doesn't map to an existing object an empty List is >>>> returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @return The associated List. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a List. >>>> + */ >>>> + List getList(String key); >>>> + >>>> + /** >>>> + * Get a List of strings associated with the given configuration >>>> key. >>>> + * If the key doesn't map to an existing object, the default value >>>> + * is returned. >>>> + * >>>> + * @param key The configuration key. >>>> + * @param defaultValue The default value. >>>> + * @return The associated List of strings. >>>> + * >>>> + * @throws ConversionException is thrown if the key maps to an >>>> + * object that is not a List. >>>> + */ >>>> + List getList(String key, List defaultValue); >>>> +} >>>> >>>> Propchange: >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**ImmutableConfiguration.java >>>> >>>> ------------------------------**------------------------------** >>>> ------------------ >>>> svn:eol-style = native >>>> >>>> Propchange: >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**ImmutableConfiguration.java >>>> >>>> ------------------------------**------------------------------** >>>> ------------------ >>>> svn:keywords = Date Author Id Revision HeadURL >>>> >>>> Propchange: >>>> commons/proper/configuration/**trunk/src/main/java/org/** >>>> apache/commons/configuration/**ImmutableConfiguration.java >>>> >>>> ------------------------------**------------------------------** >>>> ------------------ >>>> svn:mime-type = text/plain >>>> >>>> >>>> >>>> >>> >> > > ------------------------------**------------------------------**--------- > To unsubscribe, e-mail: dev-unsubscribe@commons.**apache.org > For additional commands, e-mail: dev-help@commons.apache.org > > --20cf3074d220635d2604cdcfcbcb--