001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 */
019package org.apache.isis.core.commons.debug;
020
021public interface DebugBuilder {
022
023    /**
024     * Concatenate the contents of the specified debug builder to the current
025     * builder.
026     */
027    void concat(DebugBuilder debug);
028
029    /**
030     * Append the specified number within a space (number of spaces) specified
031     * by the width. E.g. "15 " where number is 15 and width is 4.
032     */
033    void append(final int number, final int width);
034
035    /**
036     * Append the specified object by calling it <code>toString()</code> method.
037     */
038    void append(final Object object);
039
040    /**
041     * Append the specified object by calling its <code>toString()</code>
042     * method, placing it within specified space.
043     */
044    void append(final Object object, final int width);
045
046    /**
047     * Append the specified number, displayed in hexadecimal notation, with the
048     * specified label, then start a new line.
049     */
050    void appendAsHexln(final String label, final long value);
051
052    /**
053     * Append the message and trace of the specified exception.
054     */
055    void appendException(final Throwable e);
056
057    /**
058     * Start a new line.
059     * 
060     * @see #blankLine()
061     */
062    void appendln();
063
064    /**
065     * Append the specified text, then start a new line.
066     */
067    void appendln(final String text);
068
069    /**
070     * Append the specified text without any formatting.
071     */
072    void appendPreformatted(final String text);
073
074    /**
075     * Append the specified value, displayed as true or false, with the
076     * specified label, then start a new line.
077     */
078    void appendln(final String label, final boolean value);
079
080    /**
081     * Append the specified number with the specified label, then start a new
082     * line.
083     */
084    void appendln(final String label, final double value);
085
086    /**
087     * Append the specified number, displayed in hexadecimal notation, with the
088     * specified label, then start a new line.
089     */
090    void appendln(final String label, final long value);
091
092    /**
093     * Append the specified preformatted text with the specified label, then
094     * start a new line.
095     */
096    void appendPreformatted(final String label, final String text);
097
098    /**
099     * Append the specified object with the specified label, then start a new
100     * line.
101     */
102    void appendln(final String label, final Object object);
103
104    /**
105     * Append the elements of the specified array with the specified label. Each
106     * element is appended on its own line, and a new line is added after the
107     * last element.
108     */
109    void appendln(final String label, final Object[] objects);
110
111    /**
112     * Append the specified title, then start a new line. A title is shown on
113     * two lines with the text on the first line and dashes on the second.
114     */
115    void appendTitle(final String title);
116
117    void startSection(final String title);
118
119    void endSection();
120
121    /**
122     * Append a blank line only if there are existing lines and the previous
123     * line is not blank.
124     */
125    void blankLine();
126
127    /**
128     * Increase indent used when appending.
129     */
130    void indent();
131
132    /**
133     * Decrease indent used when appending.
134     */
135    void unindent();
136
137    void close();
138
139}