Libraries API

Representation of a library, and the ability to find the installed libraries.

# Contents

- Overview
- How to obtain a list of installed libraries
- Managing libraries
- Library definition format

# Libraries API

## Overview

The libraries API provides a client API of the Libraries framework. The Library itself is a typed set of volumes. The volume is a ordered list of resources. The type of library implies the volumes contained in it. For example the J2SE library contains three volumes (sources, classpath and javadoc). The resource is a valid URL of the physical resource.

## How to obtain a list of installed libraries or given library

To obtain a list of installed libraries you want to call {@link org.netbeans.api.project.libraries.LibraryManager#getLibraries} as in the following example for listing the names of installed libraries.

    Library[] libraries = LibraryManager.getDefault().getLibraries ();
    for (int i = 0; i< libraries.length; i++) {
        System.out.println(libraries[i].getName()+" : "+libraries[i].getType());
    }

To obtain a library with a given name you want to call {@link org.netbeans.api.project.libraries.LibraryManager#getLibrary} method as in the following example.

    Library library = LibraryManager.getDefault().getLibrary ("Ant");
    if (library != null) {
        System.out.println(library.getName()+" : "+libraries[i].getType());
    }

## Managing libraries

Libraries module provides graphical manager of libraries. The manager allows you to create a new library of a given type, to delete existing library or to change content of volumes. It is not possible to create or delete a volume in the library since the volumes are implied by the library type.

To open the graphical libraries manager you need to call {@link org.netbeans.api.project.libraries.LibrariesCustomizer#showCustomizer} method.

## Library definition format

A module is able to register the predefined library. For example the junit module installs the junit library. The library definition is placed in the org-netbeans-api-project-libraries/Libraries folder on the system filesystem.

The library format is given by the following DTD.

    <?xml version="1.0" encoding="UTF-8"?>

    <!--
      Root element of library definition descriptor.
    -->
    <!ELEMENT library (name, type, description?, localizing-bundle?, volume*) >

    <!-- The version attribute specifies the version of the library -->

    <!ATTLIST library version CDATA #FIXED "1.0" >

    <!--- Library unique identifier - a string.

     In the case when the localizing-bundle element presents the name value is used
     as a key into bundle to locate the display name. Otherwise the name value is
     used as a display name-->
    <!ELEMENT name (#PCDATA) >

    <!--Short description of given library - a string.
     In the case when the localizing-bundle element presents the description value
     is used as a key into bundle to locate the localized description. Otherwise
     the description value is used.-->
    <!ELEMENT description (#PCDATA) >

    <!-- The resource name of base bundle without an extension - a string.
     The bundle used to lookup the localized strings.
     The bundle is looked up by NbBundle.getBundle (String) method.
     Example of localizing bundle: org.netbeans.modules.junit.resources.Bundle -->
    <!ELEMENT localizing-bundle (#PCDATA)>

    <!--- Volume is typed list of resources -->
    <!ELEMENT volume (type, resource*) >

    <!--- Volume type of a library volume - a string
     For example the J2SE library supports the following types of volume:

     classpath, javadoc and src -->
    <!ELEMENT type (#PCDATA) >

    <!--- Volume resource coded as an URL
     In the case of URL with nbinst protocol the URL is resolved from the NetBeans installation
     dircetory.
     If the URL points to an archive file, the URL must have the jar protocol.
     Example:
     jar:file:///usr/lib/java/xerces.jar!/ is resolved to /usr/lib/java/xerces.jar/
     jar:nbinst:///modules/ext/junit.jar!/ is resolved to ${netbeans.home}/modules/ext/junit.jar

     -->
    <!ELEMENT resource (#PCDATA) >