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.graph;
20
21 import java.util.Collection;
22 import java.util.List;
23 import java.util.Map;
24
25 import org.eclipse.aether.artifact.Artifact;
26 import org.eclipse.aether.repository.RemoteRepository;
27 import org.eclipse.aether.version.Version;
28 import org.eclipse.aether.version.VersionConstraint;
29
30 /**
31 * A node within a dependency graph. To conserve memory, dependency graphs may reuse a given node instance multiple
32 * times to represent reoccurring dependencies. As such clients traversing a dependency graph should be prepared to
33 * discover multiple paths leading to the same node instance unless the input graph is known to be a duplicate-free
34 * tree. <em>Note:</em> Unless otherwise noted, implementation classes are not thread-safe and dependency nodes should
35 * not be mutated by concurrent threads.
36 *
37 * @noimplement This interface is not intended to be implemented by clients.
38 * @noextend This interface is not intended to be extended by clients.
39 */
40 public interface DependencyNode {
41
42 /**
43 * A bit flag indicating the dependency version was subject to dependency management
44 *
45 * @see #getManagedBits()
46 */
47 int MANAGED_VERSION = 0x01;
48
49 /**
50 * A bit flag indicating the dependency scope was subject to dependency management
51 *
52 * @see #getManagedBits()
53 */
54 int MANAGED_SCOPE = 0x02;
55
56 /**
57 * A bit flag indicating the optional flag was subject to dependency management
58 *
59 * @see #getManagedBits()
60 */
61 int MANAGED_OPTIONAL = 0x04;
62
63 /**
64 * A bit flag indicating the artifact properties were subject to dependency management
65 *
66 * @see #getManagedBits()
67 */
68 int MANAGED_PROPERTIES = 0x08;
69
70 /**
71 * A bit flag indicating the exclusions were subject to dependency management
72 *
73 * @see #getManagedBits()
74 */
75 int MANAGED_EXCLUSIONS = 0x10;
76
77 /**
78 * Gets the child nodes of this node. To conserve memory, dependency nodes with equal dependencies may share the
79 * same child list instance. Hence clients mutating the child list need to be aware that these changes might affect
80 * more than this node. Where this is not desired, the child list should be copied before mutation if the client
81 * cannot be sure whether it might be shared with other nodes in the graph.
82 *
83 * @return The child nodes of this node, never {@code null}.
84 */
85 List<DependencyNode> getChildren();
86
87 /**
88 * Sets the child nodes of this node.
89 *
90 * @param children The child nodes, may be {@code null}
91 */
92 void setChildren(List<DependencyNode> children);
93
94 /**
95 * Gets the dependency associated with this node. <em>Note:</em> For dependency graphs that have been constructed
96 * without a root dependency, this method will yield {@code null} when invoked on the graph's root node. The root
97 * node of such graphs may however still have a label as returned by {@link #getArtifact()}.
98 *
99 * @return The dependency or {@code null} if none.
100 */
101 Dependency getDependency();
102
103 /**
104 * Gets the artifact associated with this node. If this node is associated with a dependency, this is equivalent to
105 * {@code getDependency().getArtifact()}. Otherwise, the artifact merely provides a label for this node in which case
106 * the artifact must not be subjected to dependency collection/resolution.
107 *
108 * @return The associated artifact or {@code null} if none.
109 */
110 Artifact getArtifact();
111
112 /**
113 * Updates the artifact of the dependency after resolution. The new artifact must have the same coordinates as the
114 * original artifact. This method may only be invoked if this node actually has a dependency, i.e. if
115 * {@link #getDependency()} is not null.
116 *
117 * @param artifact The artifact satisfying the dependency, must not be {@code null}.
118 */
119 void setArtifact(Artifact artifact);
120
121 /**
122 * Gets the sequence of relocations that was followed to resolve the artifact referenced by the dependency.
123 *
124 * @return The (read-only) sequence of relocations, never {@code null}.
125 */
126 List<? extends Artifact> getRelocations();
127
128 /**
129 * Gets the known aliases for this dependency's artifact. An alias can be used to mark a patched rebuild of some
130 * other artifact as such, thereby allowing conflict resolution to consider the patched and the original artifact as
131 * a conflict.
132 *
133 * @return The (read-only) set of known aliases, never {@code null}.
134 */
135 Collection<? extends Artifact> getAliases();
136
137 /**
138 * Gets the version constraint that was parsed from the dependency's version declaration.
139 *
140 * @return The version constraint for this node or {@code null}.
141 */
142 VersionConstraint getVersionConstraint();
143
144 /**
145 * Gets the version that was selected for the dependency's target artifact.
146 *
147 * @return The parsed version or {@code null}.
148 */
149 Version getVersion();
150
151 /**
152 * Sets the scope of the dependency. This method may only be invoked if this node actually has a dependency, i.e. if
153 * {@link #getDependency()} is not null.
154 *
155 * @param scope The scope, may be {@code null}.
156 */
157 void setScope(String scope);
158
159 /**
160 * Sets the optional flag of the dependency. This method may only be invoked if this node actually has a dependency,
161 * i.e. if {@link #getDependency()} is not null.
162 *
163 * @param optional The optional flag, may be {@code null}.
164 */
165 void setOptional(Boolean optional);
166
167 /**
168 * Gets a bit field indicating which attributes of this node were subject to dependency management.
169 *
170 * @return A bit field containing any of the bits {@link #MANAGED_VERSION}, {@link #MANAGED_SCOPE},
171 * {@link #MANAGED_OPTIONAL}, {@link #MANAGED_PROPERTIES} and {@link #MANAGED_EXCLUSIONS} if the
172 * corresponding attribute was set via dependency management.
173 */
174 int getManagedBits();
175
176 /**
177 * Gets the remote repositories from which this node's artifact shall be resolved.
178 *
179 * @return The (read-only) list of remote repositories to use for artifact resolution, never {@code null}.
180 */
181 List<RemoteRepository> getRepositories();
182
183 /**
184 * Gets the request context in which this dependency node was created.
185 *
186 * @return The request context, never {@code null}.
187 */
188 String getRequestContext();
189
190 /**
191 * Sets the request context in which this dependency node was created.
192 *
193 * @param context The context, may be {@code null}.
194 */
195 void setRequestContext(String context);
196
197 /**
198 * Gets the custom data associated with this dependency node. Clients of the repository system can use this data to
199 * annotate dependency nodes with domain-specific information. Note that the returned map is read-only and
200 * {@link #setData(Object, Object)} needs to be used to update the custom data.
201 *
202 * @return The (read-only) key-value mappings, never {@code null}.
203 */
204 Map<?, ?> getData();
205
206 /**
207 * Sets the custom data associated with this dependency node.
208 *
209 * @param data The new custom data, may be {@code null}.
210 */
211 void setData(Map<Object, Object> data);
212
213 /**
214 * Associates the specified dependency node data with the given key. <em>Note:</em> This method must not be called
215 * while {@link #getData()} is being iterated.
216 *
217 * @param key The key under which to store the data, must not be {@code null}.
218 * @param value The data to associate with the key, may be {@code null} to remove the mapping.
219 */
220 void setData(Object key, Object value);
221
222 /**
223 * Traverses this node and potentially its children using the specified visitor.
224 *
225 * @param visitor The visitor to call back, must not be {@code null}.
226 * @return {@code true} to visit siblings nodes of this node as well, {@code false} to skip siblings.
227 */
228 boolean accept(DependencyVisitor visitor);
229 }