/*
 * 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 org.springframework.core.convert.converter.Converter;
import org.springframework.data.util.Streamable;
import org.springframework.lang.Nullable;

Abstraction of a path of PersistentPropertys. 
Author:
Oliver Gierke/**
 * Abstraction of a path of {@link PersistentProperty}s.
 *
 * @author Oliver Gierke
 */
public interface PersistentPropertyPath<P extends PersistentProperty<P>> extends Streamable<P> {

	
Returns the dot based path notation using PersistentProperty.getName(). 
Returns:
/**
	 * Returns the dot based path notation using {@link PersistentProperty#getName()}.
	 *
	 * @return
	 */
	@Nullable
	String toDotPath();

	
Returns the dot based path notation using the given Converter to translate individual PersistentPropertys to path segments. 
Params:
converter – must not be null.
Returns:
/**
	 * Returns the dot based path notation using the given {@link Converter} to translate individual
	 * {@link PersistentProperty}s to path segments.
	 *
	 * @param converter must not be {@literal null}.
	 * @return
	 */
	@Nullable
	String toDotPath(Converter<? super P, String> converter);

	
Returns a String path with the given delimiter based on the PersistentProperty.getName(). 
Params:
delimiter – must not be null.
Returns:
/**
	 * Returns a {@link String} path with the given delimiter based on the {@link PersistentProperty#getName()}.
	 *
	 * @param delimiter must not be {@literal null}.
	 * @return
	 */
	@Nullable
	String toPath(String delimiter);

	
Returns a String path with the given delimiter using the given Converter for PersistentProperty to String conversion. 
Params:
delimiter – must not be null.
converter – must not be null.
Returns:
/**
	 * Returns a {@link String} path with the given delimiter using the given {@link Converter} for
	 * {@link PersistentProperty} to String conversion.
	 *
	 * @param delimiter must not be {@literal null}.
	 * @param converter must not be {@literal null}.
	 * @return
	 */
	@Nullable
	String toPath(String delimiter, Converter<? super P, String> converter);

	
Returns the last property in the PersistentPropertyPath. So for foo.bar it will return the PersistentProperty for bar. For a simple foo it returns PersistentProperty for foo. 
Returns:
/**
	 * Returns the last property in the {@link PersistentPropertyPath}. So for {@code foo.bar} it will return the
	 * {@link PersistentProperty} for {@code bar}. For a simple {@code foo} it returns {@link PersistentProperty} for
	 * {@code foo}.
	 *
	 * @return
	 */
	@Nullable
	P getLeafProperty();

	default P getRequiredLeafProperty() {

		P property = getLeafProperty();

		if (property == null) {
			throw new IllegalStateException("No leaf property found!");
		}

		return property;
	}

	
Returns the first property in the PersistentPropertyPath. So for foo.bar it will return the PersistentProperty for foo. For a simple foo it returns PersistentProperty for foo. 
Returns:
/**
	 * Returns the first property in the {@link PersistentPropertyPath}. So for {@code foo.bar} it will return the
	 * {@link PersistentProperty} for {@code foo}. For a simple {@code foo} it returns {@link PersistentProperty} for
	 * {@code foo}.
	 *
	 * @return
	 */
	@Nullable
	P getBaseProperty();

	
Returns whether the given PersistentPropertyPath is a base path of the current one. This means that the current PersistentPropertyPath is basically an extension of the given one. 
Params:
path – must not be null.
Returns:
/**
	 * Returns whether the given {@link PersistentPropertyPath} is a base path of the current one. This means that the
	 * current {@link PersistentPropertyPath} is basically an extension of the given one.
	 *
	 * @param path must not be {@literal null}.
	 * @return
	 */
	boolean isBasePathOf(PersistentPropertyPath<P> path);

	
Returns the sub-path of the current one as if it was based on the given base path. So for a current path foo.bar and a given base foo it would return bar. If the given path is not a base of the the current one the current PersistentPropertyPath will be returned as is. 
Params:
base – must not be null.
Returns:
/**
	 * Returns the sub-path of the current one as if it was based on the given base path. So for a current path
	 * {@code foo.bar} and a given base {@code foo} it would return {@code bar}. If the given path is not a base of the
	 * the current one the current {@link PersistentPropertyPath} will be returned as is.
	 *
	 * @param base must not be {@literal null}.
	 * @return
	 */
	PersistentPropertyPath<P> getExtensionForBaseOf(PersistentPropertyPath<P> base);

	
Returns the parent path of the current PersistentPropertyPath, i.e. the path without the leaf property. This happens up to the base property. So for a direct property reference calling this method will result in returning the property. 
Returns:
/**
	 * Returns the parent path of the current {@link PersistentPropertyPath}, i.e. the path without the leaf property.
	 * This happens up to the base property. So for a direct property reference calling this method will result in
	 * returning the property.
	 *
	 * @return
	 */
	PersistentPropertyPath<P> getParentPath();

	
Returns the length of the PersistentPropertyPath. 
Returns:
/**
	 * Returns the length of the {@link PersistentPropertyPath}.
	 *
	 * @return
	 */
	int getLength();
}