org.netbeans.spi.io.InputOutputProvider Maven / Gradle / Ivy
/*
* 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.spi.io;
import java.io.PrintWriter;
import java.io.Reader;
import java.util.Set;
import org.netbeans.api.annotations.common.CheckForNull;
import org.netbeans.api.annotations.common.NonNull;
import org.netbeans.api.annotations.common.NullAllowed;
import org.netbeans.api.io.Hyperlink;
import org.netbeans.api.io.InputOutput;
import org.netbeans.api.io.OutputColor;
import org.netbeans.api.io.ShowOperation;
import org.openide.util.Lookup;
import org.openide.util.lookup.ServiceProvider;
/**
*
* SPI for custom output window implementations.
*
* Use {@link ServiceProvider} annotation for registration.
*
*
*
* Note: Methods of this interface can be called in any thread by the
* infrastructure, so implementations should ensure proper synchronization.
*
*
* @author jhavlin
*
* @param Type of objects that will represent I/O instances (e.g. tabs in
* output window).
* @param Type of writers for standard and error streams.
* @param Type of object that describes position of a character in the
* output window. If the implementation does not support this type of
* information, use {@link Void} here.
* @param Type of object that describes a fold in output window. If the
* implementation does not support this type of information, use {@link Void}
* here.
*/
public interface InputOutputProvider {
/**
* Get identifier of this provider.
*
* @return Name of this provider, never null.
*/
@NonNull
String getId();
/**
* Get or create an object that encapsulates state of a single I/O instance
* (e.g. tab in output window).
*
* @param name Display name of the output pane.
* @param newIO True to always create new I/O, false to return already
* existing instance if available.
* @param lookup Lookup with additional information.
*
* @return A single I/O instance, a newly created or already existing.
* @see InputOutput
*/
@NonNull
IO getIO(@NonNull String name, boolean newIO, @NonNull Lookup lookup);
/**
* Get input of the passed I/O.
*
* @param io I/O instance.
*
* @return {@link Reader} Reader for the input entered in the output pane.
*/
@NonNull
Reader getIn(@NonNull IO io);
/**
* Get output stream of the passed I/O.
*
* @param io I/O instance.
*
* @return {@link PrintWriter} for the output stream.
*/
@NonNull
WRITER getOut(@NonNull IO io);
/**
* Get error stream of the passed I/O.
*
* @param io The I/O instance.
*
* @return {@link PrintWriter} for the error stream.
*/
@NonNull
WRITER getErr(@NonNull IO io);
/**
* Print enhanced text. It can represent a clickable hyperlink, and can be
* assigned some color.
*
*
* If the implementation doesn't support this feature, this method should
* call something like
* {@code writer.print(text); if (printLineEnd) {writer.println();}}.
*
*
* @param io The I/O instance.
* @param writer The Stream to write into.
* @param text Text to print.
* @param link Link which should be represented by the text, can be null for
* standard text.
* @param color Color of the text, can be null for the default color of the
* stream.
* @param printLineEnd True if new-line should be appended after printing
* {code text}.
*/
void print(@NonNull IO io, @NonNull WRITER writer, @NullAllowed String text,
@NullAllowed Hyperlink link, @NullAllowed OutputColor color,
boolean printLineEnd);
/**
* Get lookup of an I/O instance, which can contain various extensions and
* additional info.
*
* @param io The I/O instance.
*
* @return The lookup, which can be empty, but never null.
*/
@NonNull
Lookup getIOLookup(@NonNull IO io);
/**
* Reset the I/O. Clear previously written data and prepare it for new data.
*
* If the implementation doesn't support this feature, this method should do
* nothing.
*
*
* @param io The I/O instance.
*/
void resetIO(@NonNull IO io);
/**
* Show output pane for the passed I/O instance.
*
* If the implementation doesn't support this feature, this method should do
* nothing.
*
*
* @param io The I/O instance.
* @param operations Operations that should be performed to show the output.
* If the set is empty, the output pane (e.g. tab) can be selected, but no
* GUI component should be shown or made visible if it is currently closed
* or hidden.
*
* @see ShowOperation
*/
void showIO(@NonNull IO io,
Set operations);
/**
* Close the I/O, its output pane and release resources.
*
* @param io The I/O instance.
*
* @see #isIOClosed(java.lang.Object)
*/
void closeIO(@NonNull IO io);
/**
* Check whether the I/O is closed.
*
* @param io The I/O instance.
*
* @return True if the I/O was closed, false otherwise.
*
* @see #closeIO(java.lang.Object)
*/
boolean isIOClosed(@NonNull IO io);
/**
* Get current position.
*
* @param io The I/O instance.
* @param writer Output or error writer. If the streams are merged, the
* value can be ignored.
*
* @return The current position in the output pane. If this feature is not
* supported, return null.
*/
@CheckForNull
POS getCurrentPosition(@NonNull IO io, @NonNull WRITER writer);
/**
* Scroll to a position.
*
* If this feature is not supported
* ({@link #getCurrentPosition(Object, PrintWriter)} returns null), this
* method should do nothing, it will be never called.
*
*
* @param io The I/O instance.
* @param writer Output or error writer. If the streams are merged, the
* value can be ignored.
* @param position The position to scroll to.
*
* @see #getCurrentPosition(java.lang.Object, java.io.PrintWriter)
*/
void scrollTo(@NonNull IO io, @NonNull WRITER writer,
@NonNull POS position);
/**
* Start fold at the current position. If a fold is already open, start a
* new nested fold (but if a fold with the same start position already
* exists, no nested fold will be created, and the same start position will
* be returned).
*
* @param io The I/O instance.
* @param writer Output or error writer. If the streams are merged, the
* value can be ignored.
* @param expanded True if the new fold should be expanded by default, false
* if it should be collapsed.
*
* @return Object the fold. If the implementation doesn't support this
* feature, return null.
*/
@CheckForNull
FOLD startFold(@NonNull IO io, @NonNull WRITER writer, boolean expanded);
/**
* Finish a fold specified by its start position. If some nested folds
* exist, they will be finished as well if needed.
*
*
* If this feature is not supported
* ({@link #startFold(Object, PrintWriter, boolean)} returns null), this
* method should do nothing, it will be never called.
*
*
* @param io The I/O instance.
* @param writer Output or error writer. If the streams are merged, the
* value can be ignored.
* @param fold The fold to finish.
*/
void endFold(@NonNull IO io, @NonNull WRITER writer,
@NonNull FOLD fold);
/**
* Expand or collapse a fold.
*
*
* If this feature is not supported
* ({@link #startFold(Object, PrintWriter, boolean)} returns null), this
* method should do nothing, it will be never called.
*
*
* @param io The I/O instance.
* @param writer Output or error writer. If the streams are merged, the
* value can be ignored.
* @param fold The fold to finish.
* @param expanded True to expand the fold, false to collapse the fold.
*/
void setFoldExpanded(@NonNull IO io, @NonNull WRITER writer,
FOLD fold, boolean expanded);
/**
* Get description of an I/O instance. It can be used e.g. as tooltip text
* for the output tab.
*
* @param io The I/O instance.
*
* @return The description, or null if not set.
*/
@CheckForNull String getIODescription(@NonNull IO io);
/**
* Set description of an I/O instance.
*
*
* If this feature is not supported, this method should do nothing.
*
*
* @param io The I/O instance.
* @param description The description, can be null.
*
* @see #getIODescription(java.lang.Object)
*/
void setIODescription(@NonNull IO io, @NullAllowed String description);
}