org.semanticweb.elk.util.collections.chains.Chain Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of elk-util-collections Show documentation
ELK Utilities Collections
The newest version!
package org.semanticweb.elk.util.collections.chains;

/*
 * #%L
 * ELK Reasoner
 * $Id:$
 * $HeadURL:$
 * %%
 * Copyright (C) 2011 - 2012 Department of Computer Science, University of Oxford
 * %%
 * 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.
 * #L%
 */

/**
 * A linked list of elements together with helper functions to find, create if
 * not found, and remove elements in the chain.
 * 
 * @author "Yevgeny Kazakov"
 * 
 * @param 
 *            the types of the elements in the chain
 * @see Matcher
 */
public interface Chain> extends ModifiableLink {

	/**
	 * Finds the first element in the chain that satisfies the provided
	 * {@link Matcher}. This function does not modify the chain. If the chain is
	 * modified during calling of this function, the behavior of the function is
	 * not specified.
	 * 
	 * @param 
	 *            the output type of the {@link Matcher}
	 * @param matcher
	 *            the object describing an element to search for
	 * @return the object contained in the chain that satisfies the provided
	 *         {@link Matcher} or {@code null} if no such element is found
	 */
	public  S find(Matcher matcher);

	/**
	 * Finds an element in the chain satisfies the provided {@link Matcher}, or
	 * if no such element is found, creates a new element using the provided
	 * {@link ReferenceFactory} and inserts it into the chain. In the letter
	 * case, the chain is modified.
	 * 
	 * @param 
	 *            the output type of the {@link Matcher}
	 * @param matcher
	 *            the object describing the element to search for
	 * @param factory
	 *            the factory for creating references
	 * @return the object that satisfies the provided {@link Matcher} if found
	 *         in the chain, or the newly created and inserted element object
	 *         otherwise
	 */
	public  S getCreate(Matcher matcher,
			ReferenceFactory factory);

	/**
	 * Removes the first element in the chain that satisfies the provided
	 * {@link Matcher}. If such element is found, the chain is modified.
	 * 
	 * @param 
	 *            the output type of the {@link Matcher}
	 * @param descriptor
	 *            the object describing the element to search for
	 * @return the removed element, if found, or {@code null} if not found
	 */
	public  S remove(Matcher descriptor);

}