This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 44035

Summary: Create sharable library descriptor
Product: projects Reporter: Milan Kubec <mkubec>
Component: LibrariesAssignee: apireviews <apireviews>
Status: RESOLVED FIXED    
Severity: blocker CC: anebuzelsky, bleonard, dbotterill, dkonecny, dsimonek, edwingo, fommil, gsteyn, herkules, jglick, jimdavidson, jlahoda, jrojcek, kawazu428, markdey, mkleint, mkrauskopf, m_potociar, pbuzek, pjiricka, potingwu, ppisl, tomwheeler, tpavek, tzezula, unr303, wadechandler
Priority: P2 Keywords: API, API_REVIEW, UI
Version: 4.x   
Hardware: All   
OS: All   
URL: http://wiki.netbeans.org/wiki/view/OutOfBoxVersionabilityProposal
Issue Type: ENHANCEMENT Exception Reporter:
Bug Depends on: 57338, 104337, 104336, 115947, 122580    
Bug Blocks: 85263, 47498, 49638, 66275, 76979, 84728, 89629, 107936, 108952, 108976, 123639    
Attachments: javadoc for ant/project with sharable libraries changes.
complete diff of changes in ant/project module
project/libraries complete patch
javadoc for project/libraries
complete api diff
complete api diff
complete api diff

Description Milan Kubec 2004-05-31 09:49:38 UTC
NB IDE should have something like nbproject
library descriptor. It would completly define the
library for project - location, classpath,
sourcepath, javadoc .... It would be allowed
inside jar/zip/folder or externally and it would
define also multiple libraries. 

When adding new library to IDE user would just
browse to the descriptor and that's it.

It would ease sharing of libraries and resolving
broken references since there is no support for
relative references.
Comment 1 herkules 2004-10-04 14:07:20 UTC
maybe my english isn't good enough ...

Do you want library definitions as created with the 'Library Manager'
being part of a project?

In this case, you have my vote! When looking at JBuilder ... there
libraries can be part of the system, the project, or the user settings.

Important: should be storable to VCS!
Comment 2 Jesse Glick 2004-10-04 16:21:45 UTC
Joerg please note that it is already true that if you add a library
whose JAR file is inside the project dir, or in the same VCS checkout,
the IDE will automatically store a relative path, so others checking
out the project will be able to build it out of the box. All that is
currently missing is the ability to check in the source and/or Javadoc
association, when the source/Javadoc is also checked into the VCS.

