1 /**
2 * This file Copyright (c) 2014-2018 Magnolia International
3 * Ltd. (http://www.magnolia-cms.com). All rights reserved.
4 *
5 *
6 * This file is dual-licensed under both the Magnolia
7 * Network Agreement and the GNU General Public License.
8 * You may elect to use one or the other of these licenses.
9 *
10 * This file is distributed in the hope that it will be
11 * useful, but AS-IS and WITHOUT ANY WARRANTY; without even the
12 * implied warranty of MERCHANTABILITY or FITNESS FOR A
13 * PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT.
14 * Redistribution, except as permitted by whichever of the GPL
15 * or MNA you select, is prohibited.
16 *
17 * 1. For the GPL license (GPL), you can redistribute and/or
18 * modify this file under the terms of the GNU General
19 * Public License, Version 3, as published by the Free Software
20 * Foundation. You should have received a copy of the GNU
21 * General Public License, Version 3 along with this program;
22 * if not, write to the Free Software Foundation, Inc., 51
23 * Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
24 *
25 * 2. For the Magnolia Network Agreement (MNA), this file
26 * and the accompanying materials are made available under the
27 * terms of the MNA which accompanies this distribution, and
28 * is available at http://www.magnolia-cms.com/mna.html
29 *
30 * Any modifications to this file must keep this entire header
31 * intact.
32 *
33 */
34 package info.magnolia.config.registry;
35
36 import static info.magnolia.config.registry.DefinitionProvider.Problem.SeverityType.*;
37 import static java.util.stream.Collectors.toList;
38
39 import info.magnolia.config.registry.decoration.DefinitionDecorator;
40 import info.magnolia.transformer.TransformationProblem;
41
42 import java.util.Collection;
43 import java.util.Collections;
44 import java.util.List;
45
46 /**
47 * This is NOT called Provider to avoid confusion with javax.inject.Provider; however, keep in mind that some objects
48 * provided by these and registries are not necessarily "just" definition, they might be "live" objects (Renderer is an example).
49 * Naming this ConfiguredObjectProvider might have been more correct, but also a bit long.
50 *
51 * @param <T> the provided type
52 */
53 public interface DefinitionProvider<T> {
54
55 List<DefinitionDecorator<T>> getDecorators();
56
57 DefinitionMetadata getMetadata();
58
59 /**
60 * Returns the underlying bean if and only if it is successfully resolved, is valid, and is enabled.
61 *
62 * @throws Registry.InvalidDefinitionException (which is a RuntimeException) if the underlying bean is not successfully resolved, not valid, or not enabled.
63 */
64 T get() throws Registry.InvalidDefinitionException;
65
66 /**
67 * Returns a {@link info.magnolia.config.registry.DefinitionRawView} representation the underlying bean; it might be
68 * invalid, partially resolved and/or disabled.
69 */
70 DefinitionRawView getRaw();
71
72 boolean isValid();
73
74 /**
75 * Returns the timestamp of the last change of the underlying definition change. If a {@link DefinitionProvider} merely wraps a definition instance -
76 * such timestamp would never change and be always equal to the provider's creation date. However, if a provider generates the definition on the fly from some
77 * resource - the last modified date might change and that might be a clear signal for an update of the structures that decorate/cache definitions.
78 *
79 * @see info.magnolia.config.registry.decoration.CachingDefinitionDecorator
80 */
81 long getLastModified();
82
83 /**
84 * @deprecated since 5.5 - use {@link #getProblems()} instead.
85 */
86 @Deprecated
87 default List<String> getErrorMessages() {
88 return getProblems().stream().map(problem -> problem.getTitle() + problem.getDetails()).collect(toList());
89 }
90
91 default Collection<Problem> getProblems() {
92 return Collections.emptyList();
93 }
94
95 /**
96 * Allows to record and memoize the details about an issue which might have occurred during the population of a {@link DefinitionProvider definition provider}.
97 * Provides the following information:
98 * <ul>
99 * <li>title</li>
100 * <li>description</li>
101 * <li>{@link Type type}</li>
102 * <li>{@link SeverityType severity type}</li>
103 * <li>related exception instance if any</li>
104 * </ul>
105 */
106 interface Problem {
107
108 SeverityType getSeverityType();
109
110 Type getType();
111
112 String getLocation();
113
114 String getTitle();
115
116 String getDetails();
117
118 Exception getRelatedException();
119
120 static DefinitionProviderProblemBuilder builder() {
121 return new DefinitionProviderProblemBuilder();
122 }
123
124 static DefinitionProviderProblemBuilder severe() {
125 return builder().withSeverityType(SEVERE);
126 }
127
128 static DefinitionProviderProblemBuilder major() {
129 return builder().withSeverityType(MAJOR);
130 }
131
132 static DefinitionProviderProblemBuilder deprecated() {
133 return builder().withSeverityType(DEPRECATED);
134 }
135
136 static DefinitionProviderProblemBuilder minor() {
137 return builder().withSeverityType(MINOR);
138 }
139
140 static DefinitionProviderProblemBuilder fromTransformationProblem(TransformationProblem transformationProblem) {
141 return builder()
142 // Never treat a transformation problem as a severe problem since the bean is still returned after all and might be to some degree usable
143 .withSeverityType(transformationProblem.getSeverityType() == TransformationProblem.SeverityType.WARNING ? MINOR : transformationProblem.getSeverityType() == TransformationProblem.SeverityType.DEPRECATED ? DEPRECATED : MAJOR)
144 .withDetails(transformationProblem.getMessage())
145 .withLocation(transformationProblem.getLocation())
146 .withRelatedException(transformationProblem.getException());
147 }
148
149 /**
150 * Interface of a potential {@link Problem} type. Typically provides a name (for computers) and caption (for humans).
151 */
152 interface Type {
153 String name();
154
155 String getCaption();
156 }
157
158 /**
159 * Default pre-defined {@link Type problem types}.
160 */
161 enum DefaultTypes implements Type {
162 RESOLUTION {
163 @Override
164 public String getCaption() {
165 return "Definition resolution";
166 }
167 },
168
169 DECORATION {
170 @Override
171 public String getCaption() {
172 return "Definition decoration";
173 }
174 },
175
176 SEMANTIC {
177 @Override
178 public String getCaption() {
179 return "Definition semantics";
180 }
181 },
182
183 REFERENCES {
184 @Override
185 public String getCaption() {
186 return "Definition references";
187 }
188 }
189 }
190
191 /**
192 * Possible severity types of {@link Problem definition provider problems}.
193 */
194 enum SeverityType {
195 SEVERE, MAJOR, DEPRECATED, MINOR
196 }
197 }
198
199 }