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}