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.spi.project.libraries;
021:
022: import java.beans.PropertyChangeListener;
023: import java.io.IOException;
024: import java.net.URL;
025: import java.util.List;
026: import java.util.Map;
027: import java.util.Set;
028:
029: /**
030: * Library provider which can define libraries in particular areas.
031: * There is no explicit method to save a library; setters on {@link LibraryImplementation} should do this.
032: * @param A the type of storage area used by this provider
033: * @param L the type of library created by this provider
034: * @since org.netbeans.modules.project.libraries/1 1.15
035: */
036: public interface ArealLibraryProvider<A extends LibraryStorageArea, L extends LibraryImplementation> {
037:
038: /**
039: * Property to fire when {@link #getOpenAreas} might have changed.
040: */
041: String PROP_OPEN_AREAS = "openAreas"; // NOI18N
042:
043: /**
044: * Adds a listener to {@link #PROP_OPEN_AREAS}.
045: * @param listener a listener to add
046: */
047: void addPropertyChangeListener(PropertyChangeListener listener);
048:
049: /**
050: * Removes a listener to {@link #PROP_OPEN_AREAS}.
051: * @param listener a listener to remove
052: */
053: void removePropertyChangeListener(PropertyChangeListener listener);
054:
055: /**
056: * Gets the runtime type of the area used by this provider.
057: * @return the area type
058: */
059: Class<A> areaType();
060:
061: /**
062: * Gets the runtime type of the libraries created by this provider.
063: * @return the library type
064: */
065: Class<L> libraryType();
066:
067: /**
068: * Creates or otherwise picks a storage area interactively.
069: * This might actually create a fresh area, or just load an existing one,
070: * or even do nothing (and return null).
071: * The implementor is free to show a dialog here.
072: * @return a new or existing storage area, or null
073: */
074: A createArea();
075:
076: /**
077: * Loads a storage area (which may or may exist yet).
078: * @param location an abstract storage location which may or may not be recognized by this provider
079: * @return an area whose {@link LibraryStorageArea#getLocation} matches the provided location,
080: * or null if this type of location is not recognized by this provider
081: */
082: A loadArea(URL location);
083:
084: /**
085: * Looks for areas which should be somehow listed as open.
086: * For example, a provider which refers to library areas from project metadata
087: * could list all areas referred to from currently open projects.
088: * It is <em>not</em> necessary to include areas recently mentioned e.g. by {@link #createArea}.
089: * @return a (possibly empty) collection of areas
090: */
091: Set<A> getOpenAreas();
092:
093: /**
094: * Gets all libraries defined in a given area.
095: * No two libraries in this area may share a given name (as in {@link LibraryImplementation#getName},
096: * though it is permitted for libraries from different areas to have the same name.
097: * Changes in the set of libraries defined in this area should be fired through {@link LibraryProvider#PROP_LIBRARIES}.
098: * Since {@link IOException} is not thrown either from this method or from {@link LibraryProvider#getLibraries},
099: * it is expected that any problems loading library definitions will be logged and that those libraries will be skipped.
100: * @param area some storage area (which might not even exist yet, in which case the set of libraries will initially be empty)
101: * @return a listenable set of libraries in this area
102: * (it is permitted to return distinct objects from call to call on the same area,
103: * i.e. no caching by the implementation is necessary)
104: */
105: LibraryProvider<L> getLibraries(A area);
106:
107: /**
108: * Creates a new library.
109: * @param type the kind of library to make, as in {@link LibraryTypeProvider#getLibraryType} or {@link LibraryImplementation#getType}
110: * @param name the library name, as in {@link LibraryImplementation#getName}
111: * @param area the location to define the library
112: * @param contents initial volume contents (keys must be contained in the appropriate {@link LibraryTypeProvider#getSupportedVolumeTypes})
113: * @return a new library with matching type, name, area, and contents
114: * @throws IOException if an error occurs creating the library definition */
115: L createLibrary(String type, String name, A area,
116: Map<String, List<URL>> contents) throws IOException;
117:
118: /**
119: * Deletes an existing library.
120: * @param library a library produced by this provider
121: * @throws IOException if a problem can encountered deleting the library definition
122: */
123: void remove(L library) throws IOException;
124:
125: }
|