commonj.connector.metadata.discovery
Interface MetadataObject


public interface MetadataObject

Represents an object in the metadata model for the EIS. A MetadataObject represents an object that may or may not support some form of information exchange with the client. If the object doesn not support a form of information exchange, then it cannot be imported into a ServiceDescription.

A MetadataObject has a name, and a location within the metadata model for the EIS. This location is represented by a string identifier in an implementation-specific format.

MetadataObjects have a type (enumeration of types is defined by MetadataObject.MetadataObjectType), and may support zero or more types of communication (for example request-response, notification or EIS-initiated request-response).

MetadataObjects may be mutable (can be changed) or immutable. Mutable objects allow customizations at design-time. For folders, and other objects that allow children, this means that children can be added and removed at design-time. For all objects, mutable means their properties can be changed. Mutable objects define one or more operations that may be performed on them. These operations are carried out with one or more steps within an ObjectWizardthat knows how to modify the object.

Since:
1.0

Nested Class Summary
static interface MetadataObject.MetadataObjectType
          An interface used to give tool environments a hint as to the nature of the associated MetadataObject.
 
Method Summary
 ObjectWizard beginObjectWizard(Operation op)
          Create an object wizard for the given operation.
 PropertyGroup createFilteringProperties()
          Creates a new instance of the properties that can be used to filter out the children of this MetadataObject.
 MetadataImportConfiguration createImportConfiguration()
          Create a MetadataImportConfiguration object for this Metadata object.
 PropertyGroup getAppliedFilter()
          Returns the set of filtering properties that were applied to this MetadataObject to get its children.
 MetadataObjectResponse getChildren(PropertyGroup filterParameters)
          Returns the children of this metadata object in the form of a MetadataObjectResponse
 String getDescription()
          Returns an optional string description of the MetadataObject for tool environments to use when displaying the object to users.
 String getDisplayName()
          Gets a display name that can be used within the tool environment to represent this MetadataObject.
 String getLocation()
          Returns a location within the metadata model for the EIS.
 PropertyGroup getObjectProperties()
          Gets the Read-only display properties of the metadata object.
 Operation[] getOperations()
          Gets all allowed operations on this object.
 String getParentLocation()
          Returns the location value of the parent of this MetadataObject.
 MetadataObject.MetadataObjectType getType()
          Returns the MetadataObjectType that best describes the MetadataObject.
 boolean hasChildren()
          Returns whether this metadata object has any children.
 boolean isMutable()
          Indicates if this object is mutable, and therefore supports one or more operations that can be used to modify it.
 boolean isSelectableForImport()
          Returns whether this metadata object can be imported into a ServiceDescription.
 

Method Detail

createImportConfiguration

MetadataImportConfiguration createImportConfiguration()
                                                      throws MetadataException
Create a MetadataImportConfiguration object for this Metadata object. The returned MetadataImportConfiguration represents information that will be used to import the object into a service description. The import configuration can be customized (properties set on it) and then used (as part of a MetadataSelection instance) in a call to MetadataDiscovery.createServiceDescription(commonj.connector.metadata.discovery.MetadataSelection).

Returns:
A non null MetadataImportConfiguration instance representing and controlling the import of the given object.
Throws:
MetadataException - if an error occured during execution. A MetadataException should only be thrown if it is impossible to create the MetadataImportConfiguration. If a MetadataImportConfiguration can be created but errors have occured then it should still be returned and the errors logged with th ToolContext.
See Also:
MetadataService.setToolContext(commonj.connector.tool.ToolContext)

getChildren

MetadataObjectResponse getChildren(PropertyGroup filterParameters)
                                   throws MetadataException
Returns the children of this metadata object in the form of a MetadataObjectResponse

Parameters:
filterParameters - A configured property group representing the desired filtering of children nodes. If null is passed in then no filtering is performed. The property group that is used is obtained using the createFilteringProperties() method.
Returns:
A non null MetadataObjectResponse object.
Throws:
MetadataException - if an error occured during execution. A MetadataException should only be thrown if it is impossible to create a MetadataObjectResponse. If the request for children failed this method should still return an empty MetadataObjectResponse and include an error message to be returned on the MetadataObjectResponse.getMessage() method.

getDescription

String getDescription()
Returns an optional string description of the MetadataObject for tool environments to use when displaying the object to users.

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

Returns:
an optional String description. If no description is available null is returned.
See Also:
ResourceBundle, MessageFormat

getDisplayName

String getDisplayName()
Gets a display name that can be used within the tool environment to represent this MetadataObject.

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 non null String representing the display name.
See Also:
ResourceBundle, MessageFormat

getObjectProperties

