001: /*
002: * The contents of this file are subject to the terms of the Common Development
003: * and Distribution License (the License). You may not use this file except in
004: * compliance with the License.
005: *
006: * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
007: * or http://www.netbeans.org/cddl.txt.
008: *
009: * When distributing Covered Code, include this CDDL Header Notice in each file
010: * and include the License file at http://www.netbeans.org/cddl.txt.
011: * If applicable, add the following below the CDDL Header, with the fields
012: * enclosed by brackets [] replaced by your own identifying information:
013: * "Portions Copyrighted [year] [name of copyright owner]"
014: *
015: * The Original Software is NetBeans. The Initial Developer of the Original
016: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
017: * Microsystems, Inc. All Rights Reserved.
018: */
019:
020: package org.netbeans.api.project.libraries;
021:
022: import java.awt.Component;
023: import java.beans.PropertyChangeListener;
024: import java.io.IOException;
025: import java.util.Set;
026:
027: /**
028: * Visual picker for libraries.
029: * @since org.netbeans.modules.project.libraries/1 1.16
030: */
031: public final class LibraryChooser {
032:
033: private LibraryChooser() {
034: }
035:
036: /**
037: * Create a chooser showing libraries from given library manager and let the
038: * user to pick some.
039: * @param manager manager; can be null in which case global libraries are listed
040: * @param filter optional libraries filter; null for no filtering
041: * @param handler handler to perform library importing; can be null in which case
042: * import will not be allowed in UI
043: * @return a nonempty set of libraries that were selected, or null if the dialog was cancelled
044: */
045: public static Set<Library> showDialog(LibraryManager manager,
046: Filter filter, LibraryImportHandler handler) {
047: return LibraryChooserGUI.showChooser(manager, filter, handler,
048: true);
049: }
050:
051: /**
052: * Create a picker as an embeddable panel.
053: * Might be used in a wizard, for example.
054: * @param manager library manager to use or null for global libraries
055: * @param filter optional libraries filter; null for no filtering
056: * @return a panel controller
057: */
058: public static Panel createPanel(LibraryManager manager,
059: Filter filter) {
060: return LibraryChooserGUI.createPanel(manager, filter);
061: }
062:
063: /**
064: * Filter for use by {@link LibraryChooser#createPanel()} or
065: * {@link LibraryChooser#showDialog()}.
066: */
067: public interface Filter {
068:
069: /**
070: * Accepts or rejects a library.
071: * @param library a library found in one of the managers
072: * @return true to display, false to hide
073: */
074: boolean accept(Library library);
075:
076: }
077:
078: /**
079: * Represents operations permitted by {@link #createPanel}.
080: * Not to be implemented by foreign code (methods may be added in the future).
081: */
082: public interface Panel {
083:
084: /**
085: * Produces the actual component you can display.
086: * @return an embeddable GUI component
087: */
088: Component getVisualComponent();
089:
090: /**
091: * Gets the set of libraries which are currently selected.
092: * @return a (possibly empty) set of libraries
093: */
094: Set<Library> getSelectedLibraries();
095:
096: /**
097: * Property fired when {@link #getSelectedLibraries} changes.
098: * Do not expect the old and new values to be non-null.
099: */
100: String PROP_SELECTED_LIBRARIES = "selectedLibraries"; // NOI18N
101:
102: /**
103: * Add a listener for {@link #PROP_SELECTED_LIBRARIES}.
104: * @param listener the listener to add
105: */
106: void addPropertyChangeListener(PropertyChangeListener listener);
107:
108: /**
109: * Remove a listener.
110: * @param listener the listener to remove
111: */
112: void removePropertyChangeListener(
113: PropertyChangeListener listener);
114:
115: }
116:
117: /**
118: * Handler for library importing. The handler is used from library chooser
119: * UI in order to import global library to sharable libraries location. A
120: * library is only imported if there is no library with the same library
121: * name in destination library manager.
122: */
123: public interface LibraryImportHandler {
124:
125: /**
126: * Implementation is expected to copy given global library to
127: * sharable libraries location, that is to library manager the library
128: * chooser was created for.
129: *
130: * @param library library to copy
131: * @return newly created library
132: * @throws java.io.IOException any IO failure
133: * @throws IllegalArgumentException if there already exists library
134: * with this name
135: */
136: Library importLibrary(Library library) throws IOException;
137: }
138:
139: }
|