Overview (Common Server)

Common Server
Package	Description
org.netbeans.api.server	API providing the common server instances.
org.netbeans.api.server.properties	Support API for persistence of server instance properties.
org.netbeans.spi.server	SPI for registering different kinds of servers in the IDE.

The Server module provides the CommonServerSPI that contains SPIs needed for the UI presentation of servers (anykind) and cloud providers. It covers the services tab, server manager, server add wizard, cloud manager and cloud add wizard.

There is also API part of the module CommonServerAPI that provides API representation of the server and cloud instances. API access if required in future will be placed here.

Clients can provide its instances through the SPI. They can also provide wizards to define UI way for the server or cloud instance addition. It is done with CommonServerLayerSPI where the SPIs implementation must be registered.

To provide easy way for clients to persist properties of its instances easily, module provides support API CommonServerPropertiesAPI to do that. This support API is not mandatory for clients to use in any way.

ServersNodeActions By registering actions to Servers/Actions you can extend the list of popup actions on Servers node in Services tab. CloudNodeActions By registering actions to Cloud/Actions you can extend the list of popup actions on Cloud node in Services tab. serverNodeHidden If the action registered in Servers/Actions or Cloud/Actions folder has getValue("serverNodeHidden") == Boolean.TRUE, then it will not be shown in the popup menu.

wizardMessage

By adding wizardMessage attribute you tell the Add Server... or Add Cloud... action to display this message as an option, if no servers are yet registered. If user agrees, your action will be called then to enable some server providers.

The action then receives command noui, to know that it shall only enable given functionality, but there is no need to show user anything.

ServersNodeActionsAttributes

By adding additional attributes to files in Servers/Actions or Cloud/Actions folder you can influence behaviour of the Servers and Cloud node.

By adding property-something attribute you identify an action that will be called as soon as the node is expanded and System.getProperty("something") is non-null.

By adding config-something attribute you identify an action that will be called as soon as the node is expanded and FileUtil.getConfigFile("something") is non-null.

In all of these cases, the action receives command noui, to know that it shall only enable given functionality, but there is no need to show user anything.

These attribute based APIs shall be seen as temporary and subject to replacement. Please notify us as soon as you start to use them.

What is New (see all changes)?

Jan 13 '12 The ServerInstance implements Lookup.Provider
The ServerInstance became Lookup.Provider.
Dec 22 '11 Added UI helper method CommonServerUIs.showAddServerInstanceWizard
Added helper method invoking wizard for adding new server instance.
Aug 24 '11 Establish layer to register cloud providers
Reuse existing server support provided by this module and use it to support concept of cloud providers. At the moment registration of cloud providers is implemented (/Cloud folder in layer). Their visualization will be added later. This is work in progress.
Apr 3 '09 Extensible actions on root server node
By registering actions to Servers/Actions you can extend the list of popup actions on Servers node in Services tab.
Feb 10 '08 Support API for server instance persistence
Support API providing easy way for persistence of instance properties. Not manadatory for clients to use.

Use Cases

Registering the server/cloud instance provider

An external module can register itself as the server instance provider. In order to do that it must register the implementation of ServerInstanceProvider in Servers or Cloud folder in the layer.xml.

When this is done the module will handle displaying of instances at appropriate IDE dialogs and views. Note that more specific SPIs can still be required for the technology specific dialogs and actions. This module covers the areas where the "common server" term makes sence.

Every ServerInstance returned by the provider is handled by this module. Some features of the ServerInstance are not mandatory (as described in javadoc). If new instances can be added or removed during the lifecycle of external module it has to notify all listeners of the ServerInstanceProvider.

Registering the server/cloud wizard

An external module can register the wizard(s) in order to allow the user to add new instances. In order to do that it must register the implementation of ServerWizardProvider in Servers or Cloud folder in the layer.xml.

When this is done the module will offer this wizard in UI (at contexts where it makes sense).

Persisting instance properties

The Commons Server SPI implemetor has to usually implement persistence of its instances somehow. There are many ways how this can be done. To make it easier InstancePropertiesManager can be used. It provides a way how to store and retrieve properties of the server instance.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

Group of java interfaces

Interface Name	In/Out	Stability	Specified in What Document?
CommonServerSPI	Exported	Under Development	.../netbeans/spi/server/package-summary.html
CommonServerAPI	Exported	Under Development	.../netbeans/api/server/package-summary.html
CommonServerPropertiesAPI	Exported	Under Development	.../server/properties/package-summary.html

Group of layer interfaces

Interface Name	In/Out	Stability	Specified in What Document?
CommonServerLayerSPI	Exported	Under Development	overview-summary.html
ServersNodeActions	Exported	Under Development	By registering actions to `Servers/Actions` you can extend the list of popup actions on Servers node in Services tab.
CloudNodeActions	Exported	Under Development	By registering actions to `Cloud/Actions` you can extend the list of popup actions on Cloud node in Services tab.
ServersNodeActionsAttributes	Exported	Friend	By adding additional attributes to files in `Servers/Actions` or `Cloud/Actions` folder you can influence behaviour of the Servers and Cloud node. By adding `property-something` attribute you identify an action that will be called as soon as the node is expanded and `System.getProperty("something")` is non-null. By adding `config-something` attribute you identify an action that will be called as soon as the node is expanded and `FileUtil.getConfigFile("something")` is non-null. In all of these cases, the action receives command noui, to know that it shall only enable given functionality, but there is no need to show user anything. These attribute based APIs shall be seen as temporary and subject to replacement. Please notify us as soon as you start to use them.

Group of property interfaces

Interface Name	In/Out	Stability	Specified in What Document?
serverNodeHidden	Exported	Friend	If the action registered in `Servers/Actions` or `Cloud/Actions` folder has `getValue("serverNodeHidden") == Boolean.TRUE`, then it will not be shown in the popup menu.
wizardMessage	Exported	Friend	By adding `wizardMessage` attribute you tell the Add Server... or Add Cloud... action to display this message as an option, if no servers are yet registered. If user agrees, your action will be called then to enable some server providers. The action then receives command noui, to know that it shall only enable given functionality, but there is no need to show user anything.

Implementation Details

Where are the sources for the module?

The sources for the module are in the NetBeans Mercurial repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

Nothing.

Read more about the implementation in the answers to architecture questions.

Common ServerUnder Development