/*
* Copyright 2015 Lukas Krejci
*
* 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
*
* http://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.revapi;
import java.util.List;
import java.util.SortedSet;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import org.revapi.query.Filter;
/**
* A representation of some "unit" understood by an API analyzer. Typically an abstract syntax tree of a language.
*
* @author Lukas Krejci
* @since 0.1
*/
public interface ElementForest {
/**
* @return the API this forest represents
*/
@Nonnull
API getApi();
/**
* A sorted set of all root elements of the forest. The set uses the natural order of the element implementations.
*
* @return the roots elements of the forest.
*/
@Nonnull
SortedSet<? extends Element> getRoots();
/**
* Searches through the forest for elements of given type, potentially further filtering.
*
* <p>If the {@code searchRoot} is not null, this is technically equivalent to calling the
* {@link Element#searchChildren(java.lang.Class, boolean, org.revapi.query.Filter)} on the
* {@code searchRoot}.
*
* @param <T> the type of the elements to look for
* @param resultType the type of the elements to be contained in the results
* @param recurse false to only search direct children, true for searching recursively
* @param filter the optional filter
* @param searchRoot optional element from which to conduct the search
*
* @return a list of elements of given type (or any subtype) from the forest, filtered by the filter if provided
*/
@Nonnull
<T extends Element> List<T> search(@Nonnull Class<T> resultType, boolean recurse,
@Nullable Filter<? super T> filter,
@Nullable Element searchRoot);
}