1 package org.eclipse.aether.collection; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import java.util.Iterator; 23 import java.util.List; 24 25 import org.eclipse.aether.RepositoryException; 26 import org.eclipse.aether.RepositorySystemSession; 27 import org.eclipse.aether.graph.Dependency; 28 import org.eclipse.aether.repository.ArtifactRepository; 29 import org.eclipse.aether.repository.RemoteRepository; 30 import org.eclipse.aether.version.Version; 31 import org.eclipse.aether.version.VersionConstraint; 32 33 /** 34 * Decides which versions matching a version range should actually be considered for the dependency graph. The version 35 * filter is not invoked for dependencies that do not declare a version range but a single version. 36 * <p> 37 * <strong>Note:</strong> Implementations must be stateless. 38 * <p> 39 * <em>Warning:</em> This hook is called from a hot spot and therefore implementations should pay attention to 40 * performance. Among others, implementations should provide a semantic {@link Object#equals(Object) equals()} method. 41 * 42 * @see org.eclipse.aether.RepositorySystemSession#getVersionFilter() 43 * @see org.eclipse.aether.RepositorySystem#collectDependencies(org.eclipse.aether.RepositorySystemSession, 44 * CollectRequest) 45 */ 46 public interface VersionFilter 47 { 48 49 /** 50 * A context used during version filtering to hold relevant data. 51 * 52 * @noimplement This interface is not intended to be implemented by clients. 53 * @noextend This interface is not intended to be extended by clients. 54 */ 55 interface VersionFilterContext 56 extends Iterable<Version> 57 { 58 59 /** 60 * Gets the repository system session during which the version filtering happens. 61 * 62 * @return The repository system session, never {@code null}. 63 */ 64 RepositorySystemSession getSession(); 65 66 /** 67 * Gets the dependency whose version range is being filtered. 68 * 69 * @return The dependency, never {@code null}. 70 */ 71 Dependency getDependency(); 72 73 /** 74 * Gets the total number of available versions. This count reflects any removals made during version filtering. 75 * 76 * @return The total number of available versions. 77 */ 78 int getCount(); 79 80 /** 81 * Gets an iterator over the available versions of the dependency. The iterator returns versions in ascending 82 * order. Use {@link Iterator#remove()} to exclude a version from further consideration in the dependency graph. 83 * 84 * @return The iterator of available versions, never {@code null}. 85 */ 86 Iterator<Version> iterator(); 87 88 /** 89 * Gets the version constraint that was parsed from the dependency's version string. 90 * 91 * @return The parsed version constraint, never {@code null}. 92 */ 93 VersionConstraint getVersionConstraint(); 94 95 /** 96 * Gets the repository from which the specified version was resolved. 97 * 98 * @param version The version whose source repository should be retrieved, must not be {@code null}. 99 * @return The repository from which the version was resolved or {@code null} if unknown. 100 */ 101 ArtifactRepository getRepository( Version version ); 102 103 /** 104 * Gets the remote repositories from which the versions were resolved. 105 * 106 * @return The (read-only) list of repositories, never {@code null}. 107 */ 108 List<RemoteRepository> getRepositories(); 109 110 } 111 112 /** 113 * Filters the available versions for a given dependency. Implementations will usually call 114 * {@link VersionFilterContext#iterator() context.iterator()} to inspect the available versions and use 115 * {@link java.util.Iterator#remove()} to delete unacceptable versions. If no versions remain after all filtering 116 * has been performed, the dependency collection process will automatically fail, i.e. implementations need not 117 * handle this situation on their own. 118 * 119 * @param context The version filter context, must not be {@code null}. 120 * @throws RepositoryException If the filtering could not be performed. 121 */ 122 void filterVersions( VersionFilterContext context ) 123 throws RepositoryException; 124 125 /** 126 * Derives a version filter for the specified collection context. The derived filter will be used to handle version 127 * ranges encountered in child dependencies of the current node. When calculating the child filter, implementors are 128 * strongly advised to simply return the current instance if nothing changed to help save memory. 129 * 130 * @param context The dependency collection context, must not be {@code null}. 131 * @return The version filter for the target node or {@code null} if versions should not be filtered any more. 132 */ 133 VersionFilter deriveChildFilter( DependencyCollectionContext context ); 134 135 }