commonj.connector.metadata.discovery
Interface MetadataSelection


public interface MetadataSelection

Represents the current selection of MetadataObjects in the tool environment. It contains a list of zero or more objects where each object is represented by the MetadataImportConfiguration required to import that object into a ServiceDescription. It is the responsibility of the implementor to insure that all objects added to this selection are consistent with each other and can co-exist in the same service description. The only firm requirement in this area is that a given selection can only support all inbound or all outbound import configurations. In other words, a selection cannot include objects that are being imported for inbound communication and objects that are being imported for outbound communication.

Since:
1.0

Method Summary
 void add(MetadataImportConfiguration importConfiguration)
          Add a new import configuration to this selection.
 void applySelectionProperties(PropertyGroup selectionValues)
          Applies the configured property values to the meta data selection.
 MetadataImportConfiguration canAdd(MetadataObject object)
          Deprecated. - Since 1.1. See canAdd(MetadataObject[])
 MetadataImportConfiguration[] canAdd(MetadataObject[] object)
          A convenience method for tool environments to call before attempting to call add(commonj.connector.metadata.discovery.MetadataImportConfiguration).
 PropertyGroup createSelectionProperties()
          Creates a new instance of the properties that control how a service description will be created from the current selection.
 PropertyGroup edit(MetadataImportConfiguration importConfiguration)
          Edit the configuration properties of a MetadataImportConfiguration in the selection.
 String getMessage()
          Returns any status messages indicating the state of the MetadataSelection.
 MetadataImportConfiguration[] getSelection()
          Get an array of all import configurations that have been added to this selection.
 boolean isSelectionComplete()
          Returns a boolean indicating whether the minimum number of MetadataObjects has been added and the tooling can proceed.
 void remove(MetadataImportConfiguration importConfiguration)
          Remove an existing import configuration from this selection.
 

Method Detail

add

void add(MetadataImportConfiguration importConfiguration)
         throws MetadataException
Add a new import configuration to this selection. A MetadataException will be thrown if the new import configuration is incompatible in any way with the existing import configurations in this selection.

Any MetadataImportConfiguration that has been added to a selection must not be altered subsequently by the tool environment. If an added MetadataImportConfiguration needs to be altered it must first be removed, using remove(commonj.connector.metadata.discovery.MetadataImportConfiguration), from the selection. This guarantees that any of the modifications to the MetadataImportConfiguration do not cause the current selection to be invalidated.

Parameters:
importConfiguration - A non null MetadataImportConfiguration.
Throws:
MetadataException - thrown if the new import configuration is incompatible in any way with the existing import configurations in this selection.

remove

void remove(MetadataImportConfiguration importConfiguration)
Remove an existing import configuration from this selection.

Parameters:
importConfiguration - A non null MetadataImportConfiguration.

getSelection

MetadataImportConfiguration[] getSelection()
Get an array of all import configurations that have been added to this selection.

Returns:
An non null array of MetadataImportConfigurations contained in this selection. If the selection is empty then a zero length array is returned.

createSelectionProperties

PropertyGroup createSelectionProperties()
Creates a new instance of the properties that control how a service description will be created from the current selection.

The value settings of the properties returned must match any values currently applied on the selection via a previous call to applySelectionProperties(commonj.connector.metadata.discovery.properties.PropertyGroup).

MetadataImportConfiguration instances are independent of one another, and can exist in multiple selections. For this reason, any common properties that are interrelated between various MetadataImportConfiguration instances, must be returned as MetadataSelection returned by this method.

Tool environments must call this method followed by applySelectionProperties(PropertyGroup)immediately before calling MetadataDiscovery.createServiceDescription(MetadataSelection).

Returns:
a PropertyGroup representing the available configuration properties or null if no configuration properties exist.

canAdd

MetadataImportConfiguration canAdd(MetadataObject object)
Deprecated. - Since 1.1. See canAdd(MetadataObject[])

A convenience method for tool environments to call before attempting to call add(commonj.connector.metadata.discovery.MetadataImportConfiguration). Tool environments may choose to visually display which existing nodes in a MetadataTree are valid for selection with the current set of selected nodes. This method can be used to determine this.