Also a wizard to rearrange existing libs so they can be cleanly
versioned alongside the project would be nice; this is already filed
separately (issue #49638).
Comment 3 herkules 2004-10-04 16:51:33 UTC
Ok, I think my comment talks about issue #49638. 

Currently, libraries are stored in
$user.home\.netbeans\4.0beta2\config\org-netbeans-api-project-libraries\Libraries

And from there, they cannot be checked into VCS very well.
Comment 4 Jesse Glick 2004-10-04 17:03:41 UTC
As I said, what is currently missing is the ability to check in the
source/Javadoc association, which is what is stored in the user dir
currently. If the actual JAR file is collocated with the project, you
can still build the project after a fresh checkout - there is no need
for the library to be defined in the second userdir.
Comment 5 herkules 2004-10-06 16:45:25 UTC
Ok, forgive my stupidity. Didn't notice that the libs CP are
replicated in the project.properties. 

Thus it remains a not-so-nice artifact that a 'Missing library'
appears  in the project setting w/o any hint what that library
consisted of.

From the info in project.properties ... couldn't some suggestions be
made how to create the missing library? At least the jar names are all
present.

'The library HerkulesLib is missing which contained
jdom.jar,jemmy.jar,junit.jar. Create it now?'

Comment 6 Tomas Zezula 2004-10-06 16:55:38 UTC
Yes, it can be done.
Comment 7 Jesse Glick 2005-03-09 20:14:03 UTC
*** Issue 55373 has been marked as a duplicate of this issue. ***
Comment 8 Jesse Glick 2005-03-17 22:34:25 UTC
*** Issue 56595 has been marked as a duplicate of this issue. ***
Comment 9 Tomas Zezula 2005-03-29 07:50:18 UTC
*** Issue 56764 has been marked as a duplicate of this issue. ***
Comment 10 Tomas Zezula 2005-04-20 08:02:55 UTC
*** Issue 58080 has been marked as a duplicate of this issue. ***
Comment 11 Tomas Zezula 2005-04-20 08:05:58 UTC
Should be done in NetBeans 4.2. There are many requests for it.
Comment 12 Jesse Glick 2005-05-26 19:07:40 UTC
Note that it is possible to implement something sort of like this as an add-on
module, without waiting for any changes in the IDE. Since projects can already
add binary JARs directly, and sharable project.properties will be used when the
path is relative (I think even if there is >1 JAR in the lib), the most
important missing piece is ability to share source and Javadoc associations. But
you could do that separately. E.g. define a new fragment to be placed in
project.xml like

<lib-data xmlns="whatever...">
    <source-association binary="lib/foo.jar" source="lib/foo-src.zip"/>
    <javadoc-association binary="lib/foo.jar" javadoc="lib/foo-api.zip"/>
</lib-data>

A separate module could then read and write these fragments using
AuxiliaryConfiguration without special support from the project. Now just
provide an action (Tools menu I guess?) to display a simple dialog that lets you
manage associations for the selected project; and register a global
SourceForBinaryQueryImplementation and JavadocForBinaryQueryImplementation which
refer to associations made in open projects (OpenProjectList). Your associations
would then be specific to a defining project, but that is likely to be OK - e.g.
if you have a main project and a bunch of subprojects, some of which use some
libs, just define all the lib associations in the main project and make sure you
have it open whenever you want to work on the subprojects.

Making the GUI form would be the only difficult piece. I don't think it's a
solution to this RFE because it would not be well integrated into the rest of
the IDE's UI (in particular the Library Manager), but it would function as a
temporary workaround.
Comment 13 Mark Dey 2005-05-31 18:10:52 UTC
Yes, there are a number of ways to work around the limitation using custom
solutions. The problem with that approach is that it produces project structures
that are unique to a particular implementation of the add-on module. In the case
where a project is exported to an environment that does not contain the module,
the metadata will be ignored without any clue to the user as to how to recover
from the resulting errors that occur from missing library references. I would
recommend that project implementors avoid temporary workarounds in this area and
wait for a common project API for managing sharable descriptors.
Comment 14 Jesse Glick 2005-06-01 01:34:16 UTC
Obviously the possible workaround I outlined would only work for people with
that module installed; I was just pointing out that it is possible to experiment
with solutions using a separate module, which could be incorporated into the
official codebase if it seems to be adequate.
Comment 15 Jesse Glick 2006-01-22 16:54:04 UTC
*** Issue 65016 has been marked as a duplicate of this issue. ***
Comment 16 Jesse Glick 2007-02-07 23:05:30 UTC
*** Issue 94896 has been marked as a duplicate of this issue. ***
Comment 17 Jesse Glick 2007-03-27 22:14:25 UTC
*** Issue 75117 has been marked as a duplicate of this issue. ***
Comment 18 Jesse Glick 2007-04-11 02:02:28 UTC
I have it working in a branch. See

http://wiki.netbeans.org/wiki/view/OutOfBoxVersionability

Tomáši - I would like a prereview of the design; if it looks OK to you I would
move to apireviews for a more general review.
Comment 19 Petr Jiricka 2007-04-11 07:28:19 UTC
Jesse, is there a summary of all the UI changes you are proposing? Thanks.
Comment 20 Tomas Zezula 2007-04-11 18:01:35 UTC
Seems fine to me. The disk library layout property.file containing
${base}/relative_path where base is stored in the ant project part of project
xml and the APH.getProjectLibrariesPropertyProvider is a good solution. The
project can easily create PropertyEvaluator containing the libraries properties
=> broken reference support and others should work.
The StorageAwareLibraryProvider should be fine. Do you plan to move it into
libraries SPI package? The LibraryManager.getLibraries() returns only global
libraries, right? Do you plan any API to access also the project libraries? Not
important, I am not sure if there is even an use case for it.
Comment 21 _ edwingo 2007-04-11 18:22:35 UTC
Yes, please provide an API. I have a use case.
The "component libraries" feature of visualweb needs to have per-project Library
Definitions -- the same kind as are currently (as of NB 5.5) only available
globally. This includes classpath, source, javadoc, and also a design-time
volume. In addition, a programmatic way of accessing the functionality is needed
because the Library Definitions and Library References are maintained
automatically for the user. For more info, see
http://wiki.java.net/bin/view/Javatools/AllAboutComplibs.
Comment 22 Jesse Glick 2007-04-11 18:38:11 UTC
StorageAwareLibraryProvider could be in the public SPI package at some point.
For the initial work I wanted to be conservative and keep it as a private SPI,
in case the design is wrong.


LibraryManager.getLibraries returns all libraries - global libraries, and also
project libraries (from definition files which have either been created in this
session, or are in use from open projects). In order to make it return only
global libraries it would be necessary to expose a lot more stuff in the API,
since code such as that in j2seproject needs to e.g. show library pickers. On
the other hand there is a potential incompatibility, since referring to a
project library *without* using the new method in ReferenceHelper will not work.
I am not sure what to do about that.


It is possible to create project libraries programmatically either

1. By directly writing the appropriate metadata on disk and adding a reference
to it directly using AuxiliaryConfiguration.

or

2. By using the new SPI classes, which currently means having an impl dep on the
libraries module (not ant/project directly).

I was not intending to provide a formal API for creating project libraries
programmatically in the initial work. Not until there are more use cases
available to study. Possibly not in 6.0.
Comment 23 Tomas Zezula 2007-04-11 18:50:10 UTC
Implementation  dependency or creating the property file is OK.
The problem with broken project reference when project type is not updated to
use APH.getProjectLibrariesPropertyProvider is not so hard since the code to
update the project type is quite simple. All the project types can do the update
in NetBeans 6.0.
Comment 24 _ edwingo 2007-04-11 19:06:05 UTC
Please contact me (Edwin Goei) if you want more details on the use case for
VisualWeb projects. In VisualWeb projects, users can extend the components that
are available using component libraries that are automatically managed by the
IDE because it is inconvenient for the user to have to add all the individual
artifacts that correspond to classpath, source code, javadoc, and design-time
jars and zips. The user specifies a single file, a "complib" file and all the
other parts are managed by the IDE. So the IDE needs to be able to create both
Library Definitions and Library References programmatically to do this. This is
why an API is needed. If the concern is about stability. Could you provide a
friend API to the complib module? This would greatly help the useability of
component libraries in visualweb.
Comment 25 Jesse Glick 2007-04-11 19:44:15 UTC
The project type needs to do three things:

1. Load the project libraries if specified, meaning copy the relevant stuff from
j2seproject's build-impl.xsl.

2. Add AntProjectHelper.getProjectLibrariesPropertyProvider to the evaluator.

3. Call ReferencesHelper.createLibraryReference and .cleanUpLibraryReferences
when adding/removing libraries.

If these are omitted, then project libraries will appear in the library chooser
for the Add Library dialog, and you can pick them, but they will be broken
references. It might be possible to add a new method to LibraryManager to get
project libraries, and return only global libraries from getLibraries; but then
(a) project types would also need to modify their choosers, (b)
java/j2seplatform queries would not work on project libraries without further
modification. (a) and (b) are solvable, I'm just not sure if it's worth it, if
we plan to update all nb.org project types to do 1-3 anyway.

Regarding the suggestion to have a method LibraryManager.forFile (or similar) -
this would be a possible alternative API (a bunch of things would need to be
rewritten to follow that style) which would expose the storage area concept in
the API. Unfortunately I don't think it would be much cleaner. People would
expect that you could call addLibrary on a nonglobal instance using the
currently documented idiom in the addLibrary method. But this will not work;
LibraryTypeProvider.createLibrary is unusable for project libraries (and in fact
unused in the system I am working on), since the implementations assume they are
dealing with a global library and update $userdir/build.properties. It is the
provider which needs to control the creation of the LibraryImplementation. (In
fact, as far as I can tell, LibraryTypeProvider is a useless interface, since
all the implementations have nearly identical bodies, copied and pasted; they
all use the default LibraryImplementation, and only parametrize the list of
volume types they support.)


For the friend API to complib: for now I would rather not, since there is only
one user. Also providing a friend API would be trickier than usual, since both
projects/libraries and ant/project already have public APIs and you cannot
expose both a public API and a friend API from a single module. But you can
create all the necessary files on disk (the format is intended to be stable) and
they should be recognized automatically. A formal API is possible later.
Comment 26 Jesse Glick 2007-04-11 20:44:49 UTC
Regarding UI: there are some screenshots of the current UI in the wiki.
Comment 27 Petr Jiricka 2007-04-11 22:07:33 UTC
> there are some screenshots of the current UI in the wiki.

Thanks, this is very useful. One question: when I create a new Java SE project,
can I somehow force the IDE to use the JUnit library from a shareable location?
What are the steps that accomplish this? Thanks.
Comment 28 Jesse Glick 2007-04-11 22:10:42 UTC
Requesting an API review for M9, by Wed Apr 18. (If it turns out to be too
controversial, can defer till M10.) Everything you need to know is in the wiki.
Comment 29 Jesse Glick 2007-04-11 22:29:20 UTC
To Petr's question about using a project lib when creating a new project: if the
project template contains the lib and descriptor, then it will be there. If you
are talking about the standard j2seproject template, as it exists today, then
no; but this is tracked as a separate issue #49638.

I am still investigating the issue of creating a project library with the same
name as a global library, which will be needed for #49638 etc.; it is a bit
tricky since libraries have until now been identified uniquely by a simple name,
which will no longer be reliable.
Comment 30 Jesse Glick 2007-04-12 01:42:46 UTC
I have decided to withdraw this API request as I am unhappy with the current API
for various reasons. That means this feature cannot be implemented for M9.
Comment 31 Jesse Glick 2007-05-02 21:12:16 UTC
Resubmitting with a redesigned API. Everything you need to know is in the wiki.

I plan to merge this after JavaOne. Since the API changes are not trivial, a
full API review seems appropriate. Please let me know if you would like to be a
reviewer; I need to schedule a call, I guess.
Comment 32 Jesse Glick 2007-05-15 18:32:42 UTC
Will be a conference call discussing the API if anyone else is interested:
Thursday May 17, 9.00 Pacific, 12.00 Eastern, 18.00 Europe.
Comment 33 Jesse Glick 2007-05-19 02:22:51 UTC
There were no objections to the API or basic design during the conference call.

I believe I have finished all basic work for this feature and am ready to merge
from the branch, perhaps as early as Monday (May 21). I would appreciate some QA
sanity-checking before then, but of course I will try to fix important issues in
the trunk after merging as well.

As usual, all details are in the wiki.
Comment 34 Petr Jiricka 2007-05-21 08:24:22 UTC
> I ... am ready to merge from the branch

Are the UI changes going to be a part of this merge? If so, then the UI review
(isseu 91723) should first be completed before the commit.
Comment 35 Petr Pisl 2007-05-21 10:53:47 UTC
I'm sorry for my late comments. I was thinking about this during this weekend
and I have these comments:

PP01:  With the shared libraries there is introduce new supertype of library -
the shared libraries. But there are libraries registered in Library manager (we
can call them global libraries) which are not sharable. My problem with this is
that there is no way how to share the  global libraries. A usecase is for
example supporting a web framework. The module which support a web framework 
creates a library with the framework binaries in Library Manager.  I think,
there should be a support for converting a global library into a sharable library.

PP02: There has to be explain very well in the ui the difference between the
global and sharable library. I think the ui will be very important. I'm not sure
that it will be clear for users. I think that every project should be sharable,
which means that every library should be sharable as well. So there is a
question, why anyone would want to use the old (global) libraries.

PP03: I know that the broken reference dialog is another issue. But improving
the broken reference dialog to display the definition of the missing library is
a part of the sharing projects/libraries as well (at least form my point of
view).  Basically it means that the information about the content of the
(global) library has to be stored with the project.

PP04: A project type, which want to have the possibility of sharable libraries,
has to be altered. Is there any plan for this?
Comment 36 Tomas Zezula 2007-05-21 13:04:14 UTC
PP01: Can be solved by action "Make shared" on the global library. The action
copies the content of the global library into shared place and creates an
shareable descriptor.
PP03: The BrokenReferenceSupport (BRS) has nothing in common with this API. It
can be solved for example in the following way: When the library is added into
the project it stores the names of jar files into auxiliary configuurion. This
information can be used by the BRS to show user the name of missing archives.
Comment 37 Jesse Glick 2007-05-21 19:07:28 UTC
Regarding a UI review - of course UI changes are included in the branch
(otherwise the changes could not be used!). I have already asked for a quick
review of the UI (from Dafe) but have heard nothing back. UI people are very
busy and they cannot realistically review every UI change in the IDE. Anyway the
UI can be changed at any time, so long as it follows the basic workflow dictated
by the APIs; the goal of this work for M10 is to make it possible to have
project libraries, not to make it perfect.


PP01 - this is issue #49638, or perhaps issue #49637 (maybe should be merged). I
consider this a separate task not part of the basic work.


PP02 - you can see in the Library Manager that there are Global Libraries, and
then libraries stored in a particular place. Again the UI can be improved in the
future. As to why people would want to use global libraries at all - probably in
the long run they will not. But a lot of other work needs to be done before we
get there: UI needs to be created to migrate usages of global libraries in
existing projects, and every module which tries to add specific libraries (e.g.
Group Layout) to a project would need to be modified (or the project would need
to do automatic quiet translation of requests to add global libraries to local
copies, which would then also need to be synchronized in version number, etc.
etc.). For this issue I simply want to make project libraries possible, not to
entirely replace every usage of global libraries for all users.


PP03 - this work does not touch the Broken References dialog. In the longer
term, that dialog will likely be removed, in favor of a general system for
displaying unsharable external file references and correcting them. And once you
are using project libraries, then it is much less likely you will encounter
broken references to begin with.


PP04 - see the wiki for a detailed list of changes needed by project types to
accommodate project libraries.


Given the late comments I will wait until tomorrow (Tuesday) for further action.
Comment 38 Jesse Glick 2007-05-29 15:46:32 UTC
Was not accepted for 6.0.
Comment 39 _ edwingo 2007-05-31 19:05:59 UTC
Could you explain why it was not accepted? Is there an alternate proposal? I
think this is a major limitation with NetBeans from an EOU perspective and
should be a high priority to fix as there are no good workarounds. As I
understand it, if this  issue is not fixed, then users will have to go through
an unfriendly process of "resolving references" when opening projects from other
users.
Comment 40 Jesse Glick 2007-06-01 01:05:06 UTC
Was rejected for schedule reasons. It will need to wait for the next release, sorry.
Comment 41 Tomas Zezula 2007-07-17 08:43:15 UTC
*** Issue 109598 has been marked as a duplicate of this issue. ***
Comment 42 Tomas Zezula 2007-07-17 09:22:06 UTC
*** Issue 109605 has been marked as a duplicate of this issue. ***
Comment 43 _ wadechandler 2007-11-13 21:18:53 UTC
*** Issue 94286 has been marked as a duplicate of this issue. ***
Comment 44 _ hair 2007-11-15 09:34:45 UTC
This issue is somewhat related to http://www.netbeans.org/issues/show_bug.cgi?id=74474
Atleast they are different ways of skinning the same cat and i hope are kept in mind of each other.

This issue doesn't bother me as i use mevenide projects and it picks up project dependencies, for each developer in the
team, through maven and your own repositiory, but registering those dependencies into your library manager (mainly to
benefit from readily available javadoc and source) is a sore point.
Comment 45 emi 2007-11-21 12:00:55 UTC
I would just like to add that the library sources should be visible from Go to Class/file and other such actions. It
helps a lot during debugging.
Comment 46 herkules 2007-11-21 12:57:35 UTC
I'd like to augment 2 suggestions when overhauling the library system:

* specify jars per platform optionally, e.g. Java3D jars are platform-specific
* allow to specify a path for native code, platform specific

Java3D, JTrackIR, JXInput, JOGL, JOAL, JINPUT, .... they all need natives ... would be great if this could be specified
with a library
Comment 47 ulfzibis 2007-11-21 13:19:37 UTC
Yes, that a good idea, to include natives to libraries. :-)
Comment 48 Jesse Glick 2007-12-06 16:52:01 UTC
*** Issue 123581 has been marked as a duplicate of this issue. ***
Comment 49 fommil 2008-01-09 09:42:30 UTC
Is there an answer as to when this will be added to an NB 6.x release? I've just come over from Eclipse and there is not a snowball's chance in hell of getting 
the rest of my team to move over unless this issue is resolved. As far as I am concerned, it kills the ability to have more than one person work on a project!

