001package org.apache.archiva.redback.common.config.api;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.nio.file.Path;
023import java.util.Collection;
024import java.util.List;
025import java.util.Map;
026import java.util.NoSuchElementException;
027import java.util.regex.Pattern;
028
029/**
030 * The configuration registry is a single source of external configuration.
031 *
032 * Each configuration entry is accessible by a unique key. The keys may be hierarchical so, that
033 * you can build subsets of the configuration.
034 *
035 * A configuration may be combined by multiple sources. How the multiple sources are combined, is
036 * part of the implementation classes.
037 *
038 * You can register listeners that are notified, if the configuration changes. The syntax for filter
039 * of notifications is implementation specific.
040 *
041 */
042public interface ConfigRegistry
043{
044
045    /**
046     * Dump the entire registry to a string, for debugging purposes.
047     *
048     * @return the registry contents
049     */
050    String dump( );
051
052    /**
053     * Get the original value stored in the registry. If not found, <code>null</code> is returned.
054     *
055     * @param key The key in the registry.
056     * @return The value.
057     */
058    Object getValue( String key);
059
060    /**
061     * Get a string value from the registry. If not found, <code>null</code> is returned.
062     *
063     * @param key the key in the registry
064     * @return the value
065     */
066    String getString( String key );
067
068    /**
069     * Get a string value from the registry. If not found, the default value is used.
070     *
071     * @param key          the key in the registry
072     * @param defaultValue the default value
073     * @return the value
074     */
075    String getString( String key, String defaultValue );
076
077    /**
078     * Set a string value in the registry.
079     *
080     * @param key   the key in the registry
081     * @param value the value to set
082     */
083    void setString( String key, String value );
084
085    /**
086     * Get an integer value from the registry. If not found, an exception is thrown.
087     *
088     * @param key the key in the registry
089     * @return the value
090     * @throws java.util.NoSuchElementException
091     *          if the key is not found
092     */
093    int getInt( String key ) throws NoSuchElementException;
094
095    /**
096     * Get an integer value from the registry. If not found, the default value is used.
097     *
098     * @param key          the key in the registry
099     * @param defaultValue the default value
100     * @return the value
101     */
102    int getInt( String key, int defaultValue );
103
104    /**
105     * Set an integer value in the registry.
106     *
107     * @param key   the key in the registry
108     * @param value the value to set
109     */
110    void setInt( String key, int value );
111
112    /**
113     * Get a boolean value from the registry. If not found, an exception is thrown.
114     *
115     * @param key the key in the registry
116     * @return the value
117     * @throws java.util.NoSuchElementException
118     *          if the key is not found
119     */
120    boolean getBoolean( String key ) throws NoSuchElementException;
121
122    /**
123     * Get a boolean value from the registry. If not found, the default value is used.
124     *
125     * @param key          the key in the registry
126     * @param defaultValue the default value
127     * @return the value
128     */
129    boolean getBoolean( String key, boolean defaultValue );
130
131    /**
132     * Set a boolean value in the registry.
133     *
134     * @param key   the key in the registry
135     * @param value the value to set
136     */
137    void setBoolean( String key, boolean value );
138
139    /**
140     * Load configuration from the given classloader resource.
141     *
142     * @param name the unique name that identifies this configuration in the combined one
143     * @param resource the location to load the configuration from
144     * @throws RegistryException if a problem occurred reading the resource to add to the registry
145     */
146    void addConfigurationFromResource( String name, String resource )
147        throws RegistryException;
148
149    /**
150     * Load configuration from the given classloader resource.
151     *
152     * @param name the unique name that identifies this configuration in the combined one
153     * @param resource the location to load the configuration from
154     * @param prefix   the location to add the configuration at in the registry
155     * @throws RegistryException if a problem occurred reading the resource to add to the registry
156     */
157    void addConfigurationFromResource( String name, String resource, String prefix )
158        throws RegistryException;
159
160    /**
161     * Load configuration from the given file.
162     *
163     * @param name the unique name that identifies this configuration in the combined one
164     * @param file the location to load the configuration from
165     * @throws RegistryException if a problem occurred reading the resource to add to the registry
166     */
167    void addConfigurationFromFile( String name, Path file )
168        throws RegistryException;
169
170    /**
171     * Load configuration from the given file.
172     *
173     * @param name the unique name that identifies this configuration in the combined one
174     * @param file   the location to load the configuration from
175     * @param prefix the location to add the configuration at in the registry
176     * @throws RegistryException if a problem occurred reading the resource to add to the registry
177     */
178    void addConfigurationFromFile( String name, Path file, String prefix )
179        throws RegistryException;
180
181    /**
182     * Determine if the registry contains any elements.
183     *
184     * @return whether the registry contains any elements
185     */
186    boolean isEmpty( );
187
188    /**
189     * Get a list of strings at the given key in the registry. If not found a empty list will be returned.
190     *
191     * @param key the key to lookup
192     * @return the list of strings
193     */
194    List<String> getList( String key );
195
196    /**
197     * Get the properties at the given key in the registry.
198     *
199     * @param key the key to lookup
200     * @return the properties
201     */
202    Map<String, String> getProperties( String key );
203
204    /**
205     * Get a subset of the registry, for all keys descended from the given key.
206     *
207     * @param key the key to take the subset from
208     * @return the registry subset
209     */
210    ConfigRegistry getSubset( String key ) throws RegistryException;
211
212    /**
213     * Get a list of subsets of the registry, for all keys descended from the given key.
214     *
215     * @param key the key to take the subsets from
216     * @return the registry subsets
217     */
218    List<ConfigRegistry> getSubsetList( String key ) throws RegistryException;
219
220    /**
221     * Get a configuration source part of the registry, identified by the given name. If it doesn't exist, <code>null</code> will be
222     * returned.
223     *
224     * Configurations can be combined from different sources. This returns the configuration of a specific source.
225     * The names are the ones given by the addConfiguration* methods or defined during the initialization process.
226     *
227     * @param name The source name of the configuration source.
228     * @return the The config registry object that represents this source part.
229     */
230    ConfigRegistry getPartOfCombined(String name );
231
232    /**
233     * Save any changes to the registry since it was loaded.
234     *
235     * @throws RegistryException             if there was a problem saving the registry
236     * @throws UnsupportedOperationException if the registry is not writable
237     */
238    void save( )
239        throws RegistryException, UnsupportedOperationException;
240
241    /**
242     * Register a change listener for configuration keys that match the given patterns.
243     *
244     * @param listener the listener
245     */
246    void registerChangeListener( RegistryListener listener, String prefix );
247
248    /**
249     * Unregister the change listener for all events.
250     *
251     * @param listener
252     * @return <code>true</code> if has been removed
253     */
254    boolean unregisterChangeListener( RegistryListener listener );
255
256    /**
257     * Get all keys on the base level in this registry. Keys are only retrieved at a depth of 1.
258     *
259     * @return the set of keys
260     */
261    Collection<String> getBaseKeys( );
262
263    /**
264     * Get all the keys in this registry.
265     * @return the set of keys
266     */
267    Collection<String> getKeys( );
268
269    /**
270     * Return the keys that match the given prefix.
271     *
272     * @param prefix The prefix
273     * @return A collection of keys
274     */
275    Collection<String> getKeys( String prefix);
276
277    /**
278     * Remove a keyed element from the registry.
279     *
280     * @param key the key to remove
281     */
282    void remove( String key );
283
284    /**
285     * Remove a keyed subset of the registry.
286     *
287     * @param key the subset to remove
288     */
289    void removeSubset( String key );
290
291    /**
292     * Initializes the given registry. The definition for the configuration sources is
293     * implementation specific. Implementations should provide methods and/or constructors
294     * that allows to define the configuration source.
295     *
296     * @throws RegistryException if the initialization was not successful
297     */
298    void initialize( ) throws RegistryException;
299}