+ The module contains APIs for creating output panes (e.g. output tabs in Output Window in the IDE) + and for writing data into them. It also supports some advanced techniques, e.g. color text, + hyperlinks, code folding, scrolling to stored positions. +
+
+ SPI for providing custom implementations of output window is also included in this module, in package
+ org.netbeans.spi.io
+
+ Unit test will be prepared for invocable code in API classes. But most of the + code is just definition of API and SPI. +
++ The design, implementation, preparing unit tests and reviews will + probably take several weeks. +
++ The basic use-case is printing a simple text, e.g. text output of an application, + into a dedicated pane in the UI, e.g. a tab in Output Window in the IDE. +
+
+ InputOutput io = InputOutput.get("UseCase1", true);
+ io.getOut().println("This is a simple output");
+ io.getOut().close();
+
+ + Hyperlinks can be also used to invoke some code when clicked. +
+
+ InputOutput io = InputOutput.get("UseCase3", true);
+ io.getOut().print("A line containing a ");
+ io.getOut().print("hyperlink", Hyperlink.from(new Runnable() {
+ public void run() {
+ System.gc();
+ }
+ }));
+ io.getOut().println(" for invocation of custom code.");
+ io.getOut().close();
+
+ + Print a color text. Users can select a predefined color for + common cases (debug, warning, failure, success), or custom + color specified as RGB value. +
+
+ InputOutput io = InputOutput.get("UseCase4", true);
+ io.getOut().println("Let's print some info", OutputColor.debug());
+ io.getOut().println("or warning with appropriate color", OutputColor.warning());
+ io.getOut().println("Maybe also text with custom reddish color", OutputColor.rgb(255, 16, 16));
+ io.getOut().close();
+
+ + It is possible to reuse already created output pane and clear + all the previously printed text if it is not needed any more. +
+
+ InputOutput io = InputOutput.get("UseCase5", true);
+ io.getOut().println("Let's print some text");
+ io.getErr().println("and reset the pane immediately.");
+ io.reset();
+ io.getOut().println("The pane is now empty and we can reuse it simply");
+ io.getOut().close();
+
+
+ The Input/Output API and SPI is a small module
+ which contains InputOutput and related interfaces used in
+ driving the Output Window.
+
+ The normal implementation is org.netbeans.core.output2.
+
+ Backward compatibility of other modules is not broken. +
+
+ This module should replace original I/O API module
+ org.openide.io, which has the same goals, but which is
+ not UI independent, and which is difficult to extend.
+
+ Yes. There is not much to internationalize. +
++ The module defines an API. +
++ N/A. No settings are read or written by this module. +
++ Normal module dependency is enough. +
++ Availability of some implementation of the SPI is guaranteed by + "OpenIDE-Module-Needs: org.netbeans.spi.io.InputOutputProvider" in + the manifest of this module. +
++ Just the module JAR. +
++ Yes. +
++ No; only API classes are public. +
++ Anywhere. +
++ No. +
++ No. +
++ No. +
++ No. +
++ No. +
++ No. +
++ No. +
++ No. +
++ API classes are thread safe, they mostly represent immutable + objects, or delegate to the SPI. +
++ Implementators of the SPI should ensure that their code is properly + synchronized, as it can be called from any thread. +
++ Plain Unicode text only. +
++ N/A +
++ None. +
+
+ IOProvider.getDefault() asks lookup for the first instance
+ of InputOutputProvider. This is normally provided by
+ org.netbeans.core.output2.
+
+ No. +
++ No. +
++ No. +
++ No. +
++ No. +
++ N/A +
++ No. +
++ No. +
++ Scalability in GUI speed and memory consumption is probably limited + only by the Output Window implementation. +
++ No special behavior. +
++ No. +
++ No. +
++ No, but the implementation may. +
++ No. +
++ No. +
++ No. +
++ No. +
++ No. +
++ No. +
++ * Methods of this class can be called in any thread. + *
+ * + * @author jhavlin + */ +public abstract class Fold { + + static final Fold UNSUPPORTED = new Fold() { + + @Override + public void setExpanded(boolean expanded) { + } + + @Override + void endFold() { + } + }; + + private Fold() { + } + + staticIOProvider.getDefault().getIO("MyTab", false) (pass true if
+ * there may be an existing tab with the same name and you want to write to a
+ * new tab).
+ *
+ * + * Methods of this class can be called in any thread. + *
+ * + * @author Jesse Glick, Jaroslav Havlin + */ +public abstract class IOProvider { + + private IOProvider() { + } + + /** + * Get the default I/O provider. + *+ * Normally this is taken from {@link Lookup#getDefault} but if there is no + * instance in lookup, a fallback instance is created which just uses the + * standard system I/O streams. This is useful for unit tests and perhaps + * for standalone usage of various libraries. + *
+ * + * @return The default instance (never null). + */ + @NonNull + public static IOProvider getDefault() { + InputOutputProvider def + = Lookup.getDefault().lookup(InputOutputProvider.class); + if (def != null) { + return wrapProvider(def); + } else { + return wrapProvider(new Trivial()); + } + } + + private staticInputOutput is
+ * returned, else an existing InputOutput of the same name may
+ * be returned.
+ * @return An InputOutput instance for accessing the new tab.
+ * @see InputOutput
+ */
+ @NonNull
+ public abstract InputOutput getIO(@NonNull String name, boolean newIO);
+
+ /**
+ * Get a named instance of InputOutput, which represents an output tab in
+ * the output window. Streams for reading/writing can be accessed via
+ * getters on the returned instance.
+ *
+ * @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 InputOutput
+ */
+ @NonNull
+ public abstract InputOutput getIO(@NonNull String name, boolean newIO,
+ @NonNull Lookup lookup);
+
+ /**
+ * Implementation of IOProvider that uses {@link InputOutputProvider} SPI
+ * internally.
+ *
+ * @param 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+ * This is a shorthand for {@code IOProvider.getDefault().getIO(...)}. + *
+ * + * @param name A localised display name for the tab. + * @param newIO If true, a newInputOutput 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 newInputOutput 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 + * 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
+ * Although using wide range of custom RGB colors may be tempting, predefined + * colors are recommended, as they can be configured to respect GUI theme in + * use. + *
+ * + * @author jhavlin + */ +public abstract class OutputColor { + + + private final OutputColorType type; + private static final OutputColor CLR_WARNING = new TypeColor(OutputColorType.WARNING); + private static final OutputColor CLR_FAILURE = new TypeColor(OutputColorType.FAILURE); + private static final OutputColor CLR_DEBUG = new TypeColor(OutputColorType.DEBUG); + private static final OutputColor CLR_SUCCESS = new TypeColor(OutputColorType.SUCCESS); + + static { + OutputColorAccessor.setDefault(new OutputColorAccessorImpl()); + } + + private OutputColor(OutputColorType type) { + this.type = type; + } + + OutputColorType getType() { + return type; + } + + /** + * Warning text color. + * + * @return Predefined color for text of type "warning". + */ + @NonNull + public static OutputColor warning() { + return CLR_WARNING; + } + + /** + * Failure text color. + * + * @return Predefined color for text of type "failure". + */ + @NonNull + public static OutputColor failure() { + return CLR_FAILURE; + } + + /** + * Debug text color. + * + * @return Predefined color for text of type "debug". + */ + @NonNull + public static OutputColor debug() { + return CLR_DEBUG; + } + + /** + * Success text color. + * + * @return Predefined color for text of type "success". + */ + @NonNull + public static OutputColor success() { + return CLR_SUCCESS; + } + + /** + * Arbitrary constant RGB color. + * + *+ * Please note that it is recommended to use colors for predefined text + * types, which can respect color theme used by the GUI. + *
+ * + * @param r The red component, in the range (0 - 255). + * @param g The green component, in the range (0 - 255). + * @param b The blue component, in the range (0 - 255). + * + * @return Color specified for a constant RGB value. + * @throws IllegalArgumentException If some of color components is out of + * range. + */ + @NonNull + public static OutputColor rgb(int r, int g, int b) { + checkColorComponentRange("r", r); + checkColorComponentRange("g", g); + checkColorComponentRange("b", b); + int value = ((r & 0xFF) << 16) + | ((g & 0xFF) << 8) + | ((b & 0xFF)); + return rgb(value); + } + + /** + * Arbitrary constant RGB color. Creates an opaque sRGB color with the + * specified combined RGB value consisting of the red component in bits + * 16-23, the green component in bits 8-15, and the blue component in bits + * 0-7. + * + *+ * Please note that it is recommended to use colors for predefined text + * types, which can respect color theme used by the GUI. + *
+ * + * @param rgbValue The combined RGB components. + * + * @return Color specified for a constant RGB value. + */ + @NonNull + public static OutputColor rgb(int rgbValue) { + return new RgbColor(rgbValue); + } + + private static void checkColorComponentRange(String name, + int colorComponent) { + + if (colorComponent < 0 || colorComponent > 255) { + throw new IllegalArgumentException("Color component " + name//NOI18N + + " is out of range (0 - 255): " + colorComponent); //NOI18N + } + } + + private static class TypeColor extends OutputColor { + + public TypeColor(OutputColorType type) { + super(type); + } + } + + @SuppressWarnings("PackageVisibleInnerClass") + static class RgbColor extends OutputColor { + + private final int value; + + public RgbColor(int value) { + super(OutputColorType.RGB); + this.value = value; + } + + public int getRGB() { + return value; + } + } +} diff --git a/api.io/src/org/netbeans/api/io/OutputColorAccessorImpl.java b/api.io/src/org/netbeans/api/io/OutputColorAccessorImpl.java new file mode 100644 --- /dev/null +++ b/api.io/src/org/netbeans/api/io/OutputColorAccessorImpl.java @@ -0,0 +1,68 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2014 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2014 Sun Microsystems, Inc. + */ +package org.netbeans.api.io; + +import org.netbeans.modules.io.OutputColorAccessor; +import org.netbeans.spi.io.support.OutputColorType; + +/** + * Implementation of accessor that enables retrieving information about output + * colors in SPI. + * + * @author jhavlin + */ +class OutputColorAccessorImpl extends OutputColorAccessor{ + + @Override + public OutputColorType getType(OutputColor color) { + return color.getType(); + } + + @Override + public int getRgb(OutputColor color) { + if (color instanceof OutputColor.RgbColor) { + return ((OutputColor.RgbColor) color).getRGB(); + } else { + throw new IllegalArgumentException("Not an RGB color."); //NOI18N + } + } +} diff --git a/api.io/src/org/netbeans/api/io/OutputWriter.java b/api.io/src/org/netbeans/api/io/OutputWriter.java new file mode 100644 --- /dev/null +++ b/api.io/src/org/netbeans/api/io/OutputWriter.java @@ -0,0 +1,366 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2014 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2014 Sun Microsystems, Inc. + */ +package org.netbeans.api.io; + +import java.io.IOException; +import java.io.PrintWriter; +import java.io.Writer; +import java.util.Collections; +import java.util.EnumSet; +import java.util.Locale; +import java.util.Set; +import org.netbeans.api.annotations.common.NullAllowed; +import org.netbeans.spi.io.InputOutputProvider; + +/** + * Extended {@link PrintWriter} for writing into output window or similar output + * GUI component. It can support features like color printing, hyperlinks, or + * folding. + * + *+ * Methods of this class can be called in any thread. + *
+ * + * @author jhavlin + */ +public abstract class OutputWriter extends PrintWriter { + + private OutputWriter() { + super(new DummyWriter()); + } + + /** + * Get current position in the output stream. + * + * @return The position. + */ + public abstract Position getCurrentPosition(); + + /** + * Start a new fold. If a fold already exists, a nested fold will be + * created. + * + * @param expanded True if the fold should be expanded by default, false if + * it should be collapsed. + * + * @return The fold handle. + */ + public abstract Fold startFold(boolean expanded); + + /** + * Finish a fold. If it contains some unfinished nested folds, they will be + * finished as well. + * + * @param fold The fold to finish. + */ + public abstract void endFold(Fold fold); + + public abstract void print(String s, Hyperlink link, OutputColor color); + + public abstract void print(String s, Hyperlink link); + + public abstract void print(String s, OutputColor color); + + public abstract void println(String s, Hyperlink link, OutputColor color); + + public abstract void println(String s, Hyperlink link); + + public abstract void println(String s, OutputColor color); + + static+ * Methods of this class can be called in any thread. + *
+ * + * @author jhavlin + */ +public abstract class Position { + + static final Position UNSUPPORTED = new Position() { + + @Override + public void scrollTo() { + } + }; + + private Position() { + } + + /** + * Scroll to this position. + */ + public abstract void scrollTo(); + + static+ * 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+ * 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+ * 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); +} diff --git a/api.io/src/org/netbeans/spi/io/support/HyperlinkType.java b/api.io/src/org/netbeans/spi/io/support/HyperlinkType.java new file mode 100644 --- /dev/null +++ b/api.io/src/org/netbeans/spi/io/support/HyperlinkType.java @@ -0,0 +1,54 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2014 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2014 Sun Microsystems, Inc. + */ +package org.netbeans.spi.io.support; + +/** + * Type of the hyperlink. + *+ * Note: New items may be added in the future. + *
+ * + * @author jhavlin + */ +public enum HyperlinkType { + FROM_RUNNABLE +} diff --git a/api.io/src/org/netbeans/spi/io/support/Hyperlinks.java b/api.io/src/org/netbeans/spi/io/support/Hyperlinks.java new file mode 100644 --- /dev/null +++ b/api.io/src/org/netbeans/spi/io/support/Hyperlinks.java @@ -0,0 +1,97 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2014 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2014 Sun Microsystems, Inc. + */ +package org.netbeans.spi.io.support; + +import org.netbeans.api.annotations.common.NonNull; +import org.netbeans.api.io.Hyperlink; +import org.netbeans.modules.io.HyperlinkAccessor; + +/** + * Helper class for accessing information from {@link Hyperlink} objects. + * + * @author jhavlin + */ +public final class Hyperlinks { + + private Hyperlinks() { + } + + /** + * Get hyperlink type. + * + * @param hyperlink The hyperlink to get type of. + * @return The type of the hyperlink. + */ + @NonNull + public static HyperlinkType getType(@NonNull Hyperlink hyperlink) { + return HyperlinkAccessor.getDefault().getType(hyperlink); + } + + /** + * Check whether a hyperlink is important. + * + * @param hyperlink The hyperlink to check. + * + * @return True if the hyperlink has been marked as important, false if it + * is a standard link. + */ + public static boolean isImportant(@NonNull Hyperlink hyperlink) { + return HyperlinkAccessor.getDefault().isImportant(hyperlink); + } + + /** + * Get runnable associated with a hyperlink of type + * {@link HyperlinkType#FROM_RUNNABLE}. + * + * @param hyperlink The hyperlink to get runnable from. + * + * @return A runnable. + * @throws IllegalArgumentException if type of the hyperlink is not + * {@link HyperlinkType#FROM_RUNNABLE}. + * @see #getType(org.netbeans.api.io.Hyperlink) + * @see HyperlinkType + */ + @NonNull + public static Runnable getRunnable(@NonNull Hyperlink hyperlink) { + return HyperlinkAccessor.getDefault().getRunnable(hyperlink); + } +} diff --git a/api.io/src/org/netbeans/spi/io/support/OutputColorType.java b/api.io/src/org/netbeans/spi/io/support/OutputColorType.java new file mode 100644 --- /dev/null +++ b/api.io/src/org/netbeans/spi/io/support/OutputColorType.java @@ -0,0 +1,54 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2014 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2014 Sun Microsystems, Inc. + */ +package org.netbeans.spi.io.support; + +/** + * Type of the color - static (rgb) or dynamic. + *+ * Note: New items may be added in the future. + *
+ * + * @author jhavlin + */ +public enum OutputColorType { + WARNING, FAILURE, DEBUG, SUCCESS, RGB +} diff --git a/api.io/src/org/netbeans/spi/io/support/OutputColors.java b/api.io/src/org/netbeans/spi/io/support/OutputColors.java new file mode 100644 --- /dev/null +++ b/api.io/src/org/netbeans/spi/io/support/OutputColors.java @@ -0,0 +1,83 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2014 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2014 Sun Microsystems, Inc. + */ +package org.netbeans.spi.io.support; + +import org.netbeans.api.annotations.common.NonNull; +import org.netbeans.api.io.OutputColor; +import org.netbeans.modules.io.OutputColorAccessor; + +/** + * Helper class for accessing information from {@link OutputColor} objects. + * + * @author jhavlin + */ +public final class OutputColors { + + private OutputColors() { + } + + /** + * Get type of a color. + * + * @param color The color to get type of. + * @return Type of color. + */ + @NonNull + public static OutputColorType getType(@NonNull OutputColor color) { + return OutputColorAccessor.getDefault().getType(color); + } + + /** + * Get RGB value for an {@link OutputColor} specified for a constant RGB + * color (type {@link OutputColorType#RGB}). + * + * @param color The color to get RGB value for. + * + * @return RGB value of the color. + * @throws IllegalArgumentException if the color is not of type + * {@link OutputColorType#RGB}. + */ + public static int getRGB(OutputColor color) { + return OutputColorAccessor.getDefault().getRgb(color); + } + +} diff --git a/api.io/test/unit/src/org/netbeans/api/io/HyperlinkTest.java b/api.io/test/unit/src/org/netbeans/api/io/HyperlinkTest.java new file mode 100644 --- /dev/null +++ b/api.io/test/unit/src/org/netbeans/api/io/HyperlinkTest.java @@ -0,0 +1,82 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2014 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2014 Sun Microsystems, Inc. + */ +package org.netbeans.api.io; + +import static org.junit.Assert.*; +import org.junit.Test; +import org.netbeans.spi.io.support.HyperlinkType; +import org.netbeans.spi.io.support.Hyperlinks; + +/** + * + * @author jhavlin + */ +public class HyperlinkTest { + + @Test + public void testOnClickLink() { + + final boolean[] invoked = new boolean[1]; + Hyperlink h = Hyperlink.from(new Runnable() { + + @Override + public void run() { + invoked[0] = true; + } + }); + assertTrue(Hyperlinks.getType(h) == HyperlinkType.FROM_RUNNABLE); + assertFalse(h.isImportant()); + assertNotNull(Hyperlinks.getRunnable(h)); + Hyperlinks.getRunnable(h).run(); + assertTrue("The passed code should be invoked", invoked[0]); + } + + @Test + public void testOnClickLinkImportant() { + Hyperlink h = Hyperlink.from(new Runnable() { + @Override + public void run() { + } + }, true); + assertTrue(h.isImportant()); + } +} diff --git a/api.io/test/unit/src/org/netbeans/api/io/IOProviderTest.java b/api.io/test/unit/src/org/netbeans/api/io/IOProviderTest.java new file mode 100644 --- /dev/null +++ b/api.io/test/unit/src/org/netbeans/api/io/IOProviderTest.java @@ -0,0 +1,286 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 2014 Oracle and/or its affiliates. All rights reserved. + * + * Oracle and Java are registered trademarks of Oracle and/or its affiliates. + * Other names may be trademarks of their respective owners. + * + * The contents of this file are subject to the terms of either the GNU + * General Public License Version 2 only ("GPL") or the Common + * Development and Distribution License("CDDL") (collectively, the + * "License"). You may not use this file except in compliance with the + * License. You can obtain a copy of the License at + * http://www.netbeans.org/cddl-gplv2.html + * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the + * specific language governing permissions and limitations under the + * License. When distributing the software, include this License Header + * Notice in each file and include the License file at + * nbbuild/licenses/CDDL-GPL-2-CP. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the + * License Header, with the fields enclosed by brackets [] replaced by + * your own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * If you wish your version of this file to be governed by only the CDDL + * or only the GPL Version 2, indicate your decision by adding + * "[Contributor] elects to include this software in this distribution + * under the [CDDL or GPL Version 2] license." If you do not indicate a + * single choice of license, a recipient has the option to distribute + * your version of this file under either the CDDL, the GPL Version 2 or + * to extend the choice of license to its licensees as provided above. + * However, if you add GPL Version 2 code and therefore, elected the GPL + * Version 2 license, then the option applies only if the new code is + * made subject to such option by the copyright holder. + * + * Contributor(s): + * + * Portions Copyrighted 2014 Sun Microsystems, Inc. + */ +package org.netbeans.api.io; + +import java.io.PrintWriter; +import java.io.Reader; +import java.io.StringReader; +import java.io.StringWriter; +import java.util.ArrayList; +import java.util.Set; +import org.junit.Test; +import static org.junit.Assert.*; +import org.netbeans.junit.MockServices; +import org.netbeans.spi.io.InputOutputProvider; +import org.openide.util.Lookup; +import org.openide.util.lookup.Lookups; + +/** + * + * @author jhavlin + */ +public class IOProviderTest { + + public IOProviderTest() { + } + + @Test + public void useCase1() { + InputOutput io = IOProvider.getDefault().getIO("UseCase1", true); + io.getOut().println("This is a simple output"); + io.getOut().close(); + } + + @Test + public void useCase2() { + InputOutput io = IOProvider.getDefault().getIO("UseCase2", false); + io.getOut().print("A line containing a "); + io.getOut().print("hyperlink", Hyperlink.from(new Runnable() { + + @Override + public void run() { + // some action + } + })); + io.getOut().println(" for a URI."); + io.getOut().close(); + } + + @Test + public void useCase3() { + InputOutput io = IOProvider.getDefault().getIO("UseCase3", true); + io.getOut().print("A line containing a "); + io.getOut().print("hyperlink", Hyperlink.from(new Runnable() { + @Override + public void run() { + System.gc(); + } + })); + io.getOut().println(" for invokation of custom code."); + io.getOut().close(); + } + + @Test + public void useCase4() { + InputOutput io = IOProvider.getDefault().getIO("UseCase4", true); + io.getOut().println("Let's print some info", OutputColor.debug()); + io.getOut().println("or warning with appropriate color", + OutputColor.warning()); + io.getOut().println("Maybe also text with custom reddish color", + OutputColor.rgb(255, 16, 16)); + io.getOut().close(); + } + + @Test + public void useCase5() { + InputOutput io = IOProvider.getDefault().getIO("UseCase5", true); + io.getOut().println("Let's print some text"); + io.getErr().println("and reset the pane immediately."); + io.reset(); + io.getOut().println("The pane is now empty and we can reuse it simply"); + io.getOut().close(); + } + + @Test + public void testTrivialImplementationAlwaysAvailable() { + assertEquals("Trivial", IOProvider.getDefault().getId()); + assertEquals("Trivial", IOProvider.get("Trivial").getId()); + assertEquals("Trivial", IOProvider.get("Another").getId()); + } + + @Test + public void testGetFromLookup() { + MockServices.setServices(MockInputOutputProvider.class); + try { + assertEquals("mock", IOProvider.getDefault().getId()); + assertEquals("mock", IOProvider.get("mock").getId()); + assertEquals("mock", IOProvider.get("wrong").getId()); + } finally { + MockServices.setServices(); + } + } + + @Test + public void testAllMethodsAreDelegatedToSPI() { + MockServices.setServices(MockInputOutputProvider.class); + try { + IOProvider.getDefault().getIO("test1", true); + Lookup lkp = IOProvider.getDefault() + .getIO("test1", false, Lookup.EMPTY).getLookup(); + CalledMethodList list = lkp.lookup(CalledMethodList.class); + assertEquals("getIO", list.get(0)); + assertEquals("getIO", list.get(1)); + assertEquals("getIOLookup", list.get(2)); + assertEquals(3, list.size()); + } finally { + MockServices.setServices(); + } + } + + @SuppressWarnings("PackageVisibleInnerClass") + static class CalledMethodList extends ArrayList+ As new API and SPI for output windows has been introduced, it is + useful to have a convenient way for implementators of the original + API to support the new API as well. The BridgingIOProvider class + implements both SPIs, and its JavaDoc explains how to use it. +
++ * This class is useful if you have a custom implementation of Output Window, + * which uses SPI contained in this module ({@link IOProvider} and related + * interfaces), and want to your implementation also accessible via the new I/O + * API in module api.io. + *
+ *+ * To start supporting the new API: + *
+ *
+ *
+ * @ServiceProviders({
+ * @ServiceProvider(service=IOProvider.class, position=900),
+ * @ServiceProvider(service=InputOutputProvider.class, position=900)
+ * })
+ * public final class MyIOProvider extends BridgingIOProvider { ... }
+ *
+ *