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 }