<change id="project-libraries">

        <api name="general"/>

        <summary>Support for project libraries</summary>

        <version major="1" minor="17"/>

        <date day="22" month="1" year="2008"/>

        <author login="jglick"/>

        <compatibility addition="yes" deprecation="yes">

            <p>

                <code>LibraryManager.addLibrary</code> will not work with areas,

                so it was deprecated in favor of the new <code>createLibrary</code>.

            </p>

            <p>

                Code which obtained a <code>Library</code> of arbitrary origin,

                and then assumed it could refer to that library henceforth by name only,

                will not work with project libraries.

                The simplest persistent identifier for a new-style library is pair of name

                and URL of manager (null for the default manager).

            </p>

        </compatibility>

        <description>

            <p>

                There is a new API and SPI for project libraries

                (or, more generally, libraries with specific storage locations).

                <code>ArealLibraryProvider</code>,

                and <code>LibraryStorageArea</code> are new, as are methods

                <code>Library.getManager</code>,

                <code>Library.getRawContent(String)</code>

                <code>LibraryManager.getDisplayName</code>,

                <code>LibraryManager.getLocation</code>,

                <code>LibraryManager.createLibrary</code>,

                <code>LibraryManager.forLocation</code>, and

                <code>LibraryManager.getOpenManagers</code>.

                (<code>LibraryProvider</code> was also generified.)

                <code>LibrariesSupport</code> has few additional helper methods.

            </p>

            <p>

                There's also new methods and classes for UI customizations of Libraries, eg.

                <code>LibrariesCustomizer.showCreateNewLibraryCustomizer(LibraryManager)</code>,

                <code>LibrariesCustomizer.showCustomizer(Library, LibraryManager)</code>,

                <code>LibrariesCustomizer.showSingleLibraryCustomizer(Library)</code>,

                and <code>LibraryChooser</code> class.

            </p>

        </description>

        <class package="org.netbeans.api.project.libraries" name="LibraryManager"/>

        <class package="org.netbeans.api.project.libraries" name="Library"/>

        <class package="org.netbeans.api.project.libraries" name="LibraryChooser"/>

        <class package="org.netbeans.api.project.libraries" name="LibrariesCustomizer"/>

        <class package="org.netbeans.spi.project.libraries" name="LibraryProvider"/>

        <class package="org.netbeans.spi.project.libraries" name="ArealLibraryProvider"/>

        <class package="org.netbeans.spi.project.libraries" name="LibraryStorageArea"/>

        <class package="org.netbeans.spi.project.libraries.support" name="LibrariesSupport"/>

        <issue number="44035"/>

    </change>

import javax.swing.border.EmptyBorder;

import org.netbeans.modules.project.libraries.LibraryTypeRegistry;

import org.netbeans.modules.project.libraries.ui.LibrariesModel;

import org.netbeans.modules.project.libraries.ui.NewLibraryPanel;

import org.netbeans.spi.project.libraries.LibraryImplementation;

import org.netbeans.spi.project.libraries.LibraryStorageArea;

