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 }