This method returns a MetadataImportConfiguration instance if the MetadataObject can be added. Normally, the MetadataImportConfiguration instance would be identical to the one returned from MetadataObject.createImportConfiguration(). However, there may be cases where the set of properties on the MetadataImportConfiguration need to be constrained for the MetadataObject to be added successfully to the current selection. In such situations the MetadataImportConfiguration returned would be different and would contain the constrained set of properties.

In all situations the tool environment must use the MetadataImportConfiguration returned from this method when calling the add(commonj.connector.metadata.discovery.MetadataImportConfiguration)method.

Parameters:
object - a non null MetadataObject that is to be tested for addition with the current selection.
Returns:
a MetadataImportConfiguration that can be used to add the object to the existing selection or null if the object cannot be added.

applySelectionProperties

void applySelectionProperties(PropertyGroup selectionValues)
                              throws MetadataException
Applies the configured property values to the meta data selection.

Parameters:
selectionValues - a non null property group that has been configured with values. The property group instance must have been created using the createSelectionProperties() method.

It is important to note that if this method is called, then a subsequent add(commonj.connector.metadata.discovery.MetadataImportConfiguration)call is made, the property values applied may become invalidated. Hence, tool environments must call this immediately before calling MetadataDiscovery.createServiceDescription(MetadataSelection). This guarantees that the configuration properties are compatible with the current selection.

Throws:
MetadataException - if an error occured during execution. This includes if an invalid PropertyGroup was specified.

canAdd

MetadataImportConfiguration[] canAdd(MetadataObject[] object)
A convenience method for tool environments to call before attempting to call add(commonj.connector.metadata.discovery.MetadataImportConfiguration). Tool environments may choose to visually display which existing nodes in a MetadataTree are valid for selection with the current set of selected nodes. This method can be used to determine this.

This method returns an array of MetadataImportConfiguration instances if the MetadataObject can be added. Normally, the MetadataImportConfiguration instance would be identical to the one returned from MetadataObject.createImportConfiguration(). However, there may be cases where the set of properties on the MetadataImportConfiguration need to be constrained for the MetadataObject to be added successfully to the current selection. In such situations the MetadataImportConfiguration returned would be different and would contain the constrained set of properties.

In all situations the tool environment must use the MetadataImportConfiguration returned from this method when calling the add(commonj.connector.metadata.discovery.MetadataImportConfiguration)method.

Replaces canAdd(MetadataObject)

Parameters:
object - an array of non null MetadataObject that is to be tested for addition with the current selection.
Returns:
an array of MetadataImportConfiguration that can be used to add the objects to the existing selection or null if the objects cannot be added.
Since:
1.1

getMessage

String getMessage()
Returns any status messages indicating the state of the MetadataSelection. For example, if a certain number of objects can be added or more objects needs to be added.

This message may be updated after each canAdd, add or remove of a MetadataImportConfiguration.

This is a locale specific object that must be separated to a ResourceBundle, translated, and retrieved using the locale of the tool environment.

Returns:
A String message or null if no message exists.
Since:
1.1
See Also:
ResourceBundle, MessageFormat

isSelectionComplete

boolean isSelectionComplete()
Returns a boolean indicating whether the minimum number of MetadataObjects has been added and the tooling can proceed.

Returns:
a boolean flag of true indicating that the MetadataSelection has the minimum number of MetadataObjects added to it or false otherwise
Since:
1.1

edit

PropertyGroup edit(MetadataImportConfiguration importConfiguration)
Edit the configuration properties of a MetadataImportConfiguration in the selection.

Returns a new configuration properties PropertyGroup for the specified MetadataImportConfiguration. The value settings of the properties returned must match any values currently applied on the import configuration and must be consistent with the current state of the selection.

Tool environments must call MetadataImportConfiguration.applyConfigurationProperties(PropertyGroup) to apply changes.

Parameters:
importConfiguration - A non null MetadataImportConfiguration in the selection
Returns:
a new configuration properties PropertyGroup for the specified MetadataImportConfiguration. The PropertyGroup must be consistent with the current state of the selection.
Since:
1.1