View Javadoc

1   /*
2    * Copyright (C) 2006  Tom Gibara
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 2.1 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the Free Software
16   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
17   */
18  package com.tomgibara.pronto.config;
19  
20  /**
21   * 
22   * 
23   * @author Tom Gibara
24   */
25  
26  // TODO consider adding support for concrete classes
27  public interface Config {
28  
29      /**
30       * Sets the policy. If a null policy is supplied, an instance of the default
31       * policy is used.
32       * 
33       * The timeliness with which calls change the policy take effect for live
34       * settings objects is not specified. For this reason, it is recommended
35       * that the appropriate policy be set before calls to the adaptSettings
36       * method.
37       * 
38       * @param policy
39       *            the policy to use for this config, or null for a default
40       *            policy
41       */
42  
43      void setPolicy(ConfigPolicy policy);
44  
45      /**
46       * Returns the policy which is currently in effect for this config.
47       * 
48       * @return the current policy, never null
49       */
50  
51      ConfigPolicy getPolicy();
52  
53      /**
54       * The classloader with which this config was constructed. If the class
55       * loader is null, then the context classloader (or failing that, this
56       * class's classloader) will be used to create new settings objects.
57       * 
58       * @return the class loader used by this object
59       */
60  
61      ClassLoader getClassLoader();
62  
63      /**
64       * @return The configuration source for this object.
65       */
66  
67      ConfigSource getSource();
68  
69      /*
70       * Allowing arrays of interfaces weaken the generics of this method, and
71       * internal methods and adds complexity without providing much benefit (I
72       * think)
73       */
74  
75      /**
76       * This method creates a live mapping of this config's source properties to
77       * a specified interface. Properties for the interface may be drawn from a
78       * subset of all properties by specifying a domain that effectively
79       * namespaces the properties mapped to the interface. If no domain is
80       * specified then all properties will be available for mapping to the
81       * interface In addition, if the inherit argument is true, parent domains
82       * will be searched for values to satisfy interface methods.
83       * 
84       * The same interface may be implemented with various different combinations
85       * of domain and inheritence by calling this method multiple times with
86       * different values.
87       * 
88       * @param domain
89       *            a dot separated prefix which identifies the values which
90       *            should support the interface's implementation, may be null
91       * @param inherit
92       *            true if values should be inherited from parent domains, false
93       *            otherwise
94       * @param iface
95       *            the interface to implement
96       * @param <T>
97       *            the interface type being implemented
98       * @return an implementation of the supplied interface which draws live
99       *         values from this config
100      * 
101      * @throws IllegalArgumentException
102      *             if the supplied class is not an interface
103      */
104 
105     <T> T adaptSettings(String domain, boolean inherit, Class<T> iface) throws IllegalArgumentException;
106 
107     /**
108      * Obtains current value of a specfied propery.
109      * 
110      * @param name
111      *            the name of the property to be returned, not null
112      * @return the property currently associated with the specified name
113      * 
114      * @throws ProntoConfigException
115      *             if the properties could not be accessed and the policy is to
116      *             throw exceptions
117      */
118 
119     String getProperty(String name) throws ProntoConfigException;
120 
121     /**
122      * Returns a config object which is supported by the same properties as this
123      * one but using the specified class loader. If the class loader matches the
124      * one specified on this instance, this is returned.
125      * 
126      * @param classLoader
127      *            the class loader to be used to load settings classes.
128      * @return a new configuration object, or this if a new object is not
129      *         necessary
130      */
131 
132     Config forClassLoader(ClassLoader classLoader);
133 
134     /**
135      * Returns a config object which is supported by the same properties and
136      * which uses the same class loader. This method may be used to create
137      * multiple instances to reduce lock contention during property retrieval
138      * (at the possible expense of duplicated effort by clones). For
139      * correctness, this method requires that the source supplied to a cloned
140      * config support concurrent use.
141      * 
142      * @return a clone of this object.
143      */
144 
145     Config clone();
146 
147 }