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