org.netbeans.api.io.InputOutput Maven / Gradle / Ivy

Go to download
/*
 * 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.netbeans.api.io;

import java.io.PrintWriter;
import java.io.Reader;
import java.util.Collections;
import java.util.EnumSet;
import java.util.Map;
import java.util.Set;
import java.util.WeakHashMap;
import org.netbeans.api.annotations.common.CheckForNull;
import org.netbeans.api.annotations.common.NonNull;
import org.netbeans.api.annotations.common.NullAllowed;
import org.netbeans.spi.io.InputOutputProvider;
import org.openide.util.Lookup;

/**
 * An I/O connection to one tab on the Output Window. To acquire an instance to
 * write to, call, e.g.,
 * IOProvider.getDefault().getInputOutput("someName", false). To
 * get actual streams to write to, call getOut() or 
 * getErr() on the returned instance.
 * 
 * Generally it is preferable not to hold a reference to an instance of
 * {@link org.netbeans.api.io.InputOutput}, but rather to fetch it by name from
 * {@link org.netbeans.api.io.IOProvider} as needed.
 * 
 *
 * 
 * Methods of this class can be called in any thread.
 * 
 *
 * @see OutputWriter
 * @author Ian Formanek, Jaroslav Tulach, Petr Hamernik, Ales Novak, Jan
 * Jancura, Jaroslav Havlin
 */
public abstract class InputOutput implements Lookup.Provider {

    private static final Set DEFAULT_SHOW_OPERATIONS
            = EnumSet.of(ShowOperation.OPEN, ShowOperation.MAKE_VISIBLE);

    private InputOutput() {
    }

    /**
     * Get a named instance of InputOutput from the default {@link IOProvider},
     * which represents an output tab in the output window. Streams for
     * reading/writing can be accessed via getters on the returned instance.
     *
     * 
     * This is a shorthand for {@code IOProvider.getDefault().getIO(...)}.
     * 
     *
     * @param name A localised display name for the tab.
     * @param newIO If true, a new InputOutput is
     * returned, else an existing InputOutput of the same name may
     * be returned.
     * @return An InputOutput instance for accessing the new tab.
     * @see IOProvider
     */
    @NonNull
    public static InputOutput get(@NonNull String name, boolean newIO) {
        return IOProvider.getDefault().getIO(name, newIO);
    }

     /**
     * Get a named instance of InputOutput from the default {@link IOProvider},
     * which represents an output tab in the output window. Streams for
     * reading/writing can be accessed via getters on the returned instance.
     *
     * 
     * This is a shorthand for {@code IOProvider.getDefault().getIO(...)}.
     * 
     *
     * @param name A localised display name for the tab.
     * @param newIO If true, a new InputOutput is
     * returned, else an existing InputOutput of the same name may
     * be returned.
     * @param lookup Lookup which may contain additional information for various
     * implementations of output window.
     * @return An InputOutput instance for accessing the new tab.
     * @see IOProvider
     */
    @NonNull
    public static InputOutput get(@NonNull String name, boolean newIO,
            @NonNull Lookup lookup) {
        return IOProvider.getDefault().getIO(name, newIO, lookup);
    }

    /**
     * Get a reader to read from the tab.
     *
     * @return The reader.
     */
    @NonNull
    public abstract Reader getIn();

    /**
     * Acquire an output writer to write to the tab.
     *
     * @return The writer.
     */
    @NonNull
    public abstract OutputWriter getOut();

    /**
     * Get an output writer to write to the tab in error mode. This might show
     * up in a different color than the regular output, e.g., or appear in a
     * separate pane.
     *
     * @return The writer.
     */
    @NonNull
    public abstract OutputWriter getErr();

    /**
     * Clear the output pane.
     */
    public abstract void reset();

    /**
     * Get lookup which may contain extensions provided by implementation of
     * output window.
     *
     * @return The lookup.
     */
    @NonNull
    @Override
    public abstract Lookup getLookup();

    /**
     * Closes this tab. The effect of calling any method on an instance of
     * InputOutput after calling close() on it is
     * undefined.
     */
    public abstract void close();

    /**
     * Test whether this tab has been closed, either by a call to
     * {@link #close()} or by the user closing the tab in the UI.
     *
     * @return Value true if it is closed.
     */
    public abstract boolean isClosed();

    /**
     * Get description of this I/O instance.
     *
     * @return The description, or null if not set.
     */
    @CheckForNull
    public abstract String getDescription();

    /**
     * Set description of this I/O instance. It can be used e.g. as tooltip for
     * output tab in the GUI.
     *
     * @param description The description, can be null.
     */
    public abstract void setDescription(@NullAllowed String description);

    static  InputOutput create(
            InputOutputProvider provider, IO io) {

        return new Impl(provider, io);
    }

    /**
     * Show this I/O if possible (e.g. in tabbed pane).
     * 
     * Calling this method is the same as calling:
     * 
     *      * show(EnumSet.of(ShowOperation.OPEN, ShowOperation.MAKE_VISIBLE));
     * 
     *
     * @see #show(java.util.Set)
     */
    public final void show() {
        show(DEFAULT_SHOW_OPERATIONS);
    }

    /**
     * Show this I/O if possible (e.g. in tabbed pane).
     *
     * @param operations Set of operations that should be invoked to show the
     * output. If the set is empty or null, pane for this I/O will be only
     * selected, but its component will not be opened or made visible. So it
     * will stay closed or hidden if it is not opened or not visible.
     *
     * @see ShowOperation
     */
    public abstract void show(@NullAllowed Set operations);

    private static class Impl
            extends InputOutput {

        private final Map cache
                = Collections.synchronizedMap(
                        new WeakHashMap());

        private final InputOutputProvider provider;
        private final IO ioObject;

        public Impl(InputOutputProvider provider, IO ioObject) {

            this.provider = provider;
            this.ioObject = ioObject;
        }

        @Override
        public Reader getIn() {
            return provider.getIn(ioObject);
        }

        @Override
        public OutputWriter getOut() {
            return createOrGetCachedWrapper(provider.getOut(ioObject));
        }

        @Override
        public OutputWriter getErr() {
            return createOrGetCachedWrapper(provider.getErr(ioObject));
        }

        @Override
        @NonNull
        public Lookup getLookup() {
            return provider.getIOLookup(ioObject);
        }

        @Override
        public void reset() {
            provider.resetIO(ioObject);
        }

        private OutputWriter createOrGetCachedWrapper(OW pw) {
            OutputWriter ow = cache.get(pw);
            if (ow == null) {
                ow = OutputWriter.create(provider, ioObject, pw);
                cache.put(pw, ow);
            }
            return ow;
        }

        @Override
        public void close() {
            provider.closeIO(ioObject);
        }

        @Override
        public boolean isClosed() {
            return provider.isIOClosed(ioObject);
        }

        @Override
        public String getDescription() {
            return provider.getIODescription(ioObject);
        }

        @Override
        public void setDescription(String description) {
            provider.setIODescription(ioObject, description);
        }

        @Override
        public void show(Set operations) {
            provider.showIO(ioObject,
                    operations != null
                            ? operations
                            : Collections.emptySet());
        }
    }
}