1 /*
2 * Copyright 2011-2020 the original author or authors.
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 * https://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 org.springframework.data.mapping.context;
17
18 import java.util.Collection;
19 import java.util.function.Predicate;
20
21 import org.springframework.data.mapping.MappingException;
22 import org.springframework.data.mapping.PersistentEntity;
23 import org.springframework.data.mapping.PersistentProperty;
24 import org.springframework.data.mapping.PersistentPropertyPath;
25 import org.springframework.data.mapping.PersistentPropertyPaths;
26 import org.springframework.data.mapping.PropertyPath;
27 import org.springframework.data.util.TypeInformation;
28 import org.springframework.lang.Nullable;
29
30 /**
31 * This interface defines the overall context including all known PersistentEntity instances and methods to obtain
32 * instances on demand. it is used internally to establish associations between entities and also at runtime to obtain
33 * entities by name.
34 *
35 * @author Oliver Gierke
36 * @author Jon Brisbin
37 * @author Graeme Rocher
38 * @author Mark Paluch
39 * @author Christoph Strobl
40 */
41 public interface MappingContext<E extends PersistentEntity<?, P>, P extends PersistentProperty<P>> {
42
43 /**
44 * Returns all {@link PersistentEntity}s held in the context.
45 *
46 * @return never {@literal null}.
47 */
48 Collection<E> getPersistentEntities();
49
50 /**
51 * Returns a {@link PersistentEntity} for the given {@link Class}. Will return {@code null} for types that are
52 * considered simple ones.
53 *
54 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
55 * @param type must not be {@literal null}.
56 * @return {@literal null} if no {@link PersistentEntity} found for {@literal type}.
57 */
58 @Nullable
59 E getPersistentEntity(Class<?> type);
60
61 /**
62 * Returns a required {@link PersistentEntity} for the given {@link Class}. Will throw
63 * {@link IllegalArgumentException} for types that are considered simple ones.
64 *
65 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
66 * @param type must not be {@literal null}.
67 * @return never {@literal null}.
68 * @throws MappingException when no {@link PersistentEntity} can be found for given {@literal type}.
69 * @since 2.0
70 */
71 default E getRequiredPersistentEntity(Class<?> type) throws MappingException {
72
73 E entity = getPersistentEntity(type);
74
75 if (entity != null) {
76 return entity;
77 }
78
79 throw new MappingException(String.format("Couldn't find PersistentEntity for type %s!", type));
80 }
81
82 /**
83 * Returns whether the {@link MappingContext} currently contains a {@link PersistentEntity} for the type.
84 *
85 * @param type must not be {@literal null}.
86 * @return {@literal true} if {@link PersistentEntity} present for given {@literal type}.
87 * @since 1.8
88 */
89 boolean hasPersistentEntityFor(Class<?> type);
90
91 /**
92 * Returns a {@link PersistentEntity} for the given {@link TypeInformation}. Will return {@code null} for types that
93 * are considered simple ones.
94 *
95 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
96 * @param type must not be {@literal null}.
97 * @return {@literal null} if no {@link PersistentEntity} found for {@link TypeInformation}.
98 */
99 @Nullable
100 E getPersistentEntity(TypeInformation<?> type);
101
102 /**
103 * Returns a {@link PersistentEntity} for the given {@link TypeInformation}. Will throw
104 * {@link IllegalArgumentException} for types that are considered simple ones.
105 *
106 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
107 * @param type must not be {@literal null}.
108 * @return never {@literal null}.
109 * @throws MappingException when no {@link PersistentEntity} can be found for given {@link TypeInformation}.
110 */
111 default E getRequiredPersistentEntity(TypeInformation<?> type) throws MappingException {
112
113 E entity = getPersistentEntity(type);
114
115 if (entity != null) {
116 return entity;
117 }
118
119 throw new MappingException(String.format("Couldn't find PersistentEntity for type %s!", type));
120 }
121
122 /**
123 * Returns the {@link PersistentEntity} mapped by the given {@link PersistentProperty}.
124 *
125 * @param persistentProperty must not be {@literal null}.
126 * @return the {@link PersistentEntity} mapped by the given {@link PersistentProperty} or {@literal null} if no
127 * {@link PersistentEntity} exists for it or the {@link PersistentProperty} does not refer to an entity (the
128 * type of the property is considered simple see
129 * {@link org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)}).
130 */
131 @Nullable
132 E getPersistentEntity(P persistentProperty);
133
134 /**
135 * Returns the {@link PersistentEntity} mapped by the given {@link PersistentProperty}.
136 *
137 * @param persistentProperty must not be {@literal null}.
138 * @return the {@link PersistentEntity} mapped by the given {@link PersistentProperty} or {@literal null} if no
139 * {@link PersistentEntity} exists for it or the {@link PersistentProperty} does not refer to an entity (the
140 * type of the property is considered simple see
141 * {@link org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)}).
142 * @throws MappingException when no {@link PersistentEntity} can be found for given {@link PersistentProperty}.
143 */
144 default E getRequiredPersistentEntity(P persistentProperty) throws MappingException {
145
146 E entity = getPersistentEntity(persistentProperty);
147
148 if (entity != null) {
149 return entity;
150 }
151
152 throw new MappingException(String.format("Couldn't find PersistentEntity for property %s!", persistentProperty));
153 }
154
155 /**
156 * Returns all {@link PersistentProperty}s for the given path expression based on the given {@link PropertyPath}.
157 *
158 * @param propertyPath must not be {@literal null}.
159 * @return the {@link PersistentPropertyPath} representing the given {@link PropertyPath}.
160 * @throws InvalidPersistentPropertyPath in case not all of the segments of the given {@link PropertyPath} can be
161 * resolved.
162 */
163 PersistentPropertyPath<P> getPersistentPropertyPath(PropertyPath propertyPath) throws InvalidPersistentPropertyPath;
164
165 /**
166 * Returns all {@link PersistentProperty}s for the given dot path notation based on the given type.
167 *
168 * @param propertyPath must not be {@literal null}.
169 * @param type must not be {@literal null}.
170 * @return the {@link PersistentPropertyPath} representing the given property path on the given type.
171 * @throws InvalidPersistentPropertyPath in case not all of the segments of the given property path can be resolved.
172 */
173 PersistentPropertyPath<P> getPersistentPropertyPath(String propertyPath, Class<?> type)
174 throws InvalidPersistentPropertyPath;
175
176 /**
177 * Returns all {@link PersistentPropertyPath}s pointing to properties on the given type that match the given
178 * {@link Predicate}. In case of circular references the detection will stop at the property that references a type
179 * that's already included in the path. Note, that is is a potentially expensive operation as results cannot be
180 * cached.
181 *
182 * @param type must not be {@literal null}.
183 * @param predicate must not be {@literal null}.
184 * @return
185 * @since 2.1
186 */
187 <T> PersistentPropertyPaths<T, P> findPersistentPropertyPaths(Class<T> type, Predicate<? super P> predicate);
188
189 /**
190 * Returns the {@link TypeInformation}s for all {@link PersistentEntity}s in the {@link MappingContext}.
191 *
192 * @return all {@link TypeInformation}s for the {@link PersistentEntity}s in the {@link MappingContext}.
193 * @since 1.8
194 */
195 Collection<TypeInformation<?>> getManagedTypes();
196 }
197