During the overhaul, the developers might consider adding a library-level include/exclude list for the code completer (such as Eclipse has) and looking at 
the following issues with managing libraries

 http://www.netbeans.org/issues/show_bug.cgi?id=124779
 http://www.netbeans.org/issues/show_bug.cgi?id=124842
Comment 50 David Konecny 2008-01-11 09:20:17 UTC
The plan is to have it in 6.1 Milestone2.
Comment 51 Milos Kleint 2008-01-16 08:04:07 UTC
Created attachment 55119 [details]
javadoc for ant/project with sharable libraries changes.
Comment 52 Milos Kleint 2008-01-16 08:18:06 UTC
Created attachment 55121 [details]
complete diff of changes in ant/project module
Comment 53 Milos Kleint 2008-01-16 08:24:53 UTC
please review. API changes attached. For UI design see URL field.
Comment 54 fommil 2008-01-17 09:44:27 UTC
somewhat related to issue 125314 (but not a dupe)
Comment 55 Tomas Zezula 2008-01-17 19:01:59 UTC
Doesn't seem to be a fast API review for me.
Comment 56 Milos Kleint 2008-01-17 20:21:05 UTC
tzezula: the api change itself is reasonably small. The change itself is big though.

the major part of code is within the actual project type(s) unfortunately.

