1 /******************************************************************************* 2 * Copyright (c) 2013, 2014 Sonatype, Inc. 3 * All rights reserved. This program and the accompanying materials 4 * are made available under the terms of the Eclipse Public License v1.0 5 * which accompanies this distribution, and is available at 6 * http://www.eclipse.org/legal/epl-v10.html 7 * 8 * Contributors: 9 * Sonatype, Inc. - initial API and implementation 10 *******************************************************************************/ 11 package org.eclipse.aether.collection; 12 13 import java.util.Iterator; 14 import java.util.List; 15 16 import org.eclipse.aether.RepositoryException; 17 import org.eclipse.aether.RepositorySystemSession; 18 import org.eclipse.aether.graph.Dependency; 19 import org.eclipse.aether.repository.ArtifactRepository; 20 import org.eclipse.aether.repository.RemoteRepository; 21 import org.eclipse.aether.version.Version; 22 import org.eclipse.aether.version.VersionConstraint; 23 24 /** 25 * Decides which versions matching a version range should actually be considered for the dependency graph. The version 26 * filter is not invoked for dependencies that do not declare a version range but a single version. 27 * <p> 28 * <strong>Note:</strong> Implementations must be stateless. 29 * <p> 30 * <em>Warning:</em> This hook is called from a hot spot and therefore implementations should pay attention to 31 * performance. Among others, implementations should provide a semantic {@link Object#equals(Object) equals()} method. 32 * 33 * @see org.eclipse.aether.RepositorySystemSession#getVersionFilter() 34 * @see org.eclipse.aether.RepositorySystem#collectDependencies(org.eclipse.aether.RepositorySystemSession, 35 * CollectRequest) 36 */ 37 public interface VersionFilter 38 { 39 40 /** 41 * A context used during version filtering to hold relevant data. 42 * 43 * @noimplement This interface is not intended to be implemented by clients. 44 * @noextend This interface is not intended to be extended by clients. 45 */ 46 interface VersionFilterContext 47 extends Iterable<Version> 48 { 49 50 /** 51 * Gets the repository system session during which the version filtering happens. 52 * 53 * @return The repository system session, never {@code null}. 54 */ 55 RepositorySystemSession getSession(); 56 57 /** 58 * Gets the dependency whose version range is being filtered. 59 * 60 * @return The dependency, never {@code null}. 61 */ 62 Dependency getDependency(); 63 64 /** 65 * Gets the total number of available versions. This count reflects any removals made during version filtering. 66 * 67 * @return The total number of available versions. 68 */ 69 int getCount(); 70 71 /** 72 * Gets an iterator over the available versions of the dependency. The iterator returns versions in ascending 73 * order. Use {@link Iterator#remove()} to exclude a version from further consideration in the dependency graph. 74 * 75 * @return The iterator of available versions, never {@code null}. 76 */ 77 Iterator<Version> iterator(); 78 79 /** 80 * Gets the version constraint that was parsed from the dependency's version string. 81 * 82 * @return The parsed version constraint, never {@code null}. 83 */ 84 VersionConstraint getVersionConstraint(); 85 86 /** 87 * Gets the repository from which the specified version was resolved. 88 * 89 * @param version The version whose source repository should be retrieved, must not be {@code null}. 90 * @return The repository from which the version was resolved or {@code null} if unknown. 91 */ 92 ArtifactRepository getRepository( Version version ); 93 94 /** 95 * Gets the remote repositories from which the versions were resolved. 96 * 97 * @return The (read-only) list of repositories, never {@code null}. 98 */ 99 List<RemoteRepository> getRepositories(); 100 101 } 102 103 /** 104 * Filters the available versions for a given dependency. Implementations will usually call 105 * {@link VersionFilterContext#iterator() context.iterator()} to inspect the available versions and use 106 * {@link java.util.Iterator#remove()} to delete unacceptable versions. If no versions remain after all filtering 107 * has been performed, the dependency collection process will automatically fail, i.e. implementations need not 108 * handle this situation on their own. 109 * 110 * @param context The version filter context, must not be {@code null}. 111 * @throws RepositoryException If the filtering could not be performed. 112 */ 113 void filterVersions( VersionFilterContext context ) 114 throws RepositoryException; 115 116 /** 117 * Derives a version filter for the specified collection context. The derived filter will be used to handle version 118 * ranges encountered in child dependencies of the current node. When calculating the child filter, implementors are 119 * strongly advised to simply return the current instance if nothing changed to help save memory. 120 * 121 * @param context The dependency collection context, must not be {@code null}. 122 * @return The version filter for the target node or {@code null} if versions should not be filtered any more. 123 */ 124 VersionFilter deriveChildFilter( DependencyCollectionContext context ); 125 126 }