1 /*
2 * Copyright 2012-2013 smartics, Kronseder & Reiner GmbH
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package de.smartics.properties.api.config.app;
17
18 import java.io.Serializable;
19 import java.net.URL;
20 import java.util.Collection;
21
22 import de.smartics.properties.api.config.domain.ConfigurationException;
23 import de.smartics.properties.api.config.domain.ConfigurationProperties;
24 import de.smartics.properties.api.config.domain.ConfigurationPropertiesManagement;
25 import de.smartics.properties.api.config.domain.PropertyProvider;
26 import de.smartics.properties.api.config.domain.key.ConfigurationKey;
27 import de.smartics.properties.api.core.domain.PropertyDescriptorRegistry;
28
29 /**
30 * Interface to create instances of {@link ConfigurationProperties}.
31 * <p>
32 * Implementations require to provide a public constructor without arguments.
33 * </p>
34 */
35 public interface ConfigurationPropertiesFactory extends Serializable
36 {
37 // ********************************* Fields *********************************
38
39 // --- constants ------------------------------------------------------------
40
41 // ****************************** Initializer *******************************
42
43 // ****************************** Inner Classes *****************************
44
45 // ********************************* Methods ********************************
46
47 // --- get&set --------------------------------------------------------------
48
49 /**
50 * Returns the factory configuration and changes values.
51 * <p>
52 * Since factories are not thread-safe according to configuration changes, it
53 * is expected that the factory is configured prior to any creation calls.
54 * </p>
55 *
56 * @return a reference to the factory configuration.
57 */
58 FactoryConfiguration getFactoryConfiguration();
59
60 /**
61 * Adds the given URLs to the locations to search for property
62 * {@link de.smartics.properties.api.core.domain.PropertyDescriptor
63 * declarations} and definitions. Property definitions are e.g. properties
64 * files or similar resources that define the actual value of a property.
65 * <p>
66 * Adding URLs only affects later creations of {@link ConfigurationProperties}
67 * instances.
68 * </p>
69 *
70 * @param urls the URLs to add as search location. If the list is empty or
71 * {@code urls} is <code>null</code>, nothing is added without a
72 * warning.
73 */
74 void addRootLocations(Collection<URL> urls);
75
76 /**
77 * Adds the given additional URLs to the locations to search for property
78 * {@link de.smartics.properties.api.core.domain.PropertyDescriptor
79 * declarations} and definitions. Property definitions are e.g. properties
80 * files or similar resources that define the actual value of a property.
81 * <p>
82 * Adding URLs only affects later creations of {@link ConfigurationProperties}
83 * instances.
84 * </p>
85 *
86 * @param urls the URLs to add as search location. If the list is empty or
87 * {@code urls} is <code>null</code>, nothing is added without a
88 * warning.
89 */
90 void addRootLocations(URL... urls);
91
92 /**
93 * Adds the given providers of properties as additional property definitions.
94 * <p>
95 * Adding providers only affects later creations of
96 * {@link ConfigurationProperties} instances.
97 * </p>
98 *
99 * @param providers property providers for additional property name-value
100 * pairs. If the list is empty or {@code providers} is
101 * <code>null</code>, nothing is added without a warning.
102 */
103 void addPropertyProviders(Collection<PropertyProvider> providers);
104
105 /**
106 * Adds the given providers of properties as additional property definitions.
107 * <p>
108 * Adding providers only affects later creations of
109 * {@link ConfigurationProperties} instances.
110 * </p>
111 *
112 * @param providers property providers for additional property name-value
113 * pairs. If the list is empty or {@code providers} is
114 * <code>null</code>, nothing is added without a warning.
115 */
116 void addPropertyProviders(PropertyProvider... providers);
117
118 // --- business -------------------------------------------------------------
119
120 /**
121 * Returns the configuration properties for the given {@code key}. May return
122 * a cached instance.
123 *
124 * @param key the identifier of the configuration properties that is
125 * requested.
126 * @return the requested configuration properties. Never <code>null</code>.
127 * @throws NullPointerException if {@code key} is <code>null</code>.
128 * @throws ConfigurationException on any problem loading the configuration
129 * properties.
130 * @see #createManagement(ConfigurationKey)
131 * @see de.smartics.properties.impl.config.domain.key.envapp.EnvAppConfigurationKeyHelper
132 */
133 ConfigurationProperties create(ConfigurationKey<?> key)
134 throws NullPointerException, ConfigurationException;
135
136 /**
137 * Returns the configuration properties for the given {@code key}. May return
138 * a cached instance.
139 *
140 * @param key the identifier of the configuration properties that is
141 * requested.
142 * @return the requested configuration properties. Never <code>null</code>.
143 * @throws NullPointerException if {@code key} is <code>null</code>.
144 * @throws ConfigurationException on any problem loading the configuration
145 * properties.
146 * @see #create(ConfigurationKey)
147 * @see de.smartics.properties.impl.config.domain.key.envapp.EnvAppConfigurationKeyHelper
148 */
149 ConfigurationPropertiesManagement createManagement(ConfigurationKey<?> key)
150 throws NullPointerException, ConfigurationException;
151
152 /**
153 * Returns the configuration for the default key. The default key is not
154 * associated with a particular environment or application.
155 *
156 * @return the requested configuration properties. Never <code>null</code>.
157 * @throws ConfigurationException on any problem loading the configuration
158 * properties.
159 */
160 ConfigurationProperties createDefault() throws ConfigurationException;
161
162 /**
163 * Returns the management view on a configuration for the default key. The
164 * default key is not associated with a particular environment or application.
165 *
166 * @return the requested configuration properties. Never <code>null</code>.
167 * @throws ConfigurationException on any problem loading the configuration
168 * properties.
169 */
170 ConfigurationPropertiesManagement createDefaultManagement()
171 throws ConfigurationException;
172
173 /**
174 * Returns a list of keys to the registered configurations.
175 *
176 * @return the list of configuration keys.
177 */
178 Collection<ConfigurationKey<?>> getRegisteredConfigurationKeys();
179
180 /**
181 * Returns the registry of declarations used by all created configurations.
182 *
183 * @return the registry of declarations used by all created configurations.
184 */
185 PropertyDescriptorRegistry getRegistry();
186
187 /**
188 * Materializes all configurations found by this factory.
189 *
190 * @return the collection of keys of the materialized configuration. May be
191 * empty, but is never <code>null</code>.
192 */
193 Collection<ConfigurationKey<?>> materialize();
194
195 // --- object basics --------------------------------------------------------
196
197 }