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 7 * 8 * Contributors: 9 * Sonatype, Inc. - initial API and implementation 10 *******************************************************************************/ 11 package org.eclipse.aether.graph; 12 13 import java.util.Collection; 14 import java.util.List; 15 import java.util.Map; 16 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; 21 22 /** 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. 28 * 29 * @noimplement This interface is not intended to be implemented by clients. 30 * @noextend This interface is not intended to be extended by clients. 31 */ 32 public interface DependencyNode 33 { 34 35 /** 36 * A bit flag indicating the dependency version was subject to dependency management 37 * 38 * @see #getManagedBits() 39 */ 40 int MANAGED_VERSION = 0x01; 41 42 /** 43 * A bit flag indicating the dependency scope was subject to dependency management 44 * 45 * @see #getManagedBits() 46 */ 47 int MANAGED_SCOPE = 0x02; 48 49 /** 50 * A bit flag indicating the optional flag was subject to dependency management 51 * 52 * @see #getManagedBits() 53 */ 54 int MANAGED_OPTIONAL = 0x04; 55 56 /** 57 * A bit flag indicating the artifact properties were subject to dependency management 58 * 59 * @see #getManagedBits() 60 */ 61 int MANAGED_PROPERTIES = 0x08; 62 63 /** 64 * A bit flag indicating the exclusions were subject to dependency management 65 * 66 * @see #getManagedBits() 67 */ 68 int MANAGED_EXCLUSIONS = 0x10; 69 70 /** 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. 75 * 76 * @return The child nodes of this node, never {@code null}. 77 */ 78 List<DependencyNode> getChildren(); 79 80 /** 81 * Sets the child nodes of this node. 82 * 83 * @param children The child nodes, may be {@code null} 84 */ 85 void setChildren( List<DependencyNode> children ); 86 87 /** 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()}. 91 * 92 * @return The dependency or {@code null} if none. 93 */ 94 Dependency getDependency(); 95 96 /** 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. 100 * 101 * @return The associated artifact or {@code null} if none. 102 */ 103 Artifact getArtifact(); 104 105 /** 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. 109 * 110 * @param artifact The artifact satisfying the dependency, must not be {@code null}. 111 */ 112 void setArtifact( Artifact artifact ); 113 114 /** 115 * Gets the sequence of relocations that was followed to resolve the artifact referenced by the dependency. 116 * 117 * @return The (read-only) sequence of relocations, never {@code null}. 118 */ 119 List<? extends Artifact> getRelocations(); 120 121 /** 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 124 * a conflict. 125 * 126 * @return The (read-only) set of known aliases, never {@code null}. 127 */ 128 Collection<? extends Artifact> getAliases(); 129 130 /** 131 * Gets the version constraint that was parsed from the dependency's version declaration. 132 * 133 * @return The version constraint for this node or {@code null}. 134 */ 135 VersionConstraint getVersionConstraint(); 136 137 /** 138 * Gets the version that was selected for the dependency's target artifact. 139 * 140 * @return The parsed version or {@code null}. 141 */ 142 Version getVersion(); 143 144 /** 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. 147 * 148 * @param scope The scope, may be {@code null}. 149 */ 150 void setScope( String scope ); 151 152 /** 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. 155 * 156 * @param optional The optional flag, may be {@code null}. 157 */ 158 void setOptional( Boolean optional ); 159 160 /** 161 * Gets a bit field indicating which attributes of this node were subject to dependency management. 162 * 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. 166 */ 167 int getManagedBits(); 168 169 /** 170 * Gets the remote repositories from which this node's artifact shall be resolved. 171 * 172 * @return The (read-only) list of remote repositories to use for artifact resolution, never {@code null}. 173 */ 174 List<RemoteRepository> getRepositories(); 175 176 /** 177 * Gets the request context in which this dependency node was created. 178 * 179 * @return The request context, never {@code null}. 180 */ 181 String getRequestContext(); 182 183 /** 184 * Sets the request context in which this dependency node was created. 185 * 186 * @param context The context, may be {@code null}. 187 */ 188 void setRequestContext( String context ); 189 190 /** 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. 194 * 195 * @return The (read-only) key-value mappings, never {@code null}. 196 */ 197 Map<?, ?> getData(); 198 199 /** 200 * Sets the custom data associated with this dependency node. 201 * 202 * @param data The new custom data, may be {@code null}. 203 */ 204 void setData( Map<Object, Object> data ); 205 206 /** 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. 209 * 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. 212 */ 213 void setData( Object key, Object value ); 214 215 /** 216 * Traverses this node and potentially its children using the specified visitor. 217 * 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. 220 */ 221 boolean accept( DependencyVisitor visitor ); 222 223 }