import org.netbeans.spi.project.libraries.LibraryTypeProvider;

        return showCustomizer(activeLibrary, LibraryManager.getDefault());

    }

    /**

     * Show customizer for creating new library in the given library manager.

     * @param manager manager

     * @return created persisted library or null if user cancelled operation

     * @since org.netbeans.modules.project.libraries/1 1.16

     */

    public static Library showCreateNewLibraryCustomizer(LibraryManager manager) {                                             

        if (manager == null) {

            manager = LibraryManager.getDefault();

        }

        LibraryStorageArea area = manager.getArea();

        if (area == null) {

            area = LibrariesModel.GLOBAL_AREA;

        }

import org.netbeans.spi.project.libraries.support.LibrariesSupport;

        this.manager = manager;

    /**

     * Gets the associated library manager.

     * @return the manager (may be the "default" global manager, or a local manager)

     * @since org.netbeans.modules.project.libraries/1 1.15

     */

    public LibraryManager getManager() {

        return manager;

    }

    /**

     * Access typed library data. Any relative URL provided by SPI is made absolute

     * before being passed to client. See {@link #getRawContent} if you need raw library data.

     * <p>

     * The contents are defined by SPI providers and identified

     * by the <a href="package-summary.html#volumeType">volume types</a>. For example the j2se library supports the following

     * volume types: classpath - the library classpath roots, src - the library sources, javadoc - the library javadoc.

     * Your module must have contract with a particular provider's module to be able to query it effectively.

     * </p>

     *

     * @param volumeType which resources to return.

     * @return path of URLs of given type (possibly empty but never <code>null</code>)

     */

    public List<URL> getContent(final String volumeType) {

        List<URL> urls = this.impl.getContent (volumeType);

        List<URL> resolvedUrls = new ArrayList<URL>(urls.size());

        for (URL u : urls) {

            resolvedUrls.add(LibrariesSupport.resolveLibraryEntryURL(manager.getLocation(), u));

        }

        return resolvedUrls;

    } // end getContent

    @Override

    public String toString() {

        return "Library[" + getName() + "]"; // NOI18N

    }

/*

 * The contents of this file are subject to the terms of the Common Development

 * and Distribution License (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.html

 * or http://www.netbeans.org/cddl.txt.

 *

 * When distributing Covered Code, include this CDDL Header Notice in each file

 * and include the License file at http://www.netbeans.org/cddl.txt.

 * If applicable, add the following below the CDDL Header, with the fields

 * enclosed by brackets [] replaced by your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun

 * Microsystems, Inc. All Rights Reserved.

 */

package org.netbeans.api.project.libraries;

import java.awt.Component;

import java.beans.PropertyChangeListener;

import java.io.File;

import java.io.IOException;

import java.util.Set;

import javax.swing.JFileChooser;

import org.openide.filesystems.FileUtil;

import org.openide.util.Exceptions;

import org.openide.util.NbBundle;

/**

 * Visual picker for libraries.

 * @since org.netbeans.modules.project.libraries/1 1.16

 */

public final class LibraryChooser {

    private LibraryChooser() {

    }

    /**

     * Create a chooser showing libraries from given library manager and let the

     * user to pick some.

     * @param manager manager; can be null in which case global libraries are listed

     * @param filter optional libraries filter; null for no filtering

     * @param handler handler to perform library importing; can be null in which case

     *  import will not be allowed in UI

     * @return a nonempty set of libraries that were selected, or null if the dialog was cancelled

     */

    public static Set<Library> showDialog(LibraryManager manager, Filter filter, LibraryImportHandler handler) {

        return LibraryChooserGUI.showChooser(manager, filter, handler, true);

    }

    /**

     * Create a picker as an embeddable panel.

     * Might be used in a wizard, for example.

     * @param manager library manager to use or null for global libraries

     * @param filter optional libraries filter; null for no filtering

     * @return a panel controller

     */

    public static Panel createPanel(LibraryManager manager, Filter filter) {

        return LibraryChooserGUI.createPanel(manager, filter);

    }

    /**

     * Filter for use by {@link LibraryChooser#createPanel()} or 

     * {@link LibraryChooser#showDialog()}.

     */

    public interface Filter {

        /**

         * Accepts or rejects a library.

         * @param library a library found in one of the managers

         * @return true to display, false to hide

         */

        boolean accept(Library library);

    }

    /**

     * Represents operations permitted by {@link #createPanel}.

     * Not to be implemented by foreign code (methods may be added in the future).

     */

    public interface Panel {

        /**

         * Produces the actual component you can display.

         * @return an embeddable GUI component

         */

        Component getVisualComponent();

        /**

         * Gets the set of libraries which are currently selected.

         * @return a (possibly empty) set of libraries

         */

        Set<Library> getSelectedLibraries();

        /**

         * Property fired when {@link #getSelectedLibraries} changes.

         * Do not expect the old and new values to be non-null.

         */

        String PROP_SELECTED_LIBRARIES = "selectedLibraries"; // NOI18N

        /**

         * Add a listener for {@link #PROP_SELECTED_LIBRARIES}.

         * @param listener the listener to add

         */

        void addPropertyChangeListener(PropertyChangeListener listener);

        /**

         * Remove a listener.

         * @param listener the listener to remove

         */

        void removePropertyChangeListener(PropertyChangeListener listener);

    }

    /**

     * Handler for library importing. The handler is used from library chooser

     * UI in order to import global library to sharable libraries location. A 

     * library is only imported if there is no library with the same library

     * name in destination library manager.

     */

    public interface LibraryImportHandler {

        /**

         * Implementation is expected to copy given global library to 

         * sharable libraries location, that is to library manager the library

         * chooser was created for.

         * 

         * @param library library to copy

         * @return newly created library

         * @throws java.io.IOException any IO failure

         * @throws IllegalArgumentException if there already exists library 

         *  with this name

         */

        Library importLibrary(Library library) throws IOException;

    }

}

/*

 * The contents of this file are subject to the terms of the Common Development

 * and Distribution License (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.html

 * or http://www.netbeans.org/cddl.txt.

 *

 * When distributing Covered Code, include this CDDL Header Notice in each file

 * and include the License file at http://www.netbeans.org/cddl.txt.

 * If applicable, add the following below the CDDL Header, with the fields

 * enclosed by brackets [] replaced by your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun

 * Microsystems, Inc. All Rights Reserved.

 */

package org.netbeans.api.project.libraries;

import java.awt.BorderLayout;

import java.awt.Component;

import java.awt.Image;

import java.beans.PropertyChangeEvent;

import java.beans.PropertyChangeListener;

import java.beans.PropertyVetoException;

import java.io.IOException;

import java.text.Collator;

import java.util.ArrayList;

import java.util.Collection;

import java.util.Collections;

import java.util.Comparator;

import java.util.HashSet;

import java.util.List;

import java.util.Set;

import javax.swing.JButton;

import javax.swing.JPanel;

import javax.swing.border.EmptyBorder;

import org.openide.DialogDescriptor;

import org.openide.DialogDisplayer;

import org.openide.NotifyDescriptor;

import org.openide.explorer.ExplorerManager;

import org.openide.filesystems.Repository;

import org.openide.loaders.DataFolder;

import org.openide.nodes.AbstractNode;

import org.openide.nodes.Children;

import org.openide.nodes.Node;

import org.openide.nodes.NodeNotFoundException;

import org.openide.nodes.NodeOp;

import org.openide.util.Exceptions;

import org.openide.util.HelpCtx;

import org.openide.util.NbBundle;

import org.openide.util.lookup.Lookups;

class LibraryChooserGUI extends JPanel implements ExplorerManager.Provider, HelpCtx.Provider, LibraryChooser.Panel {

    private final LibraryManager manager;

    private final LibraryChooser.Filter filter;

    private final ExplorerManager explorer;

    private LibraryChooser.LibraryImportHandler importHandler;

    private LibraryChooserGUI(LibraryManager manager, LibraryChooser.Filter filter, 

            LibraryChooser.LibraryImportHandler importHandler) {

        if (manager == null) {

            manager = LibraryManager.getDefault();

        }

        this.manager = manager;

        this.filter = filter;

        this.importHandler = importHandler;

        explorer = new ExplorerManager();

        initComponents();

        tree.setDefaultActionAllowed(false);

    }

    public static LibraryChooser.Panel createPanel(LibraryManager manager, 

            LibraryChooser.Filter filter) {

        LibraryChooserGUI l = new LibraryChooserGUI(manager, filter, null);

        l.configureForEmbedded();

        return l;

    }

    public static Set<Library> showChooser(LibraryManager manager, LibraryChooser.Filter filter, 

            LibraryChooser.LibraryImportHandler handler, boolean addOperation) {

        LibraryChooserGUI l = new LibraryChooserGUI(manager, filter, handler);

        return l.showDialog(addOperation);

    }

    private Set<Library> showDialog(boolean addOperatation) {

        // show manage button only in embedded panel:

        manageLibrariesButton.setVisible(false);

        // import enabled only for non-global library manager

        importButton.setVisible(manager.getLocation() != null && importHandler != null);

        JPanel inset = new JPanel(new BorderLayout());

        inset.setBorder(new EmptyBorder(12,12,0,12));

        inset.add(this);

        String title;

        String buttonLabel;

        if (addOperatation) {

            title = NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.add.title");

            buttonLabel = NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.add.button");

        } else {

            title = NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.import.title");

            buttonLabel = NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.import.button");

            createButton.setVisible(false);

        }

        DialogDescriptor dd = new DialogDescriptor(inset, title);

        dd.setModal(true);

        final JButton add = new JButton(buttonLabel);

        add.setEnabled(false);

        add.setDefaultCapable(true);

        explorer.addPropertyChangeListener(new PropertyChangeListener() {

           public void propertyChange(PropertyChangeEvent evt) {

               add.setEnabled(!getSelectedLibraries().isEmpty());

           }

        });

        dd.setOptions(new Object[] {add, NotifyDescriptor.CANCEL_OPTION});

        dd.setClosingOptions(new Object[] {add, NotifyDescriptor.CANCEL_OPTION});

        if (DialogDisplayer.getDefault().notify(dd) == add) {

            Set<Library> selection = getSelectedLibraries();

            assert !selection.isEmpty();

            return selection;

        } else {

            return null;

        }

    }

    private void configureForEmbedded() {

        explorer.addPropertyChangeListener(new PropertyChangeListener() {

           public void propertyChange(PropertyChangeEvent evt) {

               firePropertyChange(PROP_SELECTED_LIBRARIES, null, null);

           }

        });

        createButton.setVisible(false);

        importButton.setVisible(false);

    }

    public Set<Library> getSelectedLibraries() {

        Set<Library> s = new HashSet<Library>();

        for (Node n : explorer.getSelectedNodes()) {

            Library l = n.getLookup().lookup(Library.class);

            if (l != null) {

                s.add(l);

            } else {

                return Collections.emptySet();

            }

        }

        return s;

    }

    public Component getVisualComponent() {

        return this;

    }

    public ExplorerManager getExplorerManager() {

        return explorer;

    }

    public HelpCtx getHelpCtx() {

        return new HelpCtx(LibraryChooserGUI.class);

    }

    private void setRootNode() {

        explorer.setRootContext(new AbstractNode(new LibraryManagerChildren()));

        tree.expandAll();

        try {

            if (explorer.getRootContext().getChildren().getNodes(true).length > 0) {

                explorer.setSelectedNodes(new Node[] {explorer.getRootContext().getChildren().getNodes(true)[0]});

            }

        } catch (PropertyVetoException x) {

            Exceptions.printStackTrace(x);

        }

        /* XXX Nothing seems to work to scroll to top; how is it done?

        tree.getViewport().setViewPosition(new Point());

        tree.getViewport().scrollRectToVisible(new Rectangle(0, 0, 1, 1));

         */

        tree.requestFocus();

    }

    @Override

    public void addNotify() {

        super.addNotify();

        setRootNode();

    }

    private class LibraryManagerChildren extends Children.Keys<LibraryManager> {

        @Override

        protected void addNotify() {

            super.addNotify();

            if (manager != null) {

                setKeys(Collections.singleton(manager));

            }

        }

        protected Node[] createNodes(LibraryManager mgr) {

            List<Library> libs = new ArrayList<Library>();

            for (Library lib : mgr.getLibraries()) {

                if (filter == null || filter.accept(lib)) {

                    libs.add(lib);

                }

            }

            if (libs.isEmpty()) {

                return new Node[0];

            } else {

                Collections.sort(libs,new Comparator<Library>() {

                    Collator COLL = Collator.getInstance();

                    public int compare(Library lib1, Library lib2) {

                        return COLL.compare(lib1.getDisplayName(), lib2.getDisplayName());

                    }

                });

                Node n = new AbstractNode(new LibraryChildren(libs)) {

                    Node iconDelegate = DataFolder.findFolder(Repository.getDefault().getDefaultFileSystem().getRoot()).getNodeDelegate();

                    public Image getIcon(int type) {

                        return iconDelegate.getIcon(type);

                    }

                    public Image getOpenedIcon(int type) {

                        return iconDelegate.getOpenedIcon(type);

                    }

                };

                n.setName(mgr.getDisplayName());

                n.setDisplayName(mgr.getDisplayName());

                return new Node[] {n};

            }

        }

    }

    private class LibraryChildren extends Children.Keys<Library> {

        LibraryChildren(List<Library> libs) {

            setKeys(libs);

        }

        protected Node[] createNodes(Library lib) {

            AbstractNode n = new AbstractNode(Children.LEAF, Lookups.singleton(lib));

            n.setName(lib.getName());

            n.setDisplayName(lib.getDisplayName());

            n.setShortDescription(lib.getDescription());

            n.setIconBaseWithExtension("org/netbeans/modules/project/libraries/resources/libraries.gif"); // NOI18N

            return new Node[] {n};

        }

    }

    // <editor-fold defaultstate="collapsed" desc="Generated Code">//GEN-BEGIN:initComponents

    private void initComponents() {

        librariesLabel = new javax.swing.JLabel();

        tree = new org.openide.explorer.view.BeanTreeView();

        createButton = new javax.swing.JButton();

        importButton = new javax.swing.JButton();

        manageLibrariesButton = new javax.swing.JButton();

        librariesLabel.setLabelFor(tree);

        org.openide.awt.Mnemonics.setLocalizedText(librariesLabel, org.openide.util.NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.librariesLabel")); // NOI18N

        tree.setBorder(javax.swing.BorderFactory.createEtchedBorder());

        tree.setPopupAllowed(false);

        tree.setRootVisible(false);

        createButton.setText(org.openide.util.NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.createButton.text")); // NOI18N

        createButton.addActionListener(new java.awt.event.ActionListener() {

            public void actionPerformed(java.awt.event.ActionEvent evt) {

                createButtonActionPerformed(evt);

            }

        });

        importButton.setText(org.openide.util.NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.importButton.text")); // NOI18N

        importButton.addActionListener(new java.awt.event.ActionListener() {

            public void actionPerformed(java.awt.event.ActionEvent evt) {

                importButtonActionPerformed(evt);

            }

        });

        manageLibrariesButton.setText(org.openide.util.NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.manageLibrariesButton.text")); // NOI18N

        manageLibrariesButton.addActionListener(new java.awt.event.ActionListener() {

            public void actionPerformed(java.awt.event.ActionEvent evt) {

                manageLibrariesButtonActionPerformed(evt);

            }

        });

        org.jdesktop.layout.GroupLayout layout = new org.jdesktop.layout.GroupLayout(this);

        this.setLayout(layout);

        layout.setHorizontalGroup(

            layout.createParallelGroup(org.jdesktop.layout.GroupLayout.LEADING)

            .add(librariesLabel)

            .add(org.jdesktop.layout.GroupLayout.TRAILING, layout.createSequentialGroup()

                .add(tree, org.jdesktop.layout.GroupLayout.DEFAULT_SIZE, 257, Short.MAX_VALUE)

                .addPreferredGap(org.jdesktop.layout.LayoutStyle.RELATED)

                .add(layout.createParallelGroup(org.jdesktop.layout.GroupLayout.TRAILING)

                    .add(createButton)

                    .add(importButton)))

            .add(layout.createSequentialGroup()

                .add(manageLibrariesButton)

                .addContainerGap())

        );

        layout.setVerticalGroup(

            layout.createParallelGroup(org.jdesktop.layout.GroupLayout.LEADING)

            .add(layout.createSequentialGroup()

                .add(librariesLabel)

                .addPreferredGap(org.jdesktop.layout.LayoutStyle.RELATED)

                .add(layout.createParallelGroup(org.jdesktop.layout.GroupLayout.LEADING)

                    .add(layout.createSequentialGroup()

                        .add(createButton)

                        .addPreferredGap(org.jdesktop.layout.LayoutStyle.RELATED)

                        .add(importButton))

                    .add(tree, org.jdesktop.layout.GroupLayout.DEFAULT_SIZE, 284, Short.MAX_VALUE))

                .addPreferredGap(org.jdesktop.layout.LayoutStyle.RELATED)

                .add(manageLibrariesButton))

        );

        getAccessibleContext().setAccessibleDescription(org.openide.util.NbBundle.getMessage(LibraryChooserGUI.class, "LibraryChooserGUI.accessibleDescription")); // NOI18N

    }// </editor-fold>//GEN-END:initComponents

    private void manageLibrariesButtonActionPerformed(java.awt.event.ActionEvent evt) {//GEN-FIRST:event_manageLibrariesButtonActionPerformed

        if (LibrariesCustomizer.showCustomizer(null, manager)) {

            setRootNode();

        }

    }//GEN-LAST:event_manageLibrariesButtonActionPerformed

    private void createButtonActionPerformed(java.awt.event.ActionEvent evt) {//GEN-FIRST:event_createButtonActionPerformed

        Library l = LibrariesCustomizer.showCreateNewLibraryCustomizer(manager);

        if (l != null) {

            setRootNode();

            selectLibrary(Collections.singleton(l));

        }

    }//GEN-LAST:event_createButtonActionPerformed

    private void selectLibrary(Collection<Library> libraries) {

        Node root = explorer.getRootContext();

        List<Node> selection = new ArrayList<Node>();

        for (Library lib : libraries) {

            String[] path = {lib.getManager().getDisplayName(), lib.getName()};

            try {

                Node node = NodeOp.findPath(root, path);

                if (node != null) {

                    selection.add(node);

                }

            } catch (NodeNotFoundException e) {

                //Ignore it

            }

        }

        try {

            explorer.setSelectedNodes(selection.toArray(new Node[selection.size()]));

        } catch (PropertyVetoException e) {

            //Ignore it

        }

    }

    private void importButtonActionPerformed(java.awt.event.ActionEvent evt) {//GEN-FIRST:event_importButtonActionPerformed

        Set<Library> libs = showChooser(LibraryManager.getDefault(), 

                new IgnoreAlreadyImportedLibrariesFilter(), null, false);

        if (libs != null) {

            Set<Library> importedLibs = new HashSet<Library>();

            try {

                for (Library lib : libs) {

                    importedLibs.add(importHandler.importLibrary(lib));

                }

            } catch (IOException ex) {

                Exceptions.printStackTrace(ex);

            }

            setRootNode();        

            selectLibrary(importedLibs);

        }

    }//GEN-LAST:event_importButtonActionPerformed

    private class IgnoreAlreadyImportedLibrariesFilter implements LibraryChooser.Filter {

        public boolean accept(Library library) {

            return manager.getLibrary(library.getName()) == null;

        }

    }

    // Variables declaration - do not modify//GEN-BEGIN:variables

    private javax.swing.JButton createButton;

    private javax.swing.JButton importButton;

    private javax.swing.JLabel librariesLabel;

    private javax.swing.JButton manageLibrariesButton;

    private org.openide.explorer.view.BeanTreeView tree;

    // End of variables declaration//GEN-END:variables

}

    /**

     * Property fired when the set of libraries changes.

     */

     * @deprecated Use {@link #createLibrary} instead, as this properly supports local managers.

    @Deprecated

    /**

     * Gets a library manager which loads library definitions from a particular location.

     * There is no guarantee that the return value is the same object from call to call with the same location.

     * @param location any storage location supported by an installed provider

     * @return a library manager whose {@link #getLocation} matches the supplied location

     * @throws IllegalArgumentException if no installed provider is able to manage locations of this kind

     * @see ArealLibraryProvider#loadArea

     * @see ArealLibraryProvider#getLibraries

     * @since org.netbeans.modules.project.libraries/1 1.15

     */

    public static LibraryManager forLocation(URL location) throws IllegalArgumentException {

        for (ArealLibraryProvider alp : Lookup.getDefault().lookupAll(ArealLibraryProvider.class)) {

            LibraryStorageArea area = alp.loadArea(location);

            if (area != null) {

                return new LibraryManager(alp, area);

            }

        }

        throw new IllegalArgumentException(location.toExternalForm());

    }

    /**

     * Gets an unspecified collection of managers which are somehow to be represented as open.

     * For example, library storages referred to from open projects might be returned.

     * You can listen on changes in list of open managers via {@link #addOpenManagersPropertyChangeListener}.

     * There is no guarantee that the non-default managers are the same objects from call to call

     * even if the locations remain the same.

     * @see ArealLibraryProvider#getOpenAreas

     * @return a set of managers, always including at least {@link #getDefault}

     * @since org.netbeans.modules.project.libraries/1 1.15

     */

    public static Collection<LibraryManager> getOpenManagers() {

        List<LibraryManager> managers = new ArrayList<LibraryManager>();

        managers.add(getDefault());

        Set<URL> locations = new HashSet<URL>();

        for (ArealLibraryProvider alp : Lookup.getDefault().lookupAll(ArealLibraryProvider.class)) {

            for (LibraryStorageArea area : LibraryAccessor.getOpenAreas(alp)) {

                if (locations.add(area.getLocation())) {

                    managers.add(new LibraryManager(alp, area));

                }

            }

        }

        for (ArealLibraryProvider alp : Lookup.getDefault().lookupAll(ArealLibraryProvider.class)) {

            for (URL location : LibrariesModel.createdAreas) {

                LibraryStorageArea area = alp.loadArea(location);

                if (area != null) {

                    assert area.getLocation().equals(location) : "Bad location " + area.getLocation() + " does not match " + location + " from " + alp.getClass().getName();

                    if (locations.add(location)) {

                        managers.add(new LibraryManager(alp, area));

                    }

                }

            }

        }

        return managers;

    }

    /**

     * Adds PropertyChangeListener on list of open library managers.

     * The listener is notified when list of open library managers changes via

     * {@link #PROP_OPEN_LIBRARY_MANAGERS}.

     * @param listener to be notified

     */

    public static synchronized void addOpenManagersPropertyChangeListener (PropertyChangeListener listener) {

        assert listener != null;

        if (areaProvidersLookupResult == null) {

            areaProvidersLookupResult = Lookup.getDefault().lookupResult(ArealLibraryProvider.class);

            attachListeners(areaProvidersLookupResult.allInstances());

            areaProvidersLookupResult.addLookupListener(new LookupListener() {

                public void resultChanged(LookupEvent ev) {

                    attachListeners(areaProvidersLookupResult.allInstances());

                }

            });

        }

        openLibraryManagerListListeners.addPropertyChangeListener (listener);

    }

    private static synchronized void attachListeners(Collection<? extends ArealLibraryProvider> currentProviders) {

        for (ArealLibraryProvider provider : currentAreaProviders) {

            provider.removePropertyChangeListener(AREAL_LIBRARY_PROVIDER_LISTENER);

        }

        for (ArealLibraryProvider provider : currentProviders) {

            provider.addPropertyChangeListener(AREAL_LIBRARY_PROVIDER_LISTENER);

        }

        currentAreaProviders = currentProviders;

    }

    /**

     * Removes PropertyChangeListener

     * @param listener

     */

    public static void removeOpenManagersPropertyChangeListener (PropertyChangeListener listener) {

        assert listener != null;

        openLibraryManagerListListeners.removePropertyChangeListener (listener);

    }

    @Override

    public String toString() {

        URL loc = getLocation();

        return "LibraryManager[" + (loc != null ? loc : "default") + "]"; // NOI18N

    }

    LibraryStorageArea getArea() {

        return area;

    }

/*

 * The contents of this file are subject to the terms of the Common Development

 * and Distribution License (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.html

 * or http://www.netbeans.org/cddl.txt.

 *

 * When distributing Covered Code, include this CDDL Header Notice in each file

 * and include the License file at http://www.netbeans.org/cddl.txt.

 * If applicable, add the following below the CDDL Header, with the fields

 * enclosed by brackets [] replaced by your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun

 * Microsystems, Inc. All Rights Reserved.

 */

package org.netbeans.spi.project.libraries;

import java.beans.PropertyChangeListener;

import java.io.IOException;

import java.net.URL;

import java.util.List;

import java.util.Map;

import java.util.Set;

/**

 * Library provider which can define libraries in particular areas.

 * There is no explicit method to save a library; setters on {@link LibraryImplementation} should do this.

 * @param A the type of storage area used by this provider

 * @param L the type of library created by this provider

 * @since org.netbeans.modules.project.libraries/1 1.15

 */

public interface ArealLibraryProvider<A extends LibraryStorageArea, L extends LibraryImplementation> {

    /**

     * Property to fire when {@link #getOpenAreas} might have changed.

     */

    String PROP_OPEN_AREAS = "openAreas"; // NOI18N

    /**

     * Adds a listener to {@link #PROP_OPEN_AREAS}.

     * @param listener a listener to add

     */

    void addPropertyChangeListener(PropertyChangeListener listener);

    /**

     * Removes a listener to {@link #PROP_OPEN_AREAS}.

     * @param listener a listener to remove

     */

    void removePropertyChangeListener(PropertyChangeListener listener);

    /**

     * Gets the runtime type of the area used by this provider.

     * @return the area type

     */

    Class<A> areaType();

    /**

     * Gets the runtime type of the libraries created by this provider.

     * @return the library type

     */

    Class<L> libraryType();

    /**

     * Creates or otherwise picks a storage area interactively.

     * This might actually create a fresh area, or just load an existing one,

     * or even do nothing (and return null).

     * The implementor is free to show a dialog here.

     * @return a new or existing storage area, or null

     */

    A createArea();

    /**

     * Loads a storage area (which may or may exist yet).

     * @param location an abstract storage location which may or may not be recognized by this provider

     * @return an area whose {@link LibraryStorageArea#getLocation} matches the provided location,

     *         or null if this type of location is not recognized by this provider

     */

    A loadArea(URL location);

    /**

     * Looks for areas which should be somehow listed as open.

     * For example, a provider which refers to library areas from project metadata

     * could list all areas referred to from currently open projects.

     * It is <em>not</em> necessary to include areas recently mentioned e.g. by {@link #createArea}.

     * @return a (possibly empty) collection of areas

     */

    Set<A> getOpenAreas();

    /**

     * Gets all libraries defined in a given area.

     * No two libraries in this area may share a given name (as in {@link LibraryImplementation#getName},

     * though it is permitted for libraries from different areas to have the same name.

     * Changes in the set of libraries defined in this area should be fired through {@link LibraryProvider#PROP_LIBRARIES}.

     * Since {@link IOException} is not thrown either from this method or from {@link LibraryProvider#getLibraries},

     * it is expected that any problems loading library definitions will be logged and that those libraries will be skipped.

     * @param area some storage area (which might not even exist yet, in which case the set of libraries will initially be empty)

     * @return a listenable set of libraries in this area

     *         (it is permitted to return distinct objects from call to call on the same area,

     *         i.e. no caching by the implementation is necessary)

     */

    LibraryProvider<L> getLibraries(A area);

    /**

     * Creates a new library.

     * @param type the kind of library to make, as in {@link LibraryTypeProvider#getLibraryType} or {@link LibraryImplementation#getType}

     * @param name the library name, as in {@link LibraryImplementation#getName}

     * @param area the location to define the library

     * @param contents initial volume contents (keys must be contained in the appropriate {@link LibraryTypeProvider#getSupportedVolumeTypes})

     * @return a new library with matching type, name, area, and contents

     * @throws IOException if an error occurs creating the library definition     */

    L createLibrary(String type, String name, A area, Map<String,List<URL>> contents) throws IOException;

    /**

     * Deletes an existing library.

     * @param library a library produced by this provider

     * @throws IOException if a problem can encountered deleting the library definition

     */

    void remove(L library) throws IOException;

}

 * @param L the type of implementation which will be produced by this provider

/*

 * The contents of this file are subject to the terms of the Common Development

 * and Distribution License (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.html

 * or http://www.netbeans.org/cddl.txt.

 * 

 * When distributing Covered Code, include this CDDL Header Notice in each file

 * and include the License file at http://www.netbeans.org/cddl.txt.

 * If applicable, add the following below the CDDL Header, with the fields

 * enclosed by brackets [] replaced by your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 * 

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun

 * Microsystems, Inc. All Rights Reserved.

 */

package org.netbeans.spi.project.libraries;

import java.net.URL;

/**

 * Abstract location where zero or more libraries are defined.

 * {@link Object#equals} and {@link Object#hashCode} are expected to be defined

 * such that object identity (within the implementing class) are driven by {@link #getLocation}.

 * @see ArealLibraryProvider

 * @since org.netbeans.modules.project.libraries/1 1.15

 */

public interface LibraryStorageArea {

    /**

     * Gets an associated storage location.

     * The contents of the URL (if it is even accessible) are unspecified.

     * @return an associated URL uniquely identifying this location

     */

    URL getLocation();

    /**

     * Gets a human-readable display label for this area.

     * @return a localized display name

     */

    String getDisplayName();

}

     * Generally will use {@link LibrariesSupport#createLibraryImplementation}.

     * This method is <strong>not</strong> used by {@link LibraryManager#createLibrary} except in the case of {@link LibraryManager#getDefault}.

     * This method is <strong>not</strong> used by {@link LibraryManager#createLibrary} except in the case of {@link LibraryManager#getDefault}.

import java.io.File;

import java.net.MalformedURLException;

import java.net.URI;

import java.net.URISyntaxException;

import java.net.URL;

import org.openide.filesystems.FileObject;

import org.openide.filesystems.FileUtil;

import org.openide.filesystems.URLMapper;

import org.openide.util.Parameters;

    /**

     * Properly converts possibly relative file to URL.

     * @param f file to convert; can be relative; cannot be null

     * @return url

     * @since org.netbeans.modules.project.libraries/1 1.17

     */

    public static URL convertFilePathToURL(String path) {

        try {

            File f = new File(path);

            if (f.isAbsolute()) {

                return f.toURI().toURL();

            } else {

                // create hierarchical relative URI (that is no schema)

                // to encode OS characters

                URI uri = new URI(null, null, path.replace('\\', '/'), null);

                return new URL("file", null, uri.getRawPath());

            }

        } catch (URISyntaxException ex) {

	    IllegalArgumentException y = new IllegalArgumentException();

	    y.initCause(ex);

	    throw y;

        } catch (MalformedURLException ex) {

	    IllegalArgumentException y = new IllegalArgumentException();

	    y.initCause(ex);

	    throw y;

        }

    }

    /**

     * Properly converts possibly relative URL to file.

     * @param url file URL to convert; can be relative; cannot be null

     * @return url

     * @since org.netbeans.modules.project.libraries/1 1.17

     */

    public static String convertURLToFilePath(URL url) {

        if (!"file".equals(url.getProtocol())) {

            throw new IllegalArgumentException("not file URL "+url); //NOI18N

        }

        try {

            if (isAbsoluteURL(url)) {

                return new File(new URI(url.toExternalForm())).getPath();

            } else {

                // workaround to decode URL path - created fake absolute URI 

                // just to construct File instance and properly decoded path:

                URI uri3 = new URI("file:/"+url.getPath());

                return new File(uri3).getPath().substring(1);

            }

        } catch (URISyntaxException ex) {

	    IllegalArgumentException y = new IllegalArgumentException();

	    y.initCause(ex);

	    throw y;

        }

    }

    /**

     * Is given URL absolute?

     * 

     * @param url url to test; cannot be null

     * @return is absolute

     * @since org.netbeans.modules.project.libraries/1 1.17

     */

    public static boolean isAbsoluteURL(URL url) {

        if ("jar".equals(url.getProtocol())) { // NOI18N

            url = FileUtil.getArchiveFile(url);

        }

        return url.getPath().startsWith("/");

    }

    /**

     * Helper method to resolve (possibly relative) library content URL to FileObject.

     * 

     * @param libraryLocation library location file; can be null for global libraries

     * @param libraryEntry library entry to resolve

     * @return file object

     * @since org.netbeans.modules.project.libraries/1 1.17

     */

    public static FileObject resolveLibraryEntryFileObject(URL libraryLocation, URL libraryEntry) {

        URL u = resolveLibraryEntryURL(libraryLocation, libraryEntry);

        return URLMapper.findFileObject(u);

    }

    /**

     * Helper method to resolve (possibly relative) library content URL.

     * 

     * @param libraryLocation library location file; can be null for global libraries

     * @param libraryEntry library entry to resolve

     * @return absolute URL

     * @since org.netbeans.modules.project.libraries/1 1.17

     */

    public static URL resolveLibraryEntryURL(URL libraryLocation, URL libraryEntry) {

        Parameters.notNull("libraryEntry", libraryEntry); //NOI18N

        if (isAbsoluteURL(libraryEntry)) {

            return libraryEntry;

        } else {

            if (libraryLocation == null) {

                throw new IllegalArgumentException("cannot resolve relative URL without library location"); //NOI18N

            }

            if (!"file".equals(libraryLocation.getProtocol())) { //NOI18N

                throw new IllegalArgumentException("not file: protocol - "+libraryLocation.toExternalForm()); //NOI18N

            }

            File libLocation = new File(URI.create(libraryLocation.toExternalForm()));

            if (!libLocation.getName().endsWith(".properties")) { //NOI18N

                throw new IllegalArgumentException("library location must be a file - "+libraryLocation.toExternalForm()); //NOI18N

            }

            File libBase = libLocation.getParentFile();

            String jarFolder = null;

            if ("jar".equals(libraryEntry.getProtocol())) {

                assert libraryEntry.toExternalForm().indexOf("!/") != -1 : libraryEntry.toExternalForm(); //NOI18N

                jarFolder = libraryEntry.toExternalForm().substring(libraryEntry.toExternalForm().indexOf("!/")+2); //NOI18N

                libraryEntry = FileUtil.getArchiveFile(libraryEntry);

            }

            String path = convertURLToFilePath(libraryEntry);

            File f = FileUtil.normalizeFile(new File(libBase, path));

            URL u;

            try {

                u = f.toURI().toURL();

            } catch (MalformedURLException ex) {

                IllegalArgumentException y = new IllegalArgumentException();

                y.initCause(ex);

                throw y;

            }

            if (jarFolder != null) {

                u = FileUtil.getArchiveRoot(u);

                try {

                    u = new URL(u + jarFolder.replace('\\', '/')); //NOI18N

                } catch (MalformedURLException e) {

                    throw new AssertionError(e);

                }

            }

            return u;

        }

    }

    // TODO: add method which compares two libraries: compare content and file sizes and ...

    // TODO: move some of these methods to openide.FileUtil