 |
All About Component Libraries
This page contains information on component libraries and complib files as
defined by the
NetBeans Visual Web Pack
(VWP) and
Sun Java Studio Creator IDEs.
I recommend using the latest version of VWP because significant bugs have
been fixed in the Component Library area. As of this writing, the latest
version is NetBeans 6 M9 Preview. I need to update my blog and then
this page with a link. Information about the older version is at
Installing NetBeans 5.5 Visual Web Pack Redux.
This page is maintained by EdwinGoei.
Component Libraries Explained 2007-03-12 2006-09-11
A component library contains a set of related components that can be
packaged and distributed together in a single complib file. A complib file
is a JAR file with an extension of ".complib" instead of the usual
extension of ".jar". See SampleComplibFiles for examples. Its contents
contain the components themselves and their design-time JavaBeans
which themselves are packaged in jar files. It also may contain other items
such as source code zip files, javadoc zip files, and other jar files used
at runtime and design-time. Each complib file must contain a logical table
of contents, which is physically split into multiple files, that provide
information on its components. Thus, a complib file is
similar to a web archive war file in that it contains other jars and
content files within it and metadata about its contents. Details on the
complib package format can be found at ComplibSpec.
Each complib has a namespace which is represented by a URI and a version
number that identifies the set of components. A third party can release
components using a particular set of Java packages and associate them with
a namespace and version number. Each subsequent release of the components
can then use the same namespace but a different version number to identify
the release. This allows the IDE to prevent two different versions of
component code in the same Java package from being used within the same
project. (Note, in Creator 2, there was a bug where this was not enforced.)
A complib file can be imported into the IDE and installed into the palette
using the Tools->Component Library Manager->Import dialog. Importing a
complib file expands its contents into the IDE's "userdir", which is
typically named ".netbeans/${version}/" or ".Creator" under the user's home
directory. In VWP, the component library must be added to a project which
causes the IDE to copy the expanded component library to the project and
add its jars to the project's classpath. This allows the project to be
self-contained so it can be zipped up and given to a co-worker and still
build.
When the IDE embeds a complib within a project, it stores it's contents
under a project's "lib/complibs" sub-directory and it maintains a list of
all complibs for the project using an "index.xml" file. Project complibs
are implemented on top of NetBeans library primitives. In
NetBeans, Library definitions are managed by the Library Manager and
are global resources stored in the userdir. Library references are
managed by the NetBeans project properties dialog and are per-project
resources that point to library definitions. The IDE tries to automatically
manage both library definitions and references when complibs are used in a
project. However, sometimes problems may occur because NetBeans
typically expects the user to manage these resources manually. This means
that a user can often also manually fix such problems.
The Component Library Manager dialog also has a "Remove" button which will
remove a complib from the userdir. However, this does not remove any
complibs that are embedded within a project. To do that in VWP, you can go
to the Projects Window and use the Component Libraries node to remove or
update any component libraries. (In versions before NetBeans 5.5 VWP,
you needed to perform some difficult manual steps.)
In the future, an enhancement would be to allow a project to be dependent
upon shared instead of embedded component libraries. Each component library
would be a kind of NetBeans Library project. In this scenario, a web
project would no longer be self-contained.
Troubleshooting
This section contains information on problems related to complibs and how
to fix them. Complibs are built on top of core NetBeans features
instead of being a core feature itself so you may see problems when the IDE
state becomes inconsistent.
Fixing Broken Projects with Complibs (2006-09-12 2006-04-15)
Sometimes if you open a project, you may see the project's node icon in the
Project Navigator with a warning badge complaining about broken library
references. (There are plans to fix this problem in a future release.)
Please ignore any IDE instructions about creating library references and
instead follow the directions below to have the IDE regenerate them for
you.
- Open a JSP page, for example "Page1.jsp", in the project. This will cause a notification that the complibs within the project have been copied to your "userdir" and will be installed on the palette. You may need to scroll the palette to see them. The IDE will also add jars from the embedded project complibs to the project classpath by creating the appropriate library definitions and references for the complibs.
- At this point, the components from complibs may not appear correctly. To fix this problem, close the project (Ctrl-W) and reopen the project.
The project should now behave normally. The IDE stores information for
palette components and also library definitions in your userdir so if this
information is ever removed, the above steps must be repeated. If the steps
above do not fix the problem, you can manually clean up all complib state
from a project and reconstruct the project using the information provided
in this section.
Information on Component Authoring and Complib Files
This section is directed towards third-party component developers instead
of the general IDE user. It provides information on how to extend VWP and
Creator with additional components.
- CustomComponentLibraries contains info on how to write and package JSF components into a complib file which can then be imported into an IDE such as VWP or Creator.
Updates
- 2007-05-14 Removed obsolete info on manually removing a project complib
- 2007-03-12 Updated info on NetBeans VWP. Moved updates section to end.
- 2006-12-12 Added note about NetBeans 5.5 Visual Web Pack changes.
- 2006-09-11, 2006-09-12 Created, added troubleshooting section, moved all complib info to this page.
-- EdwinGoei
|