Java tutorial
// Copyright 2014 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.graph; import com.google.common.collect.Sets; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.List; /** * <p>A generic directed-graph Node class. Type parameter T is the type * of the node's label. * * <p>Each node is identified by a label, which is unique within the graph * owning the node. * * <p>Nodes are immutable, that is, their labels cannot be changed. However, * their predecessor/successor lists are mutable. * * <p>Nodes cannot be created directly by clients. * * <p>Clients should not confuse nodes belonging to two different graphs! (Use * Digraph.checkNode() to catch such errors.) There is no way to find the * graph to which a node belongs; it is intentionally not represented, to save * space. */ public final class Node<T> { private static final int ARRAYLIST_THRESHOLD = 6; private static final int INITIAL_HASHSET_CAPACITY = 12; // The succs and preds set representation changes depending on its size. // It is implemented using the following collections: // - null for size = 0. // - Collections$SingletonList for size = 1. // - ArrayList(6) for size = [2..6]. // - HashSet(12) for size > 6. // These numbers were chosen based on profiling. private final T label; /** * A duplicate-free collection of edges from this node. May be null, * indicating the empty set. */ private Collection<Node<T>> succs = null; /** * A duplicate-free collection of edges to this node. May be null, * indicating the empty set. */ private Collection<Node<T>> preds = null; private final int hashCode; /** * Only Digraph.createNode() can call this! */ Node(T label, int hashCode) { if (label == null) { throw new NullPointerException("label"); } this.label = label; this.hashCode = hashCode; } /** * Returns the label for this node. */ public T getLabel() { return label; } /** * Returns a duplicate-free collection of the nodes that this node links to. */ public Collection<Node<T>> getSuccessors() { if (succs == null) { return Collections.emptyList(); } else { return Collections.unmodifiableCollection(succs); } } /** * Equivalent to {@code !getSuccessors().isEmpty()} but possibly more * efficient. */ public boolean hasSuccessors() { return succs != null; } /** * Equivalent to {@code getSuccessors().size()} but possibly more efficient. */ public int numSuccessors() { return succs == null ? 0 : succs.size(); } /** * Removes all edges to/from this node. * Private: breaks graph invariant! */ void removeAllEdges() { this.succs = null; this.preds = null; } /** * Returns an (unordered, possibly immutable) set of the nodes that link to * this node. */ public Collection<Node<T>> getPredecessors() { if (preds == null) { return Collections.emptyList(); } else { return Collections.unmodifiableCollection(preds); } } /** * Equivalent to {@code getPredecessors().size()} but possibly more * efficient. */ public int numPredecessors() { return preds == null ? 0 : preds.size(); } /** * Equivalent to {@code !getPredecessors().isEmpty()} but possibly more * efficient. */ public boolean hasPredecessors() { return preds != null; } /** * Adds 'value' to either the predecessor or successor set, updating the * appropriate field as necessary. * @return {@code true} if the set was modified; {@code false} if the set * was not modified */ private boolean add(boolean predecessorSet, Node<T> value) { final Collection<Node<T>> set = predecessorSet ? preds : succs; if (set == null) { // null -> SingletonList return updateField(predecessorSet, Collections.singletonList(value)); } if (set.contains(value)) { // already exists in this set return false; } int previousSize = set.size(); if (previousSize == 1) { // SingletonList -> ArrayList Collection<Node<T>> newSet = new ArrayList<>(ARRAYLIST_THRESHOLD); newSet.addAll(set); newSet.add(value); return updateField(predecessorSet, newSet); } else if (previousSize < ARRAYLIST_THRESHOLD) { // ArrayList set.add(value); return true; } else if (previousSize == ARRAYLIST_THRESHOLD) { // ArrayList -> HashSet Collection<Node<T>> newSet = Sets.newHashSetWithExpectedSize(INITIAL_HASHSET_CAPACITY); newSet.addAll(set); newSet.add(value); return updateField(predecessorSet, newSet); } else { // HashSet set.add(value); return true; } } /** * Removes 'value' from either 'preds' or 'succs', updating the appropriate * field as necessary. * @return {@code true} if the set was modified; {@code false} if the set * was not modified */ private boolean remove(boolean predecessorSet, Node<T> value) { final Collection<Node<T>> set = predecessorSet ? preds : succs; if (set == null) { // null return false; } int previousSize = set.size(); if (previousSize == 1) { if (set.contains(value)) { // -> null return updateField(predecessorSet, null); } else { return false; } } // now remove the value if (set.remove(value)) { // may need to change representation if (previousSize == 2) { // -> SingletonList List<Node<T>> list = Collections.singletonList(set.iterator().next()); return updateField(predecessorSet, list); } else if (previousSize == 1 + ARRAYLIST_THRESHOLD) { // -> ArrayList Collection<Node<T>> newSet = new ArrayList<>(ARRAYLIST_THRESHOLD); newSet.addAll(set); return updateField(predecessorSet, newSet); } return true; } return false; } /** * Update either the {@link #preds} or {@link #succs} field to point to the * new set. * @return {@code true}, because the set must have been updated */ private boolean updateField(boolean predecessorSet, Collection<Node<T>> newSet) { if (predecessorSet) { preds = newSet; } else { succs = newSet; } return true; } /** * Add 'to' as a successor of 'this' node. Returns true iff * the graph changed. Private: breaks graph invariant! */ boolean addSuccessor(Node<T> to) { return add(false, to); } /** * Add 'from' as a predecessor of 'this' node. Returns true iff * the graph changed. Private: breaks graph invariant! */ boolean addPredecessor(Node<T> from) { return add(true, from); } /** * Remove edge: fromNode.succs = {n | n in fromNode.succs && n != toNode} * Private: breaks graph invariant! */ boolean removeSuccessor(Node<T> to) { return remove(false, to); } /** * Remove edge: toNode.preds = {n | n in toNode.preds && n != fromNode} * Private: breaks graph invariant! */ boolean removePredecessor(Node<T> from) { return remove(true, from); } @Override public String toString() { return "node:" + label; } @Override public int hashCode() { return hashCode; // Fast, deterministic. } @Override public boolean equals(Object that) { return this == that; // Nodes are unique for a given label } }