/*
 * Copyright 2011-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.springframework.data.mapping.context;

import java.util.Collection;
import java.util.function.Predicate;

import org.springframework.data.mapping.MappingException;
import org.springframework.data.mapping.PersistentEntity;
import org.springframework.data.mapping.PersistentProperty;
import org.springframework.data.mapping.PersistentPropertyPath;
import org.springframework.data.mapping.PersistentPropertyPaths;
import org.springframework.data.mapping.PropertyPath;
import org.springframework.data.util.TypeInformation;
import org.springframework.lang.Nullable;

This interface defines the overall context including all known PersistentEntity instances and methods to obtain
instances on demand. it is used internally to establish associations between entities and also at runtime to obtain
entities by name.
Author:
Oliver Gierke, Jon Brisbin, Graeme Rocher, Mark Paluch, Christoph Strobl/**
 * This interface defines the overall context including all known PersistentEntity instances and methods to obtain
 * instances on demand. it is used internally to establish associations between entities and also at runtime to obtain
 * entities by name.
 *
 * @author Oliver Gierke
 * @author Jon Brisbin
 * @author Graeme Rocher
 * @author Mark Paluch
 * @author Christoph Strobl
 */
public interface MappingContext<E extends PersistentEntity<?, P>, P extends PersistentProperty<P>> {

	
Returns all PersistentEntitys held in the context. 
Returns:
never null./**
	 * Returns all {@link PersistentEntity}s held in the context.
	 *
	 * @return never {@literal null}.
	 */
	Collection<E> getPersistentEntities();

	
Returns a PersistentEntity for the given Class. Will return null for types that are considered simple ones. 
Params:
type – must not be null.
See Also:
SimpleTypeHolder.isSimpleType(Class<?>)
Returns:
null if no PersistentEntity found for type./**
	 * Returns a {@link PersistentEntity} for the given {@link Class}. Will return {@code null} for types that are
	 * considered simple ones.
	 *
	 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
	 * @param type must not be {@literal null}.
	 * @return {@literal null} if no {@link PersistentEntity} found for {@literal type}.
	 */
	@Nullable
	E getPersistentEntity(Class<?> type);

	
Returns a required PersistentEntity for the given Class. Will throw IllegalArgumentException for types that are considered simple ones. 
Params:
type – must not be null.
Throws:
MappingException – when no PersistentEntity can be found for given type.
See Also:
SimpleTypeHolder.isSimpleType(Class<?>)
Returns:
never null.
Since:
2.0/**
	 * Returns a required {@link PersistentEntity} for the given {@link Class}. Will throw
	 * {@link IllegalArgumentException} for types that are considered simple ones.
	 *
	 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
	 * @param type must not be {@literal null}.
	 * @return never {@literal null}.
	 * @throws MappingException when no {@link PersistentEntity} can be found for given {@literal type}.
	 * @since 2.0
	 */
	default E getRequiredPersistentEntity(Class<?> type) throws MappingException {

		E entity = getPersistentEntity(type);

		if (entity != null) {
			return entity;
		}

		throw new MappingException(String.format("Couldn't find PersistentEntity for type %s!", type));
	}

	
Returns whether the MappingContext currently contains a PersistentEntity for the type. 
Params:
type – must not be null.
Returns:
true if PersistentEntity present for given type.
Since:
1.8/**
	 * Returns whether the {@link MappingContext} currently contains a {@link PersistentEntity} for the type.
	 *
	 * @param type must not be {@literal null}.
	 * @return {@literal true} if {@link PersistentEntity} present for given {@literal type}.
	 * @since 1.8
	 */
	boolean hasPersistentEntityFor(Class<?> type);

	
Returns a PersistentEntity for the given TypeInformation. Will return null for types that are considered simple ones. 
Params:
type – must not be null.
See Also:
SimpleTypeHolder.isSimpleType(Class<?>)
Returns:
null if no PersistentEntity found for TypeInformation./**
	 * Returns a {@link PersistentEntity} for the given {@link TypeInformation}. Will return {@code null} for types that
	 * are considered simple ones.
	 *
	 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
	 * @param type must not be {@literal null}.
	 * @return {@literal null} if no {@link PersistentEntity} found for {@link TypeInformation}.
	 */
	@Nullable
	E getPersistentEntity(TypeInformation<?> type);

	
Returns a PersistentEntity for the given TypeInformation. Will throw IllegalArgumentException for types that are considered simple ones. 
Params:
type – must not be null.
Throws:
MappingException – when no PersistentEntity can be found for given TypeInformation.
See Also:
SimpleTypeHolder.isSimpleType(Class<?>)
Returns:
never null./**
	 * Returns a {@link PersistentEntity} for the given {@link TypeInformation}. Will throw
	 * {@link IllegalArgumentException} for types that are considered simple ones.
	 *
	 * @see org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)
	 * @param type must not be {@literal null}.
	 * @return never {@literal null}.
	 * @throws MappingException when no {@link PersistentEntity} can be found for given {@link TypeInformation}.
	 */
	default E getRequiredPersistentEntity(TypeInformation<?> type) throws MappingException {

		E entity = getPersistentEntity(type);

		if (entity != null) {
			return entity;
		}

		throw new MappingException(String.format("Couldn't find PersistentEntity for type %s!", type));
	}

	
Returns the PersistentEntity mapped by the given PersistentProperty. 
Params:
persistentProperty – must not be null.
Returns:
the PersistentEntity mapped by the given PersistentProperty or null if no PersistentEntity exists for it or the PersistentProperty does not refer to an entity (the type of the property is considered simple see SimpleTypeHolder.isSimpleType(Class<?>))./**
	 * Returns the {@link PersistentEntity} mapped by the given {@link PersistentProperty}.
	 *
	 * @param persistentProperty must not be {@literal null}.
	 * @return the {@link PersistentEntity} mapped by the given {@link PersistentProperty} or {@literal null} if no
	 *         {@link PersistentEntity} exists for it or the {@link PersistentProperty} does not refer to an entity (the
	 *         type of the property is considered simple see
	 *         {@link org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)}).
	 */
	@Nullable
	E getPersistentEntity(P persistentProperty);

	
Returns the PersistentEntity mapped by the given PersistentProperty. 
Params:
persistentProperty – must not be null.
Throws:
MappingException – when no PersistentEntity can be found for given PersistentProperty.
Returns:
the PersistentEntity mapped by the given PersistentProperty or null if no PersistentEntity exists for it or the PersistentProperty does not refer to an entity (the type of the property is considered simple see SimpleTypeHolder.isSimpleType(Class<?>))./**
	 * Returns the {@link PersistentEntity} mapped by the given {@link PersistentProperty}.
	 *
	 * @param persistentProperty must not be {@literal null}.
	 * @return the {@link PersistentEntity} mapped by the given {@link PersistentProperty} or {@literal null} if no
	 *         {@link PersistentEntity} exists for it or the {@link PersistentProperty} does not refer to an entity (the
	 *         type of the property is considered simple see
	 *         {@link org.springframework.data.mapping.model.SimpleTypeHolder#isSimpleType(Class)}).
	 * @throws MappingException when no {@link PersistentEntity} can be found for given {@link PersistentProperty}.
	 */
	default E getRequiredPersistentEntity(P persistentProperty) throws MappingException {

		E entity = getPersistentEntity(persistentProperty);

		if (entity != null) {
			return entity;
		}

		throw new MappingException(String.format("Couldn't find PersistentEntity for property %s!", persistentProperty));
	}

	
Returns all PersistentPropertys for the given path expression based on the given PropertyPath. 
Params:
propertyPath – must not be null.
Throws:
InvalidPersistentPropertyPath – in case not all of the segments of the given PropertyPath can be resolved.
Returns:
the PersistentPropertyPath representing the given PropertyPath./**
	 * Returns all {@link PersistentProperty}s for the given path expression based on the given {@link PropertyPath}.
	 *
	 * @param propertyPath must not be {@literal null}.
	 * @return the {@link PersistentPropertyPath} representing the given {@link PropertyPath}.
	 * @throws InvalidPersistentPropertyPath in case not all of the segments of the given {@link PropertyPath} can be
	 *           resolved.
	 */
	PersistentPropertyPath<P> getPersistentPropertyPath(PropertyPath propertyPath) throws InvalidPersistentPropertyPath;

	
Returns all PersistentPropertys for the given dot path notation based on the given type. 
Params:
propertyPath – must not be null.
type – must not be null.
Throws:
InvalidPersistentPropertyPath – in case not all of the segments of the given property path can be resolved.
Returns:
the PersistentPropertyPath representing the given property path on the given type./**
	 * Returns all {@link PersistentProperty}s for the given dot path notation based on the given type.
	 *
	 * @param propertyPath must not be {@literal null}.
	 * @param type must not be {@literal null}.
	 * @return the {@link PersistentPropertyPath} representing the given property path on the given type.
	 * @throws InvalidPersistentPropertyPath in case not all of the segments of the given property path can be resolved.
	 */
	PersistentPropertyPath<P> getPersistentPropertyPath(String propertyPath, Class<?> type)
			throws InvalidPersistentPropertyPath;

	
Returns all PersistentPropertyPaths pointing to properties on the given type that match the given Predicate. In case of circular references the detection will stop at the property that references a type that's already included in the path. Note, that is is a potentially expensive operation as results cannot be cached. 
Params:
type – must not be null.
predicate – must not be null.
Returns:
Since:
2.1/**
	 * Returns all {@link PersistentPropertyPath}s pointing to properties on the given type that match the given
	 * {@link Predicate}. In case of circular references the detection will stop at the property that references a type
	 * that's already included in the path. Note, that is is a potentially expensive operation as results cannot be
	 * cached.
	 *
	 * @param type must not be {@literal null}.
	 * @param predicate must not be {@literal null}.
	 * @return
	 * @since 2.1
	 */
	<T> PersistentPropertyPaths<T, P> findPersistentPropertyPaths(Class<T> type, Predicate<? super P> predicate);

	
Returns the TypeInformations for all PersistentEntitys in the MappingContext. 
Returns:
all TypeInformations for the PersistentEntitys in the MappingContext.
Since:
1.8/**
	 * Returns the {@link TypeInformation}s for all {@link PersistentEntity}s in the {@link MappingContext}.
	 *
	 * @return all {@link TypeInformation}s for the {@link PersistentEntity}s in the {@link MappingContext}.
	 * @since 1.8
	 */
	Collection<TypeInformation<?>> getManagedTypes();
}