1 /*******************************************************************************
2 * Copyright (c) 2010, 2013 Sonatype, Inc.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
9 * Sonatype, Inc. - initial API and implementation
10 *******************************************************************************/
11 package org
.eclipse
.aether
.graph
;
13 import java
.util
.Collection
;
14 import java
.util
.List
;
17 import org
.eclipse
.aether
.artifact
.Artifact
;
18 import org
.eclipse
.aether
.repository
.RemoteRepository
;
19 import org
.eclipse
.aether
.version
.Version
;
20 import org
.eclipse
.aether
.version
.VersionConstraint
;
23 * A node within a dependency graph. To conserve memory, dependency graphs may reuse a given node instance multiple
24 * times to represent reoccurring dependencies. As such clients traversing a dependency graph should be prepared to
25 * discover multiple paths leading to the same node instance unless the input graph is known to be a duplicate-free
26 * tree. <em>Note:</em> Unless otherwise noted, implementation classes are not thread-safe and dependency nodes should
27 * not be mutated by concurrent threads.
29 * @noimplement This interface is not intended to be implemented by clients.
30 * @noextend This interface is not intended to be extended by clients.
32 public interface DependencyNode
36 * A bit flag indicating the dependency version was subject to dependency management
38 * @see #getManagedBits()
40 int MANAGED_VERSION
= 0x01;
43 * A bit flag indicating the dependency scope was subject to dependency management
45 * @see #getManagedBits()
47 int MANAGED_SCOPE
= 0x02;
50 * A bit flag indicating the optional flag was subject to dependency management
52 * @see #getManagedBits()
54 int MANAGED_OPTIONAL
= 0x04;
57 * A bit flag indicating the artifact properties were subject to dependency management
59 * @see #getManagedBits()
61 int MANAGED_PROPERTIES
= 0x08;
64 * A bit flag indicating the exclusions were subject to dependency management
66 * @see #getManagedBits()
68 int MANAGED_EXCLUSIONS
= 0x10;
71 * Gets the child nodes of this node. To conserve memory, dependency nodes with equal dependencies may share the
72 * same child list instance. Hence clients mutating the child list need to be aware that these changes might affect
73 * more than this node. Where this is not desired, the child list should be copied before mutation if the client
74 * cannot be sure whether it might be shared with other nodes in the graph.
76 * @return The child nodes of this node, never {@code null}.
78 List
<DependencyNode
> getChildren();
81 * Sets the child nodes of this node.
83 * @param children The child nodes, may be {@code null}
85 void setChildren( List
<DependencyNode
> children
);
88 * Gets the dependency associated with this node. <em>Note:</em> For dependency graphs that have been constructed
89 * without a root dependency, this method will yield {@code null} when invoked on the graph's root node. The root
90 * node of such graphs may however still have a label as returned by {@link #getArtifact()}.
92 * @return The dependency or {@code null} if none.
94 Dependency
getDependency();
97 * Gets the artifact associated with this node. If this node is associated with a dependency, this is equivalent to
98 * {@code getDependency().getArtifact()}. Otherwise the artifact merely provides a label for this node in which case
99 * the artifact must not be subjected to dependency collection/resolution.
101 * @return The associated artifact or {@code null} if none.
103 Artifact
getArtifact();
106 * Updates the artifact of the dependency after resolution. The new artifact must have the same coordinates as the
107 * original artifact. This method may only be invoked if this node actually has a dependency, i.e. if
108 * {@link #getDependency()} is not null.
110 * @param artifact The artifact satisfying the dependency, must not be {@code null}.
112 void setArtifact( Artifact artifact
);
115 * Gets the sequence of relocations that was followed to resolve the artifact referenced by the dependency.
117 * @return The (read-only) sequence of relocations, never {@code null}.
119 List
<?
extends Artifact
> getRelocations();
122 * Gets the known aliases for this dependency's artifact. An alias can be used to mark a patched rebuild of some
123 * other artifact as such, thereby allowing conflict resolution to consider the patched and the original artifact as
126 * @return The (read-only) set of known aliases, never {@code null}.
128 Collection
<?
extends Artifact
> getAliases();
131 * Gets the version constraint that was parsed from the dependency's version declaration.
133 * @return The version constraint for this node or {@code null}.
135 VersionConstraint
getVersionConstraint();
138 * Gets the version that was selected for the dependency's target artifact.
140 * @return The parsed version or {@code null}.
142 Version
getVersion();
145 * Sets the scope of the dependency. This method may only be invoked if this node actually has a dependency, i.e. if
146 * {@link #getDependency()} is not null.
148 * @param scope The scope, may be {@code null}.
150 void setScope( String scope
);
153 * Sets the optional flag of the dependency. This method may only be invoked if this node actually has a dependency,
154 * i.e. if {@link #getDependency()} is not null.
156 * @param optional The optional flag, may be {@code null}.
158 void setOptional( Boolean optional
);
161 * Gets a bit field indicating which attributes of this node were subject to dependency management.
163 * @return A bit field containing any of the bits {@link #MANAGED_VERSION}, {@link #MANAGED_SCOPE},
164 * {@link #MANAGED_OPTIONAL}, {@link #MANAGED_PROPERTIES} and {@link #MANAGED_EXCLUSIONS} if the
165 * corresponding attribute was set via dependency management.
167 int getManagedBits();
170 * Gets the remote repositories from which this node's artifact shall be resolved.
172 * @return The (read-only) list of remote repositories to use for artifact resolution, never {@code null}.
174 List
<RemoteRepository
> getRepositories();
177 * Gets the request context in which this dependency node was created.
179 * @return The request context, never {@code null}.
181 String
getRequestContext();
184 * Sets the request context in which this dependency node was created.
186 * @param context The context, may be {@code null}.
188 void setRequestContext( String context
);
191 * Gets the custom data associated with this dependency node. Clients of the repository system can use this data to
192 * annotate dependency nodes with domain-specific information. Note that the returned map is read-only and
193 * {@link #setData(Object, Object)} needs to be used to update the custom data.
195 * @return The (read-only) key-value mappings, never {@code null}.
200 * Sets the custom data associated with this dependency node.
202 * @param data The new custom data, may be {@code null}.
204 void setData( Map
<Object
, Object
> data
);
207 * Associates the specified dependency node data with the given key. <em>Note:</em> This method must not be called
208 * while {@link #getData()} is being iterated.
210 * @param key The key under which to store the data, must not be {@code null}.
211 * @param value The data to associate with the key, may be {@code null} to remove the mapping.
213 void setData( Object key
, Object value
);
216 * Traverses this node and potentially its children using the specified visitor.
218 * @param visitor The visitor to call back, must not be {@code null}.
219 * @return {@code true} to visit siblings nodes of this node as well, {@code false} to skip siblings.
221 boolean accept( DependencyVisitor visitor
);