Comment 57 Tomas Zezula 2008-01-18 08:16:31 UTC
I still believe this deserves a regular API review.
Is the ReferenceHelper (SPI) the only start point to fnd out the project libraries?
Is there a way for an API client to get a list of them?
What are the use cases for FileChooser? Is it really needed (with identity)? Wouldn't be a helper method enough?
Comment 58 Milos Kleint 2008-01-18 09:35:31 UTC
Created attachment 55235 [details]
project/libraries complete patch
Comment 59 Milos Kleint 2008-01-18 09:38:40 UTC
Created attachment 55237 [details]
javadoc for project/libraries
Comment 60 Milos Kleint 2008-01-18 10:07:09 UTC
tzezula: ok, fine with me to do the full review, however I want to merge into trunk next week anyway. We need to finish
the review before 6.1-M2. I assume you will be one of the reviewers. Anyone else volunteers?

re:
  Is the ReferenceHelper (SPI) the only start point to fnd out the project libraries?
  Is there a way for an API client to get a list of them?

Good questions, I figured I actually forgot to include the project/libraries part of the API/SPI changes. That's what
one gets for doing multiple things at once..
LibraryManager and the newly introduced methods there is what you are looking for.

re: What are the use cases for FileChooser? Is it really needed (with identity)? Wouldn't be a helper method enough?

