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.io.Serializable;
19
20 import javax.annotation.CheckForNull;
21
22 import de.smartics.properties.api.config.domain.key.ConfigurationKey;
23
24 /**
25 * Defines an interface to read property values from a source.
26 *
27 * @see PropertySource
28 * @see PropertyManager
29 */
30 public interface PropertyProvider extends Serializable
31 {
32 // ********************************* Fields *********************************
33
34 // --- constants ------------------------------------------------------------
35
36 // ****************************** Initializer *******************************
37
38 // ****************************** Inner Classes *****************************
39
40 // ********************************* Methods ********************************
41
42 // --- get&set --------------------------------------------------------------
43
44 /**
45 * Returns the unique identifier of the property source. This value is used to
46 * identify the source when reporting about a property.
47 *
48 * @return the unique identifier of the property source.
49 */
50 PropertyLocation getSourceId();
51
52 /**
53 * The key of the configuration this property provider provides properties
54 * for.
55 *
56 * @return the key of the configuration this property provider provides
57 * properties for.
58 */
59 ConfigurationKey<?> getConfigurationKey();
60
61 // --- business -------------------------------------------------------------
62
63 /**
64 * Returns the property with the given {@code name}.
65 *
66 * @param name the name of the property to fetch.
67 * @return the value to the property.
68 * @throws NullPointerException if {@code name} is <code>null</code>.
69 * @throws IllegalArgumentException if the property is not known. A property
70 * is not known if its key has not been registered. A property that
71 * is registered with the <code>null</code> value is known.
72 */
73 @CheckForNull
74 Property getProperty(String name) throws NullPointerException,
75 IllegalArgumentException;
76
77 /**
78 * Returns the collection of all property values known to the system.
79 *
80 * @return the collection of all property values known to the system. May be
81 * empty, but is never <code>null</code>.
82 */
83 PropertyCollection getProperties();
84
85 /**
86 * Checks if a given property is provided by the property provider.
87 *
88 * @param name the property name to check.
89 * @return <code>true</code> if the provider provides a property for the name,
90 * <code>false</code> otherwise.
91 * @throws NullPointerException if {@code name} is <code>null</code>.
92 */
93 boolean containsKey(String name) throws NullPointerException;
94
95 /**
96 * Providers that do not have to fetch their property definitions eagerly
97 * return <code>true</code> here. All others return <code>false</code>.
98 * Usually providers that fetch properties from a backend store are lazy,
99 * while properties on a class path are eager.
100 * <p>
101 * Generally: If the provider cannot fetch individual properties easily, then
102 * they should fetch them eagerly and hold them in memory. Otherwise they will
103 * fetch properties on demand (aka lazily).
104 * </p>
105 *
106 * @return <code>true</code> if the property provider is lazy,
107 * <code>false</code> if it is eager.
108 */
109 boolean isLazy();
110
111 // --- object basics --------------------------------------------------------
112
113 }