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 import java.util.Properties;
20
21 import de.smartics.properties.api.core.domain.DuplicatePropertyDeclarationsException;
22 import de.smartics.properties.api.core.domain.PropertyDescriptor;
23 import de.smartics.properties.api.core.domain.PropertyDescriptorRegistry;
24 import de.smartics.properties.api.core.domain.PropertyKey;
25 import de.smartics.properties.api.core.domain.PropertyValidationException;
26 import de.smartics.properties.api.core.domain.ReadOnlyPropertyException;
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 // --- business -------------------------------------------------------------
60
61 /**
62 * Adds all property descriptors declared in the given type.
63 *
64 * @param declaringType the type that declares the descriptors.
65 * @throws DuplicatePropertyDeclarationsException if any of the descriptors
66 * declare the same property.
67 */
68 void addDescriptors(Class<?> declaringType)
69 throws DuplicatePropertyDeclarationsException;
70
71 /**
72 * Returns the descriptor for the given key.
73 *
74 * @param key the of the requested descriptor.
75 * @return the descriptor whose key matches the given {@code key}.
76 * @throws UnknownPropertyException if the property is not known.
77 */
78 PropertyDescriptor getDescriptor(String key) throws UnknownPropertyException;
79
80 /**
81 * Returns the descriptor for the given key.
82 *
83 * @param key the of the requested descriptor.
84 * @return the descriptor whose key matches the given {@code key}.
85 * @throws UnknownPropertyException if the property is not known.
86 */
87 PropertyDescriptor getDescriptor(PropertyKey key)
88 throws UnknownPropertyException;
89
90 /**
91 * Returns the list of mandatory properties.
92 * <p>
93 * Returns a copy that can be edited.
94 * </p>
95 *
96 * @return the list of mandatory properties.
97 */
98 List<PropertyDescriptor> getMandatoryPropertyDescriptors();
99
100 /**
101 * Adds the given definitions to this configuration.
102 *
103 * @param properties the property definitions to add.
104 * @return a reference to this configuration for chaining.
105 * @throws NullPointerException if {@code properties} is <code>null</code>.
106 */
107 ConfigurationPropertiesManagement addDefinitions(Properties properties)
108 throws NullPointerException;
109
110 /**
111 * Sets the property value for the given key.
112 *
113 * @param key the key to the property.
114 * @param value the value to the property.
115 * @return the old value to the property. A value of <code>null</code> is
116 * returned if the property had no value prior to this call.
117 * @throws NullPointerException if {@code key} is <code>null</code>.
118 * @throws PropertyValidationException if the property value is invalid
119 * according to its constraints.
120 * @throws ReadOnlyPropertyException if the property to update is read-only.
121 */
122 Property setProperty(PropertyKey key, String value)
123 throws NullPointerException, PropertyValidationException,
124 ReadOnlyPropertyException;
125
126 /**
127 * Unsets the property value for the given key.
128 *
129 * @param key the key to the property.
130 * @return the old value to the property. A value of <code>null</code> is
131 * returned if the property had no value prior to this call.
132 * @throws NullPointerException if {@code key} is <code>null</code>.
133 * @throws ReadOnlyPropertyException if the property to update is read-only.
134 */
135 Property unsetProperty(PropertyKey key) throws NullPointerException,
136 ReadOnlyPropertyException;
137
138 /**
139 * Signal to flush properties changed in memory to be written to a secondary
140 * storage.
141 * <p>
142 * Implementations are not required to only write on a flush. They have to
143 * make sure that after the flush is called, all data is transfered to the
144 * secondary storage.
145 * </p>
146 */
147 void flush();
148
149 // --- object basics --------------------------------------------------------
150
151 /**
152 * Creates a serializable variant of this implementation.
153 *
154 * @return a serializable variant of this implementation.
155 * @see de.smartics.properties.spi.config.domain.ConfigurationPropertiesProxy
156 * @see de.smartics.properties.spi.config.domain.ConfigurationPropertiesManagementProxy
157 */
158 SerializableConfigurationPropertiesManagement toSerializable();
159 }