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