OutOfBoxVersionabilityImplementation

Out-Of-Box Versionability Implementation

Hudson build

CVS information

Branch: versionability_89629 over ant/project apisupport/project form java/j2seplatform java/j2seproject java/project java/source projects/libraries web/project with last base tag versionability_89629_base_12 (created on 21/Jan);

On 22/Jan the branch was merged to trunk. NO further development on the branch is planned.

Versionable library descriptors

User requirement: ability to create library definitions corresponding to library JARs which are physically stored in a versionable area alongside other project sources; when the project (or whole versioned source tree) is checked out from CVS, the library should not only be ready for use from e.g. a continuous builder, but ready for use in the IDE if the project is opened. Should support multiple JARs in one library (as in current global libraries). Should also be possible to keep sources and/or Javadoc for the library in versioned area as well, if desired.

Does not address any UI to update existing global library references to sharable libraries, e.g. by copying JARs into the project. That is issue #49638.

Status: The Library Manager handles project libraries, j2seproject & web/project both understand them, New Java SE Library Descriptor wiz in apisupport lets you pick them, the form editor's Palette handles them. Java ME and (non-web-tier) Java EE project types do not yet grok them - see issues #104336 and #104337.

Issue #44035

Old proposal from Tomáš Zezula

Basic idea: inside a VCS root, have a file such as libs/libs.properties with syntax similar to ${userdir}/build.properties:

libs.commons_collections.type=j2se
libs.commons_collections.classpath=${base}/commons-collections.jar
libs.commons_collections.javadoc=${base}/commons-collections-api.zip

You could also keep some per-user settings nearby, here in libs/libs-private.properties:

libs.commons_collections.src=/home/joe/commons-collections-1.0/src/java

Each project could refer to this versioned descriptor, for example:

<libraries xmlns="http://www.netbeans.org/ns/ant-project-libraries/1">
    <definitions>../../libs/libs.properties</definitions>
</libraries>

The build-impl.xml would load libs.properties so you could have project.properties refer to these paths as usual:

javac.classpath=\
    ${libs.commons_collections.classpath}

And the IDE would offer code completion and other features according to the classpath, optional source association, and optional Javadoc association specified for each JAR.

Open Issues

  1. Can the same system be used to define Java platforms?
 While library definitions have a fixed syntax defined in projects/libraries
 which is easy to translate to properties files,
 Java platforms can be defined with different DTDs according to type (SE, ME),
 and these files have a lot more junk in them (such as system properties).
 Probably the same format and some infrastructure could be used,
 but nontrivial API changes in java/platform
 (similar to those just made in projects/libraries)
 would be required.
  1. You cannot specify a displayName for a LibraryImplementation
 except using a localizing bundle over which you have no control;
 get/setLocalizingBundle should not have been made part of the public SPI.
 (Issue #57338)

To do

  • publish schema in www/www/ns/
  • update ide/golden/, check commit validation
  • Update any random code still using LibraryManager.getDefault.
 (Adaptation of project types should be covered by
 Issue #104336 and
 Issue #104337.)
  • Sometimes build-impl.xml is not regenerated after adding library definition?
 Not sure how to reproduce.
  • Tree expansion and node selection after loading a new area
 in LibrariesCustomizer is unreliable.
  • Fix usage of LibraryManager.getDefault() from java/source and other modules.
 (Was audited in branch but need to recheck with current sources.)

Associated API Changes

http://deadlock.netbeans.org/hudson/job/versionability_89629/javadoc/

<!-- ant-project-libraries-1.xsd; see real file for details on file formats -->
<xsd:schema ... targetNamespace="http://www.netbeans.org/ns/ant-project-libraries/1" ...>
 <xsd:element name="libraries">
  <xsd:complexType>
   <xsd:sequence>
    <xsd:element name="definitions" minOccurs="0" maxOccurs="unbounded" type="xsd:string"/>
   </xsd:sequence>
  </xsd:complexType>
 </xsd:element>
</xsd:schema>

class AntProjectHelper {
  // ...as before plus:
  public PropertyProvider getProjectLibrariesPropertyProvider(); // add to prj eval
}
class ReferenceHelper {
  // ...as before plus:
  // used when adding/removing libs to CP:
  public String createLibraryReference(Library library, String volumeType);
  public void cleanUpLibraryReferences();
  // used when looking up libs by name:
  public Collection<LibraryManager> getProjectLibraryManagers();
  public Library findLibrary(String name);
}

package org.netbeans.api.project.libraries;
class LibraryManager {
  // ...as before, but addLibrary is deprecated
  public String getDisplayName();
  public URL getLocation();
  public Library createLibrary(String type, String name, Map<String,List<URL>> contents)
    throws IllegalArgumentException, IOException;
  public static LibraryManager forLocation(URL location) throws IllegalArgumentException;
  public static Collection<LibraryManager> getOpenManagers();
}
class Library {
  // ...as before
  public LibraryManager getManager();
}
public final class LibraryChooser {
  public LibraryChooser();
  public LibraryChooser(Collection<LibraryManager>);
  public Set<Library>/*|null*/ showDialog();
  public Panel createPanel();
  public LibraryChooser filter(Filter);
  public interface Filter {
    boolean accept(Library);
  }
  public interface Panel {
    Component getVisualComponent();
    Set<Library> getSelectedLibraries();
    String PROP_SELECTED_LIBRARIES;
    void addPropertyChangeListener(PropertyChangeListener);
    void removePropertyChangeListener(PropertyChangeListener);
  }
}

package org.netbeans.spi.project.libraries;
public interface LibraryProvider<L extends LibraryImplementation> {
  L[] getLibraries(); // as before, just generic
}
public interface ArealLibraryProvider<A extends LibraryStorageArea,
                                      L extends LibraryImplementation> {
  String PROP_OPEN_AREAS;
  void addPropertyChangeListener(PropertyChangeListener listener);
  void removePropertyChangeListener(PropertyChangeListener listener);
  Class<A> areaType();
  Class<L> libraryType();
  A createArea();
  A loadArea(URL location);
  Set<A> getOpenAreas();
  LibraryProvider<L> getLibraries(A area);
  L createLibrary(String type, String name, A area, Map<String,List<URL>> contents)
    throws IOException;
  void remove(L library) throws IOException;
}
public interface LibraryStorageArea {
  URL getLocation();
  String getDisplayName();
}

Project types need to make the following changes to support project libraries:

  1. Load the project libraries if specified,
 meaning copy the relevant stuff from j2seproject's build-impl.xsl.
  1. Add AntProjectHelper.getProjectLibrariesPropertyProvider to the evaluator.
  2. Call ReferenceHelper.createLibraryReference and .cleanUpLibraryReferences
 when adding/removing libraries.
  1. Use LibraryChooser instead of proprietary choosers.
  2. Check for improper usages of LibraryManager.getDefault.
 Generally replace with ReferenceHelper.findLibrary.

Appendix

Old UI proposal

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo