001/*
002 * Copyright (c) 2010, 2022, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package org.jdrupes.mdoclet.internal.doclets.toolkit;
027
028import java.io.IOException;
029import java.io.StringWriter;
030import java.io.Writer;
031import java.util.Collection;
032import java.util.function.Function;
033
034/**
035 * A content tree for javadoc output pages.
036 */
037public abstract class Content {
038
039    /**
040     * Returns a string representation of the content.
041     * Newlines are represented by {@code \n}.
042     *
043     * @return string representation of the content
044     */
045    @Override
046    public String toString() {
047        StringWriter out = new StringWriter();
048        try {
049            write(out, "\n", true);
050        } catch (IOException e) {
051            // cannot happen from StringWriter
052            throw new AssertionError(e);
053        }
054        return out.toString();
055    }
056
057    /**
058     * Adds content to the existing content.
059     * This is an optional operation.
060     *
061     * @implSpec This implementation throws {@linkplain UnsupportedOperationException}.
062     *
063     * @param content content to be added
064     * @return this object
065     * @throws UnsupportedOperationException if this operation is not supported by
066     *                                       a particular implementation
067     * @throws IllegalArgumentException      if the content is not suitable to be added
068     */
069    public Content add(Content content) {
070        throw new UnsupportedOperationException();
071    }
072
073    /**
074     * Adds a string content to the existing content.
075     * This is an optional operation.
076     *
077     * @implSpec
078     * This implementation throws {@linkplain UnsupportedOperationException}.
079     *
080     * @param stringContent the string content to be added
081     * @return this object
082     * @throws UnsupportedOperationException if this operation is not supported by
083     *                                       a particular implementation
084     * @throws IllegalArgumentException      if the content is not suitable to be added
085     */
086    public Content add(CharSequence stringContent) {
087        throw new UnsupportedOperationException();
088    }
089
090    /**
091     * Adds content to the existing content, generated from a collection of items
092     * This is an optional operation.
093     *
094     * @implSpec This implementation delegates to {@link #add(Content)}.
095     *
096     * @param items  the items to be added
097     * @param mapper the function to create content for each item
098     *
099     * @return this object
100     * @throws UnsupportedOperationException if this operation is not supported by
101     *                                       a particular implementation
102     * @throws IllegalArgumentException      if the content is not suitable to be added
103     */
104    public <T> Content addAll(Collection<T> items,
105            Function<T, Content> mapper) {
106        items.forEach(item -> add(mapper.apply(item)));
107        return this;
108    }
109
110    /**
111     * Writes content to a writer, using a given newline sequence, which should be
112     * either {@code \n} or the platform line separator.
113     *
114     * @param writer the writer
115     * @param newline the newline sequence to use
116     * @param atNewline whether the writer has just written a newline
117     * @return whether the writer has just written a newline
118     * @throws IOException if an error occurs while writing the output
119     */
120    public abstract boolean write(Writer writer, String newline,
121            boolean atNewline) throws IOException;
122
123    /**
124     * Returns true if the content is empty.
125     *
126     * @return true if no content to be displayed else return false
127     */
128    public abstract boolean isEmpty();
129
130    /**
131     * Returns true if this content does not affect the output and can be discarded.
132     * The default implementation considers empty content as discardable.
133     *
134     * @return true if this content can be discarded without affecting the output
135     */
136    public boolean isDiscardable() {
137        return isEmpty();
138    }
139
140    /**
141     * {@return the number of characters of plain text content in this object}
142     */
143    public int charCount() {
144        return 0;
145    }
146}