what do you mean with identity? The filechooser is there as class primarily because there's a different way of
retrieving the java.util.File selected values from it. It probably could be replaced with a FileChooserHelper class and
2 methods (public static JFileChooser createFileChooser() and public static File[] getFiles(JFileChooser)) but it
doesn't enforce a better pattern usage (one can still make the mistake of using the original JFileCHooser method
getSelectedFiles()). Hiding the JFileChooser instance altogether is not possible as all the current usecases need to
setup the basic properties of JFileChooser as well.
Comment 61 Tomas Zezula 2008-01-18 11:23:27 UTC
I fully support integration of this feature even before review, if Jarda permits.
Having the second part of the diff I am much more happier :-)
FileChooser: I just wanted to be sure that several other properties of JFileChooser are used, otherwise I will suggest
only a simple method List<? extends File> showFileChooser (.....), but if there is plenty of JFileChooser props used I
have nothing against the final class FileChooser.
Comment 62 Jesse Glick 2008-01-19 20:17:25 UTC
Since I already reviewed my own changes as of 20070502 :-) may I ask what further API changes were made since then (or
changes of mine reverted)?
Comment 63 Milos Kleint 2008-01-22 09:36:02 UTC
glick: I'm not aware of any significant API change that we would revert. We've been mostly adding on top of what you
have done or slightly changing it. The majority of work done (and to be done in the future)  was in the UI.
I'm not aware of a simple method of extracting changes in api between two dates..
Comment 64 Jesse Glick 2008-01-22 19:04:15 UTC
Too much to absorb at once, but some things:

