View Javadoc
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 }