001package org.eclipse.aether.graph;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 * 
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 * 
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.util.Collection;
023import java.util.List;
024import java.util.Map;
025
026import org.eclipse.aether.artifact.Artifact;
027import org.eclipse.aether.repository.RemoteRepository;
028import org.eclipse.aether.version.Version;
029import org.eclipse.aether.version.VersionConstraint;
030
031/**
032 * A node within a dependency graph. To conserve memory, dependency graphs may reuse a given node instance multiple
033 * times to represent reoccurring dependencies. As such clients traversing a dependency graph should be prepared to
034 * discover multiple paths leading to the same node instance unless the input graph is known to be a duplicate-free
035 * tree. <em>Note:</em> Unless otherwise noted, implementation classes are not thread-safe and dependency nodes should
036 * not be mutated by concurrent threads.
037 * 
038 * @noimplement This interface is not intended to be implemented by clients.
039 * @noextend This interface is not intended to be extended by clients.
040 */
041public interface DependencyNode
042{
043
044    /**
045     * A bit flag indicating the dependency version was subject to dependency management
046     * 
047     * @see #getManagedBits()
048     */
049    int MANAGED_VERSION = 0x01;
050
051    /**
052     * A bit flag indicating the dependency scope was subject to dependency management
053     * 
054     * @see #getManagedBits()
055     */
056    int MANAGED_SCOPE = 0x02;
057
058    /**
059     * A bit flag indicating the optional flag was subject to dependency management
060     * 
061     * @see #getManagedBits()
062     */
063    int MANAGED_OPTIONAL = 0x04;
064
065    /**
066     * A bit flag indicating the artifact properties were subject to dependency management
067     * 
068     * @see #getManagedBits()
069     */
070    int MANAGED_PROPERTIES = 0x08;
071
072    /**
073     * A bit flag indicating the exclusions were subject to dependency management
074     * 
075     * @see #getManagedBits()
076     */
077    int MANAGED_EXCLUSIONS = 0x10;
078
079    /**
080     * Gets the child nodes of this node. To conserve memory, dependency nodes with equal dependencies may share the
081     * same child list instance. Hence clients mutating the child list need to be aware that these changes might affect
082     * more than this node. Where this is not desired, the child list should be copied before mutation if the client
083     * cannot be sure whether it might be shared with other nodes in the graph.
084     * 
085     * @return The child nodes of this node, never {@code null}.
086     */
087    List<DependencyNode> getChildren();
088
089    /**
090     * Sets the child nodes of this node.
091     * 
092     * @param children The child nodes, may be {@code null}
093     */
094    void setChildren( List<DependencyNode> children );
095
096    /**
097     * Gets the dependency associated with this node. <em>Note:</em> For dependency graphs that have been constructed
098     * without a root dependency, this method will yield {@code null} when invoked on the graph's root node. The root
099     * 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}