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.domain;
17
18 import java.util.List;
19
20 import de.smartics.properties.api.core.domain.DuplicatePropertyDeclarationsException;
21 import de.smartics.properties.api.core.domain.PropertyDescriptor;
22 import de.smartics.properties.api.core.domain.PropertyDescriptorRegistry;
23 import de.smartics.properties.api.core.domain.PropertyKey;
24 import de.smartics.properties.api.core.domain.PropertyValidationException;
25 import de.smartics.properties.api.core.domain.ReadOnlyPropertyException;
26 import de.smartics.properties.api.core.security.PropertyValueSecurity;
27
28 /**
29 * Provides management access to the configuration properties. Allows to add
30 * properties and other functions not related with accessing property values.
31 *
32 * @impl This interface is intended to be implemented by service providers. API
33 * users are intended to us this interface to access properties. For
34 * details on creating instances of classes implementing this interface
35 * please refer to {@link de.smartics.properties.api.config}.
36 */
37 public interface ConfigurationPropertiesManagement extends
38 ConfigurationProperties
39 {
40 // ********************************* Fields *********************************
41
42 // --- constants ------------------------------------------------------------
43
44 // ****************************** Initializer *******************************
45
46 // ****************************** Inner Classes *****************************
47
48 // ********************************* Methods ********************************
49
50 // --- get&set --------------------------------------------------------------
51
52 /**
53 * Returns the registry to resolve property descriptors.
54 *
55 * @return the registry to resolve property descriptors.
56 */
57 PropertyDescriptorRegistry getRegistry();
58
59 /**
60 * Returns the property value security helper to en- and decrypt property
61 * values.
62 *
63 * @return the property value security helper to en- and decrypt property
64 * values.
65 */
66 PropertyValueSecurity getPropertyValueSecurity();
67
68 /**
69 * Sets the administration mode for this configuration.
70 *
71 * @param newMode the new value of the mode <code>true</code> if the
72 * configuration is to be set in administration mode,
73 * <code>false</code> if not.
74 * @see #isInAdminMode()
75 */
76 void setToAdminMode(boolean newMode);
77
78 // --- business -------------------------------------------------------------
79
80 /**
81 * Adds all property descriptors declared in the given type.
82 *
83 * @param declaringType the type that declares the descriptors.
84 * @throws DuplicatePropertyDeclarationsException if any of the descriptors
85 * declare the same property.
86 */
87 void addDescriptors(Class<?> declaringType)
88 throws DuplicatePropertyDeclarationsException;
89
90 /**
91 * Returns the descriptor for the given key.
92 *
93 * @param key the of the requested descriptor.
94 * @return the descriptor whose key matches the given {@code key}.
95 * @throws UnknownPropertyException if the property is not known.
96 */
97 PropertyDescriptor getDescriptor(String key) throws UnknownPropertyException;
98
99 /**
100 * Returns the descriptor for the given key.
101 *
102 * @param key the of the requested descriptor.
103 * @return the descriptor whose key matches the given {@code key}.
104 * @throws UnknownPropertyException if the property is not known.
105 */
106 PropertyDescriptor getDescriptor(PropertyKey key)
107 throws UnknownPropertyException;
108
109 /**
110 * Returns the list of mandatory properties.
111 * <p>
112 * Returns a copy that can be edited.
113 * </p>
114 *
115 * @return the list of mandatory properties.
116 */
117 List<PropertyDescriptor> getMandatoryPropertyDescriptors();
118
119 /**
120 * Adds the given definitions to this configuration.
121 *
122 * @param properties the property definitions to add.
123 * @return a reference to this configuration for chaining.
124 * @throws NullPointerException if {@code properties} is <code>null</code>.
125 */
126 ConfigurationPropertiesManagement addDefinitions(PropertyProvider properties)
127 throws NullPointerException;
128
129 /**
130 * Sets the property value for the given key.
131 *
132 * @param key the key to the property.
133 * @param value the value to the property.
134 * @return the old value to the property. A value of <code>null</code> is
135 * returned if the property had no value prior to this call.
136 * @throws NullPointerException if {@code key} is <code>null</code>.
137 * @throws PropertyValidationException if the property value is invalid
138 * according to its constraints.
139 * @throws ReadOnlyPropertyException if the property to update is read-only.
140 */
141 Property setProperty(PropertyKey key, String value)
142 throws NullPointerException, PropertyValidationException,
143 ReadOnlyPropertyException;
144
145 /**
146 * Unsets the property value for the given key.
147 *
148 * @param key the key to the property.
149 * @return the old value to the property. A value of <code>null</code> is
150 * returned if the property had no value prior to this call.
151 * @throws NullPointerException if {@code key} is <code>null</code>.
152 * @throws ReadOnlyPropertyException if the property to update is read-only.
153 */
154 Property unsetProperty(PropertyKey key) throws NullPointerException,
155 ReadOnlyPropertyException;
156
157 /**
158 * Signal to flush properties changed in memory to be written to a secondary
159 * storage.
160 * <p>
161 * Implementations are not required to only write on a flush. They have to
162 * make sure that after the flush is called, all data is transfered to the
163 * secondary storage.
164 * </p>
165 */
166 void flush();
167
168 // ... property store access ................................................
169
170 /**
171 * Provides direct access to the properties in the underlying store.
172 *
173 * @return direct access to the properties in the underlying store.
174 */
175 PropertyStoreAccessor getPropertyStoreAccessor();
176
177 // --- object basics --------------------------------------------------------
178
179 /**
180 * Creates a serializable variant of this implementation.
181 *
182 * @return a serializable variant of this implementation.
183 * @see de.smartics.properties.spi.config.domain.ConfigurationPropertiesProxy
184 * @see de.smartics.properties.spi.config.domain.ConfigurationPropertiesManagementProxy
185 */
186 SerializableConfigurationPropertiesManagement toSerializable();
187
188 /**
189 * Creates an representative of this configuration. If the configuration
190 * serves for a specific configuration key, this instance will be returned. If
191 * the configuration servers for multiple configuration keys, the
192 * representative is returned. The representative is usually the configuration
193 * that is associated with the full key.
194 *
195 * @return the representative (may be this).
196 */
197 ConfigurationPropertiesManagement toRepresentative();
198 }