[JG01] EditJarSupport.Item should expose only methods, not fields - both as a matter of general API hygiene, and to
account for the possibility that we might wish to later (1) prevent concurrent modifications, (2) insert logging, (3)
support multiple source or Javadoc archives, etc.

[JG02] It is also unclear in EJS.Item how a File could be relative to project basedir. java.io.File is normally
absolute; an unanchored path is always treated as a relative to the JVM's current working directory. If you really mean
to distinguish between absolute and project-relative paths as two distinct possibilities, the normal way of doing this
(already used in various APIs, e.g. AntArtifact) is to use a variable of type URI.
Comment 65 Milos Kleint 2008-01-23 08:33:13 UTC
[JG01] done

[JG02] The relative/absolute File reference is only consumed by ReferenceHelper.createForeignFileReferenceAsIs() and
ReferenceHelper.createExtraForeignFileReferenceAsIs() methods that call File.getPath() on it and make sure it's relative
to the project root when creating the reference. David has more insight here, I let him comment more..
Comment 66 Jesse Glick 2008-01-23 18:12:26 UTC
[JG02] Please do not ever use java.io.File objects with relative paths to mean a path relative to some separately
specified dir. This is potentially very confusing, as class Javadoc (and the behavior of other methods, e.g. isFile) all
assume that the JVM's CWD is the base for pathname resolution. If you want to refer to either relative or absolute paths
with one Java type, you can use either

1. A String in Ant format, e.g. "../foo bar" vs. "/home/bob/foo bar"; best used only in ant/project or modules depending
on it, where PropertyUtils can be used to resolve the path against a base dir (here "/home/bob/somethingelse").

2. A URI, e.g. "../foo%20bar/" vs. "file:/home/bob/foo%20bar/", which can be resolved using URI and File methods.
Comment 67 Jesse Glick 2008-01-25 00:06:32 UTC
*** Issue 125955 has been marked as a duplicate of this issue. ***
Comment 68 fommil 2008-01-28 02:10:29 UTC
I tried out an early build of this last week (thanks to Petr Jiricka for pointing me to it) and I think this looks great!

I had a bug with an erroneous directory being created on my file system which looked very much like somebody getting their relative paths mixed up... I'm pleased to 
see jglick has found some offending uses of File which may have prompted this.

I do have one major concern with the proposed solution... which should be easy to fix, but I'd like to see it addressed before 6.1. If the associated sources/Javadocs 
are not at the top level of an archive, then there is no way to specify the path within the archive. This is a pretty big issue as it means NetBeans cannot display javadocs 
or sources for most libraries. It could be fixed by either having an additional property (e.g. lib.name.url.base) to contain this information, or including it as part of the 
URL, much the way the XML descriptors work. I would prefer the former solution as "archive.zip!/path/" may mess with ant tasks that are expecting a file. Somewhat 
related to this is issue 124779, which I am keen to help out with.
Comment 69 Jesse Glick 2008-01-28 02:16:55 UTC
archive.zip!/path/ for representing non-top-level roots of sources and Javadoc ought to be OK because AFAIK this
information would not be used by Ant builds anyway.
Comment 70 David Konecny 2008-01-28 02:49:43 UTC
Re. "I tried out an early build" - thanks. If you tell me more about the bug you experienced, preferably how to
reproduce it, I would be happy to fix it. Or just file new issue.

Re. "support Javadoc not at the top level of an archive" - this is unrelated to project sharability. There is definitely
separate issue requesting this.

[JG02] - I agree it can be confusing and may end up being source of problems. I need to look at this in detail and will
comment later.

Re. jglick wrote "Since I already reviewed my own changes as of 20070502 :-) may I ask what further API changes were
made since then (or changes of mine reverted)?" - I thought that was the case but I could not find any "record" of that.
There were basically just two changes in your implementation:
* project can have 0..1 versionable library descriptors; ProjectLibraryProvider slightly changed to accommodate that
* logic determining whether a file should be reference via relative or absolute path was generally moved from
AntProjectHelper to UI layer - user is in control how things get referenced. Most of the changes were done in UI.

