What is the difference between a suite and a cluster?

Apache NetBeans Wiki Index

Note: These pages are being reviewed.

A suite is a project which bundles together a number of module projects, lets you build them all together, and puts the resulting JARs in a directory structure the NetBeans Platform understands.

That directory structure is a cluster. A cluster is a directory structure which the application launcher and module system understand. A cluster is a runtime artifact where the module system can find the modules that make up an application.

While it is common to think of a suite as being a cluster (the build product of a suite is a cluster, after all), they are not the same thing.

Suites

A suite is a container project used to group module projects into a unit whose members can depend on one another, and also depend on a copy of the NetBeans platform.

The structure generated on disk when you compile a suite project is a cluster.

If you are creating a single module (perhaps an IDE extension or a very simple NetBeans Platform-based application) you can ignore suites, and just build/run/distribute a single stand-alone module. You will still get a cluster structure on disk when you compile the module. However, suite projects offer some additional features, such as building zip and JNLP application distributions.

You can always start with a stand-alone module project and later create a suite project and add your module to the suite. If you are going to bundle multiple third-party libraries, and want the ability to provide updates of those libraries, you probably want a suite.

Inter-suite Dependencies

A suite may depend on

  • Another suite

  • A stand-alone module

  • An external binary cluster (a cluster directory somewhere on disk which you might not have the source code to: DevFaqWhatIsACluster). Use the Add Cluster button on the Libraries tab of your suite’s Project Properties dialog to set up such dependencies.

See DevFaqHowToReuseModules for more details.

Clusters

A cluster is typically a subdirectory of a NB-based application’s binary installation. Every module in the installation lives in one (and only one) cluster. For details on the structure of clusters, see DevFaqWhatIsACluster.

The installation is divided into clusters for purposes of:

  1. Conceptual clarity.

  2. Mapping to native packaging systems such as RPM, Debian/Ubuntu packages, Solaris packages, etc.

The NetBeans team has a policy of treating inter-cluster module dependencies as more significant than intra-cluster module dependencies with respect to backward compatibility. The goal is to make it possible for product teams building on top of the NetBeans IDE to select a subset of the IDE to use — with cluster granularity rather than with module granularity.

Cluster-granularity is simpler to grasp and integrate with native packaging (if the NetBeans IDE consisted of 500 Debian packages, nobody would be particularly happy about that). But there is nothing preventing you from reusing a subset with module granularity.

The NetBeans launcher (nbexec) accepts a list of cluster directories to load modules from — basically a search path. There are no further semantics to clusters.

The suite project type has a standard build target to assemble a complete application. For simplicity, it simply places all modules built from suite sources into their own cluster named in accordance with the suite’s name.

NBMs may specify a cluster. The netbeans/ subdirectory of the NBM (which is a ZIP file) has a file layout which matches the layout of files within a single cluster. Each cluster managed by Auto Update has an update_tracking/ subdirectory with one XML file per module, enumerating the files which that module contributes to the cluster.

Currently the "NB Platform" is just the platform cluster from the IDE. The entire contents of the platform cluster may not be exactly what you want for every "platform" application, so a suite project allows you to exclude modules you do not wish to include.

Clusters are supposed to be medium-grained or coarse-grained, unlike modules which are generally fine-grained units.

See also:

  • harness/README in your IDE distribution

  • the Help > Contents pages on modules and applications

  • Installation Structure

No Suites In NetBeans IDE Sources

The NetBeans IDE build (from sources on hg.netbeans.org) does not use suites.

It uses a historical build infrastructure which partially overlaps the external module/suite build harness introduced in NetBeans 5.0, but which has different requirements, and is considerably more complex.

Module projects physically inside the netbeans.org source tree cannot be "standalone" modules nor "suite component" modules. They are simply netbeans.org modules, and as such use a (slightly) different format for metadata, and have access to somewhat different facilities specific to netbeans.org practices.

The resulting build artifacts are, nonetheless, clusters. These clusters are simply built using a different build-infrastructure, where the cluster names and contents are defined in .properties files in $NB_SRC/nbbuild/.