PropertyGroup getObjectProperties()
Gets the Read-only display properties of the metadata object. These properties are used to provide details about the metadata object so that users can better understand what the object represents. Tool environments can use this property group to display the metadata object details.

Returns:
A PropertyGroup containing read-only descriptive properties for the MetadataObject or null if none exist.

createFilteringProperties

PropertyGroup createFilteringProperties()
Creates a new instance of the properties that can be used to filter out the children of this MetadataObject. Tool environments can display this filter to users and allow them to optionaly filter out children as they are expanded in the metadata tree. EMD service providers may optionally choose to prime the values of the returned properties with values from the filter that was applied to the parent Metadata object.

Returns:
A PropertyGroup containing filtering properties for the MetadataObject or null if none exist.

getAppliedFilter

PropertyGroup getAppliedFilter()
Returns the set of filtering properties that were applied to this MetadataObject to get its children.

Returns:
A PropertyGroup containing filtering properties used to obtain the MetadataObject's children or null if no filter was used.

getLocation

String getLocation()
Returns a location within the metadata model for the EIS. This location is represented by a string identifier in an implementation-specific format. The location attribute returned must be unique such that it may be used at a later point in time to retrieve the MetadataObject again using the MetadataTree.getMetadataObject(java.lang.String)method.

Returns:
a unique non null String representing the location.

getParentLocation

String getParentLocation()
Returns the location value of the parent of this MetadataObject. The return of this call yields the same result as calling getLocation()on the parent MetadataObject.

Returns:
a String representing the location of the parent or null if no parent exists. Only Metadata objects that are at the very root of the EIS can have no parent. In otherwords the first set of MetadataObjects in the the MetadataObjectResponsethat is returned from a MetadataTree.listMetadataObjects(commonj.connector.metadata.discovery.properties.PropertyGroup)method call.
See Also:
getLocation()

getType

MetadataObject.MetadataObjectType getType()
Returns the MetadataObjectType that best describes the MetadataObject. The detailed behaviour of the object is controlled not through the MetadataObjectType, but rather through other properties, such as those returned from getObjectProperties(). For example, an object that is strictly used to hold, or group, other objects may be given a MetadataObjectType.FOLDER. Another object that also allows children but may also represent a more primary object might just have MetadataObjectType.OBJECT and set hasChildren()= true.

Returns:
a non null MetadataObjectType that describes the metadata object.

hasChildren

boolean hasChildren()
Returns whether this metadata object has any children. This is a convenience method for tool environments to call before deciding whether or not the getChildren(commonj.connector.metadata.discovery.properties.PropertyGroup)method needs to be invoked.

Returns:
a boolean flag indicating whether this metadata object has any children.

isSelectableForImport

boolean isSelectableForImport()
Returns whether this metadata object can be imported into a ServiceDescription. Tool environments must check the value of this method to determine if a MetadataImportConfigurationcan be created for this MetadataObject.

Returns:
a boolean flag indicating whether this metadata object can be imported into a ServiceDescription.
See Also:
ServiceDescription, MetadataImportConfiguration

isMutable

boolean isMutable()
Indicates if this object is mutable, and therefore supports one or more operations that can be used to modify it. If this method returns true, the caller must also call the getOperations()method to determine which operations are allowed for this object.

Returns:
a boolean flag indicating whether this metadata object is mutable.

getOperations

Operation[] getOperations()
                          throws MetadataException
Gets all allowed operations on this object. If an object is immutable, this method will return an empty array. The list of returned Operation objects should be shown to the tool user for selection. If the tool user chooses to modify this object, the tool will pass the selected Operation object to the beginObjectWizard(commonj.connector.metadata.discovery.mutable.Operation)method.

Returns:
a non null array of Operation s supported by this metadata object. If this metadata object is not mutable then the returned array must be empty.
Throws:
MetadataException - if an error occured during execution.
See Also:
beginObjectWizard(Operation)

beginObjectWizard

ObjectWizard beginObjectWizard(Operation op)
                               throws MetadataException
Create an object wizard for the given operation. The returned wizard is used to carry out the sequence of steps needed to accomplish the indicated operation on the indicated MetadataObject. The number of steps included in the wizard and the meaning of each step is entirely determined by the EMD service implementation, the selected MetadataObject, and the operation being performed on that object.

The operation being passed in must be non- null and and the ObjectWizard that is returned must also be non- null. An exception is thrown if an object wizard cannot be returned.

Parameters:
op - a non null Operation.
Returns:
a non null ObjectWizard used to carry out the sequence of steps needed to accomplish the indicated operation on the indicated MetadataObject.
Throws:
MetadataException - Thrown if unable to return the ObjectWizard. This includes conditions where this metadata object is not mutable and hence cannot support any operation.