Github user kinow commented on a diff in the pull request: https://github.com/apache/commons-lang/pull/311#discussion_r164282304 --- Diff: src/main/java/org/apache/commons/lang3/time/StackWatch.java --- @@ -0,0 +1,329 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.commons.lang3.time; + +import java.util.Deque; +import java.util.LinkedList; +import org.apache.commons.lang3.StringUtils; + +/** + * <p> + * The {@code StackWatch}, provides a wrapper around the {@code StopWatch} for creating multiple and + * possibly nested named timings. + * </p> + * <p> + * While the {@code StopWatch} provides functionality to time the length of operations, there is no + * context or name to go with the time tracked. It is also not possible to time nested calls with + * the {@code StopWatch}. + * </p> + * <p> + * {@code StackWatch} provides that functionality, allowing successive calls to {@link StackWatch#startTiming(String, String...)} to track + * nested calls. + * </p> + * <p> + * Each start provides a timing name and a parent timing name, thus providing context to the timing. + * </p> + * <p> + * At the end of a timing 'run', a visitor interface provides the ability to visit all the timing + * 'nodes' and capture their output, including the level of the call if nested. + * </p> + * <p> + * The {@code TimeRecordNodes} provide a tree structure in support of nesting. + * A {@code Deque} is use to track the current time node. + * </p> + * + * <pre> + * {@code + * private void outerFunction() { + * try { + * StackWatch watch = new StackWatch("OuterFunction"); + * watch.start(); + * functionOne(); + * watch.stop(); + * watch.visit(new TimingRecordNodeVisitor() { + * {@literal @}Override + * public void visitRecord(int level, TimingRecordNode node) { + * ... + * } + * }); + * } catch (Exception e){} + * } + * private void functionOne(StackWatch watch) throws Exception { + * watch.startTiming("One", "OneFunc"); + * functionOneOne(watch); + * watch.stopTiming(); + * } + * + * private void functionOneOne(StackWatch watch) throws Exception { + * watch.startTiming("OneOne", "OneFunc"); + * functionOneTwo(watch); + * watch.stopTiming(); + * } + * + * private void functionOneTwo(StackWatch watch) throws Exception { + * watch.startTiming("OneTwo", "OneFunc"); + * watch.stopTiming(); + * } + * } + * </pre> + * + * + * <p> + * This class is not thread safe, and is meant to track timings across multiple calls on the same + * thread + * </p> + */ +public class StackWatch { + + /** + * The default name for the root level timing if not provided + */ + public static final String DEFAULT_ROOT_NAME = "ROOT_TIMING"; --- End diff -- Here is needs to be four spaced as well. You can look at another file and compare that (e.g. https://github.com/apache/commons-lang/blob/f50ec5e608286b0c48d6b9b4c792352de8353804/src/main/java/org/apache/commons/lang3/concurrent/AtomicSafeInitializer.java#L58).
---