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 import de.smartics.util.annotations.marker.ServiceInterface;
29
30 /**
31 * Interface to create instances of {@link ConfigurationProperties}.
32 * <p>
33 * Implementations require to provide a public constructor without arguments.
34 * </p>
35 */
36 @ServiceInterface
37 public interface ConfigurationPropertiesFactory extends Serializable
38 {
39 // ********************************* Fields *********************************
40
41 // --- constants ------------------------------------------------------------
42
43 // ****************************** Initializer *******************************
44
45 // ****************************** Inner Classes *****************************
46
47 // ********************************* Methods ********************************
48
49 // --- get&set --------------------------------------------------------------
50
51 /**
52 * Returns the unique id for this factory
53 *
54 * @return the uniqu id.
55 */
56 String getId();
57
58 /**
59 * Returns the factory configuration and changes values.
60 * <p>
61 * Since factories are not thread-safe according to configuration changes, it
62 * is expected that the factory is configured prior to any creation calls.
63 * </p>
64 *
65 * @return a reference to the factory configuration.
66 */
67 FactoryConfiguration getFactoryConfiguration();
68
69 /**
70 * Adds the given URLs to the locations to search for property
71 * {@link de.smartics.properties.api.core.domain.PropertyDescriptor
72 * declarations} and definitions. Property definitions are e.g. properties
73 * files or similar resources that define the actual value of a property.
74 * <p>
75 * Adding URLs only affects later creations of {@link ConfigurationProperties}
76 * instances.
77 * </p>
78 *
79 * @param urls the URLs to add as search location. If the list is empty or
80 * {@code urls} is <code>null</code>, nothing is added without a
81 * warning.
82 */
83 void addRootLocations(Collection<URL> urls);
84
85 /**
86 * Adds the given additional URLs to the locations to search for property
87 * {@link de.smartics.properties.api.core.domain.PropertyDescriptor
88 * declarations} and definitions. Property definitions are e.g. properties
89 * files or similar resources that define the actual value of a property.
90 * <p>
91 * Adding URLs only affects later creations of {@link ConfigurationProperties}
92 * instances.
93 * </p>
94 *
95 * @param urls the URLs to add as search location. If the list is empty or
96 * {@code urls} is <code>null</code>, nothing is added without a
97 * warning.
98 */
99 void addRootLocations(URL... urls);
100
101 /**
102 * Adds the given providers of properties as additional property definitions.
103 * <p>
104 * Adding providers only affects later creations of
105 * {@link ConfigurationProperties} instances.
106 * </p>
107 *
108 * @param providers property providers for additional property name-value
109 * pairs. If the list is empty or {@code providers} is
110 * <code>null</code>, nothing is added without a warning.
111 */
112 void addPropertyProviders(Collection<PropertyProvider> providers);
113
114 /**
115 * Adds the given providers of properties as additional property definitions.
116 * <p>
117 * Adding providers only affects later creations of
118 * {@link ConfigurationProperties} instances.
119 * </p>
120 *
121 * @param providers property providers for additional property name-value
122 * pairs. If the list is empty or {@code providers} is
123 * <code>null</code>, nothing is added without a warning.
124 */
125 void addPropertyProviders(PropertyProvider... providers);
126
127 // --- business -------------------------------------------------------------
128
129 /**
130 * Returns the configuration properties for the given {@code key}. May return
131 * a cached instance.
132 *
133 * @param key the identifier of the configuration properties that is
134 * requested.
135 * @return the requested configuration properties. Never <code>null</code>.
136 * @throws NullPointerException if {@code key} is <code>null</code>.
137 * @throws ConfigurationException on any problem loading the configuration
138 * properties.
139 * @see #createManagement(ConfigurationKey)
140 * @see de.smartics.properties.impl.config.domain.key.envapp.EnvAppConfigurationKeyHelper
141 */
142 ConfigurationProperties create(ConfigurationKey<?> key)
143 throws NullPointerException, ConfigurationException;
144
145 /**
146 * Returns the configuration properties for the given {@code key}. May return
147 * a cached instance.
148 *
149 * @param key the identifier of the configuration properties that is
150 * requested.
151 * @return the requested configuration properties. Never <code>null</code>.
152 * @throws NullPointerException if {@code key} is <code>null</code>.
153 * @throws ConfigurationException on any problem loading the configuration
154 * properties.
155 * @see #create(ConfigurationKey)
156 * @see de.smartics.properties.impl.config.domain.key.envapp.EnvAppConfigurationKeyHelper
157 */
158 ConfigurationPropertiesManagement createManagement(ConfigurationKey<?> key)
159 throws NullPointerException, ConfigurationException;
160
161 /**
162 * Returns the configuration for the default key. The default key is not
163 * associated with a particular environment or application.
164 *
165 * @return the requested configuration properties. Never <code>null</code>.
166 * @throws ConfigurationException on any problem loading the configuration
167 * properties.
168 */
169 ConfigurationProperties createDefault() throws ConfigurationException;
170
171 /**
172 * Returns the management view on a configuration for the default key. The
173 * default key is not associated with a particular environment or application.
174 *
175 * @return the requested configuration properties. Never <code>null</code>.
176 * @throws ConfigurationException on any problem loading the configuration
177 * properties.
178 */
179 ConfigurationPropertiesManagement createDefaultManagement()
180 throws ConfigurationException;
181
182 /**
183 * Returns a list of keys to the registered configurations.
184 *
185 * @return the list of configuration keys.
186 */
187 Collection<ConfigurationKey<?>> getRegisteredConfigurationKeys();
188
189 /**
190 * Returns the registry of declarations used by all created configurations.
191 *
192 * @return the registry of declarations used by all created configurations.
193 */
194 PropertyDescriptorRegistry getRegistry();
195
196 /**
197 * Materializes all configurations found by this factory.
198 *
199 * @return the collection of keys of the materialized configuration. May be
200 * empty, but is never <code>null</code>.
201 */
202 Collection<ConfigurationKey<?>> materialize();
203
204 // --- object basics --------------------------------------------------------
205
206 }