There is bunch of new API (helper) methods/classes we added:
* org.netbeans.api.project.ant.FileChooser
* org.netbeans.spi.project.support.ant.AntProjectHelper.isSharableProject()
* org.netbeans.spi.project.support.ant.AntProjectHelper.[get|set]LibrariesLocation
* org.netbeans.spi.project.support.ant.ProjectGenerator.createProject(FileObject, String, String)
* org.netbeans.spi.project.support.ant.ReferenceHelper.createForeignFileReferenceAsIs
* org.netbeans.spi.project.support.ant.ReferenceHelper.createExtraForeignFileReferenceAsIs
* org.netbeans.spi.project.support.ant.ReferenceHelper.copyLibrary
* org.netbeans.spi.project.support.ant.ReferenceHelper.getLibraryChooserImportHandler
* org.netbeans.spi.java.project.support.ExtraSourceJavadocSupport
* org.netbeans.spi.java.project.support.ui.EditJarSupport
* org.netbeans.spi.java.project.support.ui.MakeSharableUtils
* org.netbeans.api.project.libraries.LibrariesCustomizer.showCreateNewLibraryCustomizer
* org.netbeans.api.project.libraries.LibrariesCustomizer.showSingleLibraryCustomizer
* org.netbeans.api.project.libraries.LibraryChooser.LibraryImportHandler
* org.netbeans.api.project.libraries.LibraryManager.[add|remove]OpenManagersPropertyChangeListener
* org.netbeans.spi.project.libraries.support.LibrariesSupport.convertFileToURL
* org.netbeans.spi.project.libraries.support.LibrariesSupport.convertURLToFile
* org.netbeans.spi.project.libraries.support.LibrariesSupport.isAbsoluteURL
* org.netbeans.spi.project.libraries.support.LibrariesSupport.resolveLibraryEntryFileObject
* org.netbeans.spi.project.libraries.support.LibrariesSupport.resolveLibraryEntryURL
Comment 71 fommil 2008-01-28 09:33:49 UTC
> "support Javadoc not at the top level of an archive" - this is unrelated to project sharability. There is definitely
separate issue requesting this.

where is the separate issue which specifically addresses javadoc/sources and the sharable descriptor? Who is the best person/team to speak to regarding 
associated source/javadocs in general?

I disagree that it is unrelated... it is a critical necessity of the sharability feature that associated javadocs/source be properly supported. The ability to share 
libraries between developers is completely voided if developers cannot use the IDE's Javadoc or source viewer on those libraries. Most middleware libraries do 
not have their source/javadocs at the top level of an archive. Unless the sharable descriptors provide a means to store that path information, then there is no 
hope of supporting it.
Comment 72 Milos Kleint 2008-01-28 12:59:26 UTC
fommil: the non toplevel path in archives works on the general level. I've been using it in maven support for a while
(with javadoc at least). I suppose you can try it out by manually editing the library properties files or the project
properties files. If I recall correctly the issue/enhancement is filed already for some time, it would be nice to have
but I'm not 100% positive that the UI changes required make it into 6.1. 
Comment 73 Tomas Zezula 2008-01-28 13:15:03 UTC
There is an enhancement #124779 for attaching the inside jar sources and javadocs.
It's not problem to implement it but it's problem to design an UI for it, if you agree with 
auto detection of source (javadoc) root it shouldn't be problem.
Comment 74 fommil 2008-01-28 13:37:16 UTC
mkleint wrote:
> the non toplevel path in archives works on the general level. I've been using it in maven support for a while (with javadoc at least). I suppose you can try 
it out by manually editing the library properties files or the project properties files. If I recall correctly the issue/enhancement is filed already for some 
time, it would be nice to have but I'm not 100% positive that the UI changes required make it into 6.1. 

Perhaps we are confusing things here. I am not talking about any UI-related work here... it is clear that such a discussion belongs in the issue 124779  
report. When I say that the sharable library descriptors should probably support paths within an archive, I mean that the following should happen:-

- create a sharable library descriptor for a library
- add source or Javadocs using the current UI
- close NetBeans
- edit the properties file and edit the source/Javadoc location property to contain the archive.zip!/path/ notation to point to the base (or edit a separate 
path-within-archive property)
- restart NetBeans
- NetBeans uses the correct non-root archive path for loading source/Javadocs for this library

The last build which contained this patch did not support non-root paths at all. If you're saying the situation has changed, then I will try the latest build. 
Should things work as explained or is this still not supported?

I'd be more in favour of an additional property to store the path within the archive, instead of mixing it up with the file location property. It is conceivable 
that somebody would want to create an ant task that copies all sources/Javadocs of dependencies to a deployment location.

tzezula wrote:
> There is an enhancement #124779 for attaching the inside jar sources and javadocs. It's not problem to implement it but it's problem to design an UI for 
it, if you agree with auto detection of source (javadoc) root it shouldn't be problem.

I know... I created it :-) I've volunteered to write the code for the auto-detection, if somebody would get back to me I would speed up my efforts with a 
goal of getting this into 6.1... but that's getting a little off topic and we should continue that thought on the issue 124779 page.
Comment 75 ulfzibis 2008-01-28 17:59:14 UTC
> If the associated sources/Javadocs are not at the top level of an archive, 
> then there is no way to specify the path within the archive.

IMO there are some other issues, which would profit from this:
 Issue 123639, 108976, 108952, 107936, 85263

So I add them to the 'blocks' list. Feel free to remove them, if you don't agree.
Comment 76 David Konecny 2008-01-29 03:37:35 UTC
[JG02] - we agreed with mkleint to use String representation of relative path instead of File. Will impact
FileChooser.getFiles(), RerefenceHelper.createForeignFileReferenceAsIs() and perhaps obsoletes some of the methods in
LibrariesSupport which convert File to URL and vice versa.

to fommil: I enhanced sharable libraries descriptor to handle "archive.zip!/path/" values - no separate property for now
as it is not needed by Ant; can be added later. Right now I'm behind firewall and have difficulties pushing the change
to trunk so perhaps tomorrow. By "unrelated" I meant mainly that UI needs to be provided and that's beyond the scope of
this issue.
Comment 77 fommil 2008-01-29 08:46:33 UTC
dkonecny:
> By "unrelated" I meant mainly that UI needs to be provided and that's beyond the scope of this issue.

Looks like that support is going to make 6.1, and no need for a UI... it's all autodetect, see issue 124779. Thanks for ensuring that the properties files can 
support this!
Comment 78 gsteyn 2008-01-31 01:33:15 UTC
Will the proposed changes resolve or take the problem identified in Issue 115947 into account?  If so, issue 115947 can 
be marked as a duplicate/closed.

One other question - without knowing the details, will this change make is easier to use Netbeans projects with 
continuous build systems such as Hudson, Bamboo, Continuum?  I have being trying to persuade our teams to consider 
moving to Netbeans, but without an easy means of integrating to a CI environment this will be a big problem.  Using 
Mevenide helps, but there are some cases where working with NB projects is easier for starting out.

Fabrizio covers some of the details of using NB with CI systems in his blog: 
http://weblogs.java.net/blog/fabriziogiudici/archive/2006/11/setting_up_netb.html
Comment 79 Jana Maleckova 2008-02-07 09:50:43 UTC
*** Issue 126188 has been marked as a duplicate of this issue. ***
Comment 80 David Konecny 2008-02-11 01:56:53 UTC
re. "will this change make is easier to use Netbeans projects with continuous build systems" - yes.

Two small API changes:
* "Library.getContent" is going to always return absolute URLs. This is what method used to do before introducing shared
libraries and relative URLs in library content. This change was actually semantically incompatible and forced client to
call Library.getContent() + LibrariesSupport.resolveLibraryEntryURL(). If (ever) needed there might be added
Library.getRawContent.

* added "static LibraryManager ReferenceHelper.getProjectLibraryManager(Project)" - it is useful for 3rd party modules
which do not have AntProjectHelper and yet they do something with global or project libraries
Comment 81 Milos Kleint 2008-02-21 13:47:14 UTC
Created attachment 56982 [details]
complete api diff
Comment 82 Milos Kleint 2008-02-21 13:47:52 UTC
Created attachment 56983 [details]
complete api diff
Comment 83 Milos Kleint 2008-02-21 13:54:15 UTC
Created attachment 56984 [details]
complete api diff
Comment 84 Milos Kleint 2008-02-21 14:06:02 UTC
attached are the diffs of api/spi packages only, related to shared libraries (this issue).
I'l like to schedule a review meeting on Tue, 25Feb at 7PM CET. The initial participants are mkleint, jglick, tzezula
and dkonecny. If anyone else wants to ake part, please send me an email.
Comment 85 Jesse Glick 2008-02-21 17:07:52 UTC
Uh, is that Mon Feb 25 or Tue Feb 26?
Comment 86 Jesse Glick 2008-02-25 17:49:04 UTC
Again: what day?
Comment 87 Pavel Buzek 2008-03-05 19:30:51 UTC
Is this done? Tonda says it is resolved but I still see the issue open. Please clarify. Thanks.
Comment 88 fommil 2008-03-11 16:40:06 UTC
I'm not able to remove a library from a project if it is using a sharable library folder, 6.1 beta.

Also, as general feedback, I found the support to port a project from local descriptors to shared descriptors to be very difficult. In particular, my local libraries 
were not automatically exported into the shared folder. I had to manually create them using the Resolve Reference Problems dialog and then manually add 
jars and sources.
Comment 89 David Konecny 2008-03-11 22:34:29 UTC
fommil, could you please file separate issues for your problems? Both sounds like defects to me. More detailed steps how
to reproduce the problems are appreciated. Thanks, David.
Comment 90 Milos Kleint 2008-03-25 10:33:37 UTC
I'm closing this issue as fixed in 6.1
Comment 91 Karthikeyan Rajeswaran 2008-04-03 18:03:59 UTC
See also: issue 118587