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.core.domain;
17
18 import java.io.Serializable;
19 import java.util.List;
20 import java.util.Set;
21
22 /**
23 * A registry for a set of property descriptors.
24 * <p>
25 * The typical usage of this class is to fetch a {@link PropertyDescriptor} by
26 * its (string) key.
27 * </p>
28 */
29 public interface PropertyDescriptorRegistry extends Serializable,
30 Iterable<PropertyDescriptor>
31 {
32 // ********************************* Fields *********************************
33
34 // --- constants ------------------------------------------------------------
35
36 // ****************************** Initializer *******************************
37
38 // ****************************** Inner Classes *****************************
39
40 // ********************************* Methods ********************************
41
42 // --- get&set --------------------------------------------------------------
43
44 // --- business -------------------------------------------------------------
45
46 /**
47 * Adds the descriptors to the given declaring type.
48 *
49 * @param propertySetType the type that declares the property
50 * {@code descriptors}.
51 * @param descriptors the descriptors to the given {@code propertySetType}.
52 * @throws NullPointerException if {@code propertySetType} or
53 * {@code descriptors} is <code>null</code>.
54 * @throws DuplicatePropertyDeclarationsException if any of the descriptors
55 * declare the same property.
56 */
57 void addDescriptors(Class<?> propertySetType,
58 List<PropertyDescriptor> descriptors) throws NullPointerException,
59 DuplicatePropertyDeclarationsException;
60
61 /**
62 * Returns the list of mandatory properties.
63 * <p>
64 * Returns a copy that can be edited.
65 * </p>
66 *
67 * @return the list of mandatory properties.
68 */
69 List<PropertyDescriptor> createMandatoryProperties();
70
71 /**
72 * Adds the given descriptor.
73 *
74 * @param propertySetType the property set type to add.
75 * @throws DuplicatePropertyDeclarationsException if any of the descriptors
76 * declare the same property.
77 */
78 void addDescriptors(Class<?> propertySetType)
79 throws DuplicatePropertyDeclarationsException;
80
81 /**
82 * Adds the given descriptors.
83 *
84 * @param propertySetTypes the array of property set types to add.
85 * @throws DuplicatePropertyDeclarationsException if any of the descriptors
86 * declare the same property.
87 */
88 void addDescriptors(Class<?>... propertySetTypes)
89 throws DuplicatePropertyDeclarationsException;
90
91 /**
92 * Adds the given descriptors.
93 *
94 * @param propertySetTypes the array of property set types to add.
95 * @throws DuplicatePropertyDeclarationsException if any of the descriptors
96 * declare the same property.
97 */
98 void addDescriptors(Set<Class<?>> propertySetTypes)
99 throws DuplicatePropertyDeclarationsException;
100
101 /**
102 * Returns the descriptors for the given descriptor type.
103 *
104 * @param propertySet the type for descriptors to fetch.
105 * @return the list of descriptors registered. May be the empty list, but is
106 * never <code>null</code>.
107 */
108 List<? extends PropertyDescriptor> get(Class<?> propertySet);
109
110 /**
111 * Returns the descriptor for the given key or <code>null</code> if no
112 * descriptor is registered for the given key.
113 *
114 * @param key the key whose descriptor is requested.
115 * @return the descriptor to the key or <code>null</code>.
116 */
117 PropertyDescriptor get(String key);
118
119 /**
120 * Returns the property context for the given property descriptor.
121 *
122 * @param descriptor the descriptor whose context is requested.
123 * @return the requested context.
124 * @throws ConfigException if the context for the descriptor cannot be found.
125 */
126 PropertiesContext getContext(PropertyDescriptor descriptor)
127 throws ConfigException;
128
129 /**
130 * Returns the property context for the given property declaring type.
131 *
132 * @param declaringType the type whose context is requested.
133 * @return the requested context.
134 * @throws ConfigException if the context for the descriptor cannot be found.
135 */
136 PropertiesContext getContext(Class<?> declaringType) throws ConfigException;
137
138 /**
139 * Returns the URL to the documentation report for the given property
140 * descriptor.
141 *
142 * @param descriptor the descriptor whose documentation is requested.
143 * @return the URL to the documentation.
144 * @throws ConfigException if the descriptors context cannot be found.
145 */
146 String getDocumentationUrl(PropertyDescriptor descriptor)
147 throws ConfigException;
148
149 /**
150 * Returns the path to the context information for the given property
151 * descriptor.
152 *
153 * @param descriptor the descriptor whose context information is requested.
154 * @return the URL to the context information.
155 * @throws ConfigException if the descriptors context cannot be found.
156 */
157 String getMetaInfPath(PropertyDescriptor descriptor) throws ConfigException;
158
159 /**
160 * Returns the property set types of all property descriptors that have been
161 * added.
162 *
163 * @return the property set types of all property descriptors that have been
164 * added.
165 */
166 Set<Class<?>> getPropertySetTypes();
167
168 // --- object basics --------------------------------------------------------
169 }