/*
 * 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;

import java.lang.annotation.Annotation;
import java.util.Iterator;

import org.springframework.data.annotation.Immutable;
import org.springframework.data.convert.EntityInstantiator;
import org.springframework.data.util.TypeInformation;
import org.springframework.lang.Nullable;

Represents a persistent entity.
Author:
Oliver Gierke, Graeme Rocher, Jon Brisbin, Patryk Wasik, Mark Paluch, Christoph Strobl/**
 * Represents a persistent entity.
 *
 * @author Oliver Gierke
 * @author Graeme Rocher
 * @author Jon Brisbin
 * @author Patryk Wasik
 * @author Mark Paluch
 * @author Christoph Strobl
 */
public interface PersistentEntity<T, P extends PersistentProperty<P>> extends Iterable<P> {

	
The entity name including any package prefix.
Returns:
must never return null./**
	 * The entity name including any package prefix.
	 *
	 * @return must never return {@literal null}.
	 */
	String getName();

	
Returns the PreferredConstructor to be used to instantiate objects of this PersistentEntity. 
Returns:
null in case no suitable constructor for automatic construction can be found. This usually indicates that the instantiation of the object of that persistent entity is done through either a customer EntityInstantiator or handled by custom conversion mechanisms entirely./**
	 * Returns the {@link PreferredConstructor} to be used to instantiate objects of this {@link PersistentEntity}.
	 *
	 * @return {@literal null} in case no suitable constructor for automatic construction can be found. This usually
	 *         indicates that the instantiation of the object of that persistent entity is done through either a customer
	 *         {@link EntityInstantiator} or handled by custom conversion mechanisms entirely.
	 */
	@Nullable
	PreferredConstructor<T, P> getPersistenceConstructor();

	
Returns whether the given PersistentProperty is referred to by a constructor argument of the PersistentEntity. 
Params:
property – can be null.
Returns:
true if the given PersistentProperty is referred to by a constructor argument or false if not or null./**
	 * Returns whether the given {@link PersistentProperty} is referred to by a constructor argument of the
	 * {@link PersistentEntity}.
	 *
	 * @param property can be {@literal null}.
	 * @return true if the given {@link PersistentProperty} is referred to by a constructor argument or {@literal false}
	 *         if not or {@literal null}.
	 */
	boolean isConstructorArgument(PersistentProperty<?> property);

	
Returns whether the given PersistentProperty is the id property of the entity. 
Params:
property – can be null.
Returns:
true given property is the entities id./**
	 * Returns whether the given {@link PersistentProperty} is the id property of the entity.
	 *
	 * @param property can be {@literal null}.
	 * @return {@literal true} given property is the entities id.
	 */
	boolean isIdProperty(PersistentProperty<?> property);

	
Returns whether the given PersistentProperty is the version property of the entity. 
Params:
property – can be null.
Returns:
true given property is used as version./**
	 * Returns whether the given {@link PersistentProperty} is the version property of the entity.
	 *
	 * @param property can be {@literal null}.
	 * @return {@literal true} given property is used as version.
	 */
	boolean isVersionProperty(PersistentProperty<?> property);

	
Returns the id property of the PersistentEntity. Can be null in case this is an entity completely handled by a custom conversion. 
Returns:
the id property of the PersistentEntity./**
	 * Returns the id property of the {@link PersistentEntity}. Can be {@literal null} in case this is an entity
	 * completely handled by a custom conversion.
	 *
	 * @return the id property of the {@link PersistentEntity}.
	 */
	@Nullable
	P getIdProperty();

	
Returns the id property of the PersistentEntity. 
Throws:
IllegalStateException – if PersistentEntity does not define an id property.
Returns:
the id property of the PersistentEntity.
Since:
2.0/**
	 * Returns the id property of the {@link PersistentEntity}.
	 *
	 * @return the id property of the {@link PersistentEntity}.
	 * @throws IllegalStateException if {@link PersistentEntity} does not define an {@literal id} property.
	 * @since 2.0
	 */
	default P getRequiredIdProperty() {

		P property = getIdProperty();

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

		throw new IllegalStateException(String.format("Required identifier property not found for %s!", getType()));
	}

	
Returns the version property of the PersistentEntity. Can be null in case no version property is available on the entity. 
Returns:
the version property of the PersistentEntity./**
	 * Returns the version property of the {@link PersistentEntity}. Can be {@literal null} in case no version property is
	 * available on the entity.
	 *
	 * @return the version property of the {@link PersistentEntity}.
	 */
	@Nullable
	P getVersionProperty();

	
Returns the version property of the PersistentEntity. Can be null in case no version property is available on the entity. 
Throws:
IllegalStateException – if PersistentEntity does not define a version property.
Returns:
the version property of the PersistentEntity.
Since:
2.0/**
	 * Returns the version property of the {@link PersistentEntity}. Can be {@literal null} in case no version property is
	 * available on the entity.
	 *
	 * @return the version property of the {@link PersistentEntity}.
	 * @throws IllegalStateException if {@link PersistentEntity} does not define a {@literal version} property.
	 * @since 2.0
	 */
	default P getRequiredVersionProperty() {

		P property = getVersionProperty();

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

		throw new IllegalStateException(String.format("Required version property not found for %s!", getType()));
	}

	
Obtains a PersistentProperty instance by name. 
Params:
name – The name of the property. Can be null.
Returns:
the PersistentProperty or null if it doesn't exist./**
	 * Obtains a {@link PersistentProperty} instance by name.
	 *
	 * @param name The name of the property. Can be {@literal null}.
	 * @return the {@link PersistentProperty} or {@literal null} if it doesn't exist.
	 */
	@Nullable
	P getPersistentProperty(String name);

	
Returns the PersistentProperty with the given name. 
Params:
name – the name of the property. Can be null or empty.
Throws:
IllegalStateException – in case no property with the given name exists.
Returns:
the PersistentProperty with the given name./**
	 * Returns the {@link PersistentProperty} with the given name.
	 *
	 * @param name the name of the property. Can be {@literal null} or empty.
	 * @return the {@link PersistentProperty} with the given name.
	 * @throws IllegalStateException in case no property with the given name exists.
	 */
	default P getRequiredPersistentProperty(String name) {

		P property = getPersistentProperty(name);

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

		throw new IllegalStateException(String.format("Required property %s not found for %s!", name, getType()));
	}

	
Returns the first property equipped with an Annotation of the given type. 
Params:
annotationType – must not be null.
Returns:
null if no property found with given annotation type.
Since:
1.8/**
	 * Returns the first property equipped with an {@link Annotation} of the given type.
	 *
	 * @param annotationType must not be {@literal null}.
	 * @return {@literal null} if no property found with given annotation type.
	 * @since 1.8
	 */
	@Nullable
	default P getPersistentProperty(Class<? extends Annotation> annotationType) {

		Iterator<P> it = getPersistentProperties(annotationType).iterator();
		return it.hasNext() ? it.next() : null;
	}

	
Returns all properties equipped with an Annotation of the given type. 
Params:
annotationType – must not be null.
Returns:
empty Iterator if no match found. Never null.
Since:
2.0/**
	 * Returns all properties equipped with an {@link Annotation} of the given type.
	 *
	 * @param annotationType must not be {@literal null}.
	 * @return {@literal empty} {@link Iterator} if no match found. Never {@literal null}.
	 * @since 2.0
	 */
	Iterable<P> getPersistentProperties(Class<? extends Annotation> annotationType);

	
Returns whether the PersistentEntity has an id property. If this call returns true, getIdProperty() will return a non-null value. 
Returns:
true if entity has an id property./**
	 * Returns whether the {@link PersistentEntity} has an id property. If this call returns {@literal true},
	 * {@link #getIdProperty()} will return a non-{@literal null} value.
	 *
	 * @return {@literal true} if entity has an {@literal id} property.
	 */
	boolean hasIdProperty();

	
Returns whether the PersistentEntity has a version property. If this call returns true, getVersionProperty() will return a non-null value. 
Returns:
true if entity has a version property./**
	 * Returns whether the {@link PersistentEntity} has a version property. If this call returns {@literal true},
	 * {@link #getVersionProperty()} will return a non-{@literal null} value.
	 *
	 * @return {@literal true} if entity has a {@literal version} property.
	 */
	boolean hasVersionProperty();

	
Returns the resolved Java type of this entity.
Returns:
The underlying Java class for this entity. Never null./**
	 * Returns the resolved Java type of this entity.
	 *
	 * @return The underlying Java class for this entity. Never {@literal null}.
	 */
	Class<T> getType();

	
Returns the alias to be used when storing type information. Might be null to indicate that there was no alias defined through the mapping metadata. 
Returns:
/**
	 * Returns the alias to be used when storing type information. Might be {@literal null} to indicate that there was no
	 * alias defined through the mapping metadata.
	 *
	 * @return
	 */
	Alias getTypeAlias();

	
Returns the TypeInformation backing this PersistentEntity. 
Returns:
/**
	 * Returns the {@link TypeInformation} backing this {@link PersistentEntity}.
	 *
	 * @return
	 */
	TypeInformation<T> getTypeInformation();

	
Applies the given PropertyHandler to all PersistentPropertys contained in this PersistentEntity. 
Params:
handler – must not be null./**
	 * Applies the given {@link PropertyHandler} to all {@link PersistentProperty}s contained in this
	 * {@link PersistentEntity}.
	 *
	 * @param handler must not be {@literal null}.
	 */
	void doWithProperties(PropertyHandler<P> handler);

	void doWithProperties(SimplePropertyHandler handler);

	
Applies the given AssociationHandler to all Association contained in this PersistentEntity. 
Params:
handler – must not be null./**
	 * Applies the given {@link AssociationHandler} to all {@link Association} contained in this {@link PersistentEntity}.
	 *
	 * @param handler must not be {@literal null}.
	 */
	void doWithAssociations(AssociationHandler<P> handler);

	void doWithAssociations(SimpleAssociationHandler handler);

	
Looks up the annotation of the given type on the PersistentEntity. 
Params:
annotationType – must not be null.
Returns:
null if not found.
Since:
1.8/**
	 * Looks up the annotation of the given type on the {@link PersistentEntity}.
	 *
	 * @param annotationType must not be {@literal null}.
	 * @return {@literal null} if not found.
	 * @since 1.8
	 */
	@Nullable
	<A extends Annotation> A findAnnotation(Class<A> annotationType);

	
Returns the required annotation of the given type on the PersistentEntity. 
Params:
annotationType – must not be null.
Throws:
IllegalStateException – if the required annotationType is not found.
Returns:
the annotation.
Since:
2.0/**
	 * Returns the required annotation of the given type on the {@link PersistentEntity}.
	 *
	 * @param annotationType must not be {@literal null}.
	 * @return the annotation.
	 * @throws IllegalStateException if the required {@code annotationType} is not found.
	 * @since 2.0
	 */
	default <A extends Annotation> A getRequiredAnnotation(Class<A> annotationType) throws IllegalStateException {

		A annotation = findAnnotation(annotationType);

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

		throw new IllegalStateException(
				String.format("Required annotation %s not found for %s!", annotationType, getType()));
	}

	
Checks whether the annotation of the given type is present on the PersistentEntity. 
Params:
annotationType – must not be null.
Returns:
true if Annotation of given type is present.
Since:
2.0/**
	 * Checks whether the annotation of the given type is present on the {@link PersistentEntity}.
	 *
	 * @param annotationType must not be {@literal null}.
	 * @return {@literal true} if {@link Annotation} of given type is present.
	 * @since 2.0
	 */
	<A extends Annotation> boolean isAnnotationPresent(Class<A> annotationType);

	
Returns a PersistentPropertyAccessor to access property values of the given bean. 
Params:
bean – must not be null.
Returns:
new PersistentPropertyAccessor.
Since:
1.10/**
	 * Returns a {@link PersistentPropertyAccessor} to access property values of the given bean.
	 *
	 * @param bean must not be {@literal null}.
	 * @return new {@link PersistentPropertyAccessor}.
	 * @since 1.10
	 */
	<B> PersistentPropertyAccessor<B> getPropertyAccessor(B bean);

	
Returns the IdentifierAccessor for the given bean. 
Params:
bean – must not be null.
Returns:
new IdentifierAccessor.
Since:
1.10/**
	 * Returns the {@link IdentifierAccessor} for the given bean.
	 *
	 * @param bean must not be {@literal null}.
	 * @return new {@link IdentifierAccessor}.
	 * @since 1.10
	 */
	IdentifierAccessor getIdentifierAccessor(Object bean);

	
Returns whether the given bean is considered new according to the static metadata.
Params:
bean – must not be null.
Throws:
IllegalArgumentException – in case the given bean is not an instance of the typ represented by the PersistentEntity.
Returns:
whether the given bean is considered a new instance./**
	 * Returns whether the given bean is considered new according to the static metadata.
	 * 
	 * @param bean must not be {@literal null}.
	 * @throws IllegalArgumentException in case the given bean is not an instance of the typ represented by the
	 *           {@link PersistentEntity}.
	 * @return whether the given bean is considered a new instance.
	 */
	boolean isNew(Object bean);

	
Returns whether the entity is considered immutable, i.e. clients shouldn't attempt to change instances via the PersistentPropertyAccessor obtained via getPropertyAccessor(Object). 
See Also:
Immutable
Returns:
Since:
2.1/**
	 * Returns whether the entity is considered immutable, i.e. clients shouldn't attempt to change instances via the
	 * {@link PersistentPropertyAccessor} obtained via {@link #getPropertyAccessor(Object)}.
	 * 
	 * @return
	 * @see Immutable
	 * @since 2.1
	 */
	boolean isImmutable();

	
Returns whether the entity needs properties to be populated, i.e. if any property exists that's not initialized by
the constructor.
Returns:
Since:
2.1/**
	 * Returns whether the entity needs properties to be populated, i.e. if any property exists that's not initialized by
	 * the constructor.
	 * 
	 * @return
	 * @since 2.1
	 */
	boolean requiresPropertyPopulation();
}