Java tutorial
// Copyright 2017 The Bazel Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.lib.analysis; import com.google.common.base.Objects; import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableSet; import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable; import com.google.devtools.build.lib.packages.Aspect; import com.google.devtools.build.lib.packages.AspectDefinition; import com.google.devtools.build.lib.packages.AspectDescriptor; import java.util.ArrayList; import java.util.HashMap; import java.util.LinkedHashMap; import java.util.Map.Entry; import java.util.Set; /** * Represents aspects that should be applied to a target as part of {@link Dependency}. * * {@link Dependency} encapsulates all information that is needed to analyze an edge between * an AspectValue or a ConfiguredTargetValue and their direct dependencies, and * {@link AspectCollection} represents an aspect-related part of this information. * * Analysis arrives to a particular node in target graph with an ordered list of aspects that need * to be applied. Some of those aspects should visible to the node in question; some of them * are not directly visible, but are visible to other aspects, as specified by * {@link AspectDefinition#getRequiredProvidersForAspects()}. * * As an example, of all these things in interplay, consider android_binary rule depending * on java_proto_library rule depending on proto_library rule; consider further that * we analyze the android_binary with some ide_info aspect: * <pre> * proto_library(name = "pl") + ide_info_aspect * ^ * | [java_proto_aspect] * java_proto_library(name = "jpl") + ide_info_aspect * ^ * | [DexArchiveAspect] * android_binary(name = "ab") + ide_info_aspect * </pre> * ide_info_aspect is interested in java_proto_aspect, but not in DexArchiveAspect. * * Let's look is the {@link AspectCollection} for a Dependency representing a jpl->pl edge * for ide_info_aspect application to target <code>jpl</code>: * <ul> * <li>the full list of aspects is [java_proto_aspect, DaxProtoAspect, ide_info_aspect] * in this order (the order is determined by the order in which aspects originate on * <code>ab->...->pl</code> path. * </li> * <li>however, DaxProtoAspect is not visible to either ide_info_aspect or java_proto_aspect, * so the reduced list(and a result of {@link #getAllAspects()}) will be * [java_proto_aspect, ide_info_aspect] * </li> * <li>both java_proto_aspect and ide_info_aspect will be visible to * <code>jpl + ide_info_aspect</code> node: the former because java_proto_library * originates java_proto_aspect, and the aspect applied to the node sees the same * dependencies; and the latter because the aspect sees itself on all targets it * propagates to. So {@link #getVisibleAspects()} will return both of them. * </li> * <li>Since ide_info_aspect declared its interest in java_proto_aspect and the latter * comes before it in the order, {@link AspectDeps} for ide_info_aspect will * contain java_proto_aspect (so the application of ide_info_aspect to <code>pl</code> * target will see java_proto_aspect as well). * </li> * </ul> * * More details on members of {@link AspectCollection} follow, as well as more examples * of aspect visibility rules. * * * <p>{@link AspectDeps} is a class that represents an aspect and all aspects that are directly * visible to it.</p> * * <p>{@link #getVisibleAspects()} returns aspects that should be visible to the node in question. * </p> * * <p>{@link #getAllAspects()} return all aspects that should be applied to the target, * in topological order.</p> * * <p>In the following scenario, consider rule r<sub>i</sub> sending an aspect a<sub>i</sub> * to its dependency: * <pre> * [r0] * ^ * (a1) | * [r1] * (a2) | * [r2] * (a3) | * [r3] * </pre> * * When a3 is propagated to target r0, the analysis arrives there with a path [a1, a2, a3]. * Since we analyse the propagation of aspect a3, the only visible aspect is a3. * * <p>Let's first assume that aspect a3 wants to see aspects a1 and a2, but aspects a1 and a2 are * not interested in each other (according to their * {@link AspectDefinition#getRequiredProvidersForAspects()}). * * Since a3 is interested in all aspects, the result of {@link #getAllAspects()} will be * [a1, a2, a3], and {@link AspectCollection} will be: * <ul> * <li>a3 -> [a1, a2], a3 is visible</li> * <li>a2 -> []</li> * <li>a1 -> []</li> * </ul> * * <p>Now what happens if a3 is interested in a2 but not a1, and a2 is interested in a1? * Again, all aspects are transitively interesting to a visible a3, so {@link #getAllAspects()} * will be [a1, a2, a3], but {@link AspectCollection} will now be: * <ul> * <li>a3 -> [a2], a3 is visible</li> * <li>a2 -> [a1]</li> * <li>a1 -> []</li> * </ul> * * <p>As a final example, what happens if a3 is interested in a1, and a1 is interested in a2, but * a3 is not interested in a2? Now the result of {@link #getAllAspects()} will be [a1, a3]. * a1 is interested in a2, but a2 comes later in the path than a1, so a1 does not see it (a1 only * started propagating on r1 -> r0 edge, and there is now a2 originating on that path). * And {@link AspectCollection} will now be: * <ul> * <li>a3 -> [a1], a3 is visible</li> * <li>a1 -> []</li> * </ul> * Note that is does not matter if a2 is interested in a1 or not - since no one after it * in the path is interested in it, a2 is filtered out. * </p> */ @Immutable public final class AspectCollection { /** all aspects in the path; transitively visible to {@link #visibleAspects} */ private final ImmutableSet<AspectDescriptor> aspectPath; /** aspects that should be visible to a dependency */ private final ImmutableSet<AspectDeps> visibleAspects; public static final AspectCollection EMPTY = new AspectCollection(ImmutableSet.<AspectDescriptor>of(), ImmutableSet.<AspectDeps>of()); private AspectCollection(ImmutableSet<AspectDescriptor> allAspects, ImmutableSet<AspectDeps> visibleAspects) { this.aspectPath = allAspects; this.visibleAspects = visibleAspects; } public Iterable<AspectDescriptor> getAllAspects() { return aspectPath; } public ImmutableSet<AspectDeps> getVisibleAspects() { return visibleAspects; } public boolean isEmpty() { return aspectPath.isEmpty(); } @Override public int hashCode() { return aspectPath.hashCode(); } @Override public boolean equals(Object obj) { if (!(obj instanceof AspectCollection)) { return false; } AspectCollection that = (AspectCollection) obj; return Objects.equal(aspectPath, that.aspectPath); } /** * Represents an aspect with all the aspects it depends on * (within an {@link AspectCollection}. * * We preserve the order of aspects to correspond to the order in the * original {@link AspectCollection#aspectPath}, although that is not * strictly needed semantically. */ @Immutable public static final class AspectDeps { private final AspectDescriptor aspect; private final ImmutableList<AspectDeps> dependentAspects; private AspectDeps(AspectDescriptor aspect, ImmutableList<AspectDeps> dependentAspects) { this.aspect = aspect; this.dependentAspects = dependentAspects; } public AspectDescriptor getAspect() { return aspect; } public ImmutableList<AspectDeps> getDependentAspects() { return dependentAspects; } } public static AspectCollection createForTests(AspectDescriptor... descriptors) { return createForTests(ImmutableSet.copyOf(descriptors)); } public static AspectCollection createForTests(ImmutableSet<AspectDescriptor> descriptors) { ImmutableSet.Builder<AspectDeps> depsBuilder = ImmutableSet.builder(); for (AspectDescriptor descriptor : descriptors) { depsBuilder.add(new AspectDeps(descriptor, ImmutableList.<AspectDeps>of())); } return new AspectCollection(descriptors, depsBuilder.build()); } /** * Creates an {@link AspectCollection} from an ordered list of aspects and * a set of visible aspects. * * The order of aspects is reverse to the order in which they originated, with * the earliest originating occurring last in the list. */ public static AspectCollection create(Iterable<Aspect> aspectPath, Set<AspectDescriptor> visibleAspects) throws AspectCycleOnPathException { LinkedHashMap<AspectDescriptor, Aspect> aspectMap = deduplicateAspects(aspectPath); LinkedHashMap<AspectDescriptor, ArrayList<AspectDescriptor>> deps = new LinkedHashMap<>(); // Calculate all needed aspects (either visible from outside or visible to // other needed aspects). Already discovered needed aspects are in key set of deps. // 1) Start from the end of the path. The aspect only sees other aspects that are // before it // 2) If the 'aspect' is visible from outside, it is needed. // 3) Otherwise, check whether 'aspect' is visible to any already needed aspects, // if it is visible to a needed 'depAspect', // add the 'aspect' to a list of aspects visible to 'depAspect'. // if 'aspect' is needed, add it to 'deps'. // At the end of this algorithm, key set of 'deps' contains a subset of original // aspect list consisting only of needed aspects, in reverse (since we iterate // the original list in reverse). // // deps[aspect] contains all aspects that 'aspect' needs, in reverse order. for (Entry<AspectDescriptor, Aspect> aspect : ImmutableList.copyOf(aspectMap.entrySet()).reverse()) { boolean needed = visibleAspects.contains(aspect.getKey()); for (AspectDescriptor depAspectDescriptor : deps.keySet()) { if (depAspectDescriptor.equals(aspect.getKey())) { continue; } Aspect depAspect = aspectMap.get(depAspectDescriptor); if (depAspect.getDefinition().getRequiredProvidersForAspects() .isSatisfiedBy(aspect.getValue().getDefinition().getAdvertisedProviders())) { deps.get(depAspectDescriptor).add(aspect.getKey()); needed = true; } } if (needed && !deps.containsKey(aspect.getKey())) { deps.put(aspect.getKey(), new ArrayList<AspectDescriptor>()); } } // Record only the needed aspects from all aspects, in correct order. ImmutableList<AspectDescriptor> neededAspects = ImmutableList.copyOf(deps.keySet()).reverse(); // Calculate visible aspect paths. HashMap<AspectDescriptor, AspectDeps> aspectPaths = new HashMap<>(); ImmutableSet.Builder<AspectDeps> visibleAspectPaths = ImmutableSet.builder(); for (AspectDescriptor visibleAspect : visibleAspects) { visibleAspectPaths.add(buildAspectDeps(visibleAspect, aspectPaths, deps)); } return new AspectCollection(ImmutableSet.copyOf(neededAspects), visibleAspectPaths.build()); } /** * Deduplicate aspects in path. * * @throws AspectCycleOnPathException if an aspect occurs twice on the path and * the second occurrence sees a different set of aspects. */ private static LinkedHashMap<AspectDescriptor, Aspect> deduplicateAspects(Iterable<Aspect> aspectPath) throws AspectCycleOnPathException { LinkedHashMap<AspectDescriptor, Aspect> aspectMap = new LinkedHashMap<>(); ArrayList<Aspect> seenAspects = new ArrayList<>(); for (Aspect aspect : aspectPath) { if (!aspectMap.containsKey(aspect.getDescriptor())) { aspectMap.put(aspect.getDescriptor(), aspect); seenAspects.add(aspect); } else { validateDuplicateAspect(aspect, seenAspects); } } return aspectMap; } /** * Detect inconsistent duplicate occurrence of an aspect on the path. * There is a previous occurrence of {@code aspect} in {@code seenAspects}. * * If in between that previous occurrence and the newly discovered occurrence * there is an aspect that is visible to {@code aspect}, then the second occurrence * is inconsistent - the set of aspects it sees is different from the first one. */ private static void validateDuplicateAspect(Aspect aspect, ArrayList<Aspect> seenAspects) throws AspectCycleOnPathException { for (int i = seenAspects.size() - 1; i >= 0; i--) { Aspect seenAspect = seenAspects.get(i); if (aspect.getDescriptor().equals(seenAspect.getDescriptor())) { // This is a previous occurrence of the same aspect. return; } if (aspect.getDefinition().getRequiredProvidersForAspects() .isSatisfiedBy(seenAspect.getDefinition().getAdvertisedProviders())) { throw new AspectCycleOnPathException(aspect.getDescriptor(), seenAspect.getDescriptor()); } } } private static AspectDeps buildAspectDeps(AspectDescriptor descriptor, HashMap<AspectDescriptor, AspectDeps> aspectPaths, LinkedHashMap<AspectDescriptor, ArrayList<AspectDescriptor>> deps) { if (aspectPaths.containsKey(descriptor)) { return aspectPaths.get(descriptor); } ImmutableList.Builder<AspectDeps> aspectPathBuilder = ImmutableList.builder(); ArrayList<AspectDescriptor> depList = deps.get(descriptor); // deps[aspect] contains all aspects visible to 'aspect' in reverse order. for (int i = depList.size() - 1; i >= 0; i--) { aspectPathBuilder.add(buildAspectDeps(depList.get(i), aspectPaths, deps)); } AspectDeps aspectPath = new AspectDeps(descriptor, aspectPathBuilder.build()); aspectPaths.put(descriptor, aspectPath); return aspectPath; } /** * Signals an inconsistency on aspect path: an aspect occurs twice on the path and * the second occurrence sees a different set of aspects. * * {@link #getAspect()} is the aspect occuring twice, and {@link #getPreviousAspect()} * is the aspect that the second occurrence sees but the first does not. */ public static class AspectCycleOnPathException extends Exception { private final AspectDescriptor aspect; private final AspectDescriptor previousAspect; public AspectCycleOnPathException(AspectDescriptor aspect, AspectDescriptor previousAspect) { super(String.format("Aspect %s is applied twice, both before and after aspect %s", aspect.getDescription(), previousAspect.getDescription())); this.aspect = aspect; this.previousAspect = previousAspect; } public AspectDescriptor getAspect() { return aspect; } public AspectDescriptor getPreviousAspect() { return previousAspect; } } }