org.argeo.slc.repo/src/org/eclipse/aether/graph/DependencyNode.java

   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 }