com.hp.ucmdb.api.topology

Interface TopologyUpdateService

public interface TopologyUpdateService

Interface for updating topology: creating, updating, and deleting CIs and relations. To create the data structures used by the methods of this interface, use the factory obtained with the getFactory method.

A typical usage of this interface is demonstrated below:

 TopologyUpdateService topologyUpdateService = ucmdbService.getTopologyUpdateService();
 TopologyUpdateFactory topologyUpdateFactory = topologyUpdateService.getFactory();
 TopologyModificationData topologyModificationData = topologyUpdateFactory.createTopologyModificationData();
 CI host = topologyModificationData.addCI("host");
 host.setPropertyValue("host_key", "test1");
 CI ip = topologyModificationData.addCI("ip");
 ip.setPropertyValue("ip_address", "127.0.0.10");
 ip.setPropertyValue("ip_domain", "DefaultDomain");
 topologyModificationData.addRelation("contained", host, ip);

 TopologyModificationData topologyCleanupData = topologyUpdateFactory.createTopologyModificationData();
 CI test_host = topologyCleanupData.addCI("host");
 test_host.setPropertyValue("host_key", "test2");

 TopologyModification topologyModification = topologyUpdateFactory.createTopologyModification();
 topologyModification.setDataForCreate(topologyModificationData).setDataForDelete(topologyCleanupData);

 topologyUpdateService.execute(topologyModification,ModifyMode.OPTIMISTIC);


 

Method Summary

Modifier and Type	Method and Description
CreateOutput	create(TopologyModificationData modificationData, CreateMode mode) Creates the specified set of CIs and relations in the UCMDB.
CreateStatus	createGracefully(TopologyModificationData modificationData, CreateGracefullyMode mode) Similar to create(TopologyModificationData, CreateMode), except that on failure, instead of throwing an exception, the given modificationData is split to smaller chunks that are processed individually.
DeleteOutput	delete(TopologyModificationData modificationData, DeleteMode mode) Deletes a set of CIs and relations from the UCMDB.
DeleteStatus	deleteGracefully(TopologyModificationData modificationData) Similar to delete(TopologyModificationData, DeleteMode), except that on failure, instead of throwing an exception, the given modificationData is split to smaller chunks that are processed individually.
ExecuteOutput	execute(TopologyModificationBulk topologyModificationBulk) Executes bulk of topology modifications
ExecuteOutput	execute(TopologyModification topologyModification, ModifyMode mode) Deprecated. Use execute(TopologyModificationBulk)
GracefulTopologyModificationOutput	executeGracefully(SingleTopologyModification topologyModification) Executes single topology modification gracefully.
TopologyUpdateFactory	getFactory()
MergeOutput	merge(MergeInput idsToMerge) Merge a set of CIs in the UCMDB.
void	touch(TopologyModificationData modificationData) Delays deletion of UCMDB CIs and relations due to aging.
UpdateOutput	update(TopologyModificationData modificationData) Updates a set of CIs and relations in the UCMDB.

Method Detail

getFactory

TopologyUpdateFactory getFactory()

create

CreateOutput create(TopologyModificationData modificationData,
                    CreateMode mode)
             throws UcmdbException

Creates the specified set of CIs and relations in the UCMDB.
Generally, the elements in modificationData have temporary IDs. All key attributes must be defined on these elements. This method calculates UCMDB IDs from the key attributes and replaces the temporary IDs. All key attributes must be specified in the input modificationData.
If the elements in modificationData have permanent UCMDB IDs, they are used only if the type of those elements is defined as having randomly generated IDs. The IDs specified are used to check whether the CIs and relations already exist.

Parameters:

modificationData - describes the CIs and relations to create

mode - specifies the behavior if items already exist. See the CreateMode enum.

Returns:

CreateOutput

Throws:

UcmdbException - in case of an exception

createGracefully

CreateStatus createGracefully(TopologyModificationData modificationData,
                              CreateGracefullyMode mode)

Similar to create(TopologyModificationData, CreateMode), except that on failure, instead of throwing an exception, the given modificationData is split to smaller chunks that are processed individually. That is done in attempt to isolate the failed CI and to process the input bulk as much as possible. Splitting is done logically by avoiding "breaking" relations that are essential in identifying the data.

Using this method may slow down performance when the modificationData causes failures, otherwise, performance is the same.

Parameters:

modificationData - describes the CIs and relations to create

mode - specifies the behavior if items already exist. See the CreateGracefullyMode enum.

Returns:

creation status for the created and failed CIs and relations

update

UpdateOutput update(TopologyModificationData modificationData)
             throws UcmdbException

Updates a set of CIs and relations in the UCMDB. If the specified CIs and relations do not exist, the operation fails and no elements are updated. You must specify the elements in modificationData with permanent UCMDB IDs.

Parameters:

modificationData - describes CIs and relations to update

Returns:

UpdateOutput

Throws:

UcmdbException - in case of an exception

touch

void touch(TopologyModificationData modificationData)
    throws UcmdbException

Delays deletion of UCMDB CIs and relations due to aging. If an element is neither updated nor touched for a sufficiently long time, it is deleted. The obsolescence period is configured per type in the UCMDB. Calling this method puts off the automatic deletion of the specified elements for another obsolescence period.

Parameters:

modificationData - Specifies the the CIs and relations to touch. This method only uses the IDs from the modificationData. Other properties are ignored.

Throws:

UcmdbException - in case of an exception

delete

DeleteOutput delete(TopologyModificationData modificationData,
                    DeleteMode mode)
             throws UcmdbException

Deletes a set of CIs and relations from the UCMDB.
These deletions may result in the deletion of additional elements. This occurs if elements in modificationData are the independent ends of relations that require deletion of dependent CIs.
The elements in modificationData be specified using have permanent UCMDB IDs.

Parameters:

modificationData - specifies the elements to delete

mode - specifies the behavior if items do not exist. See the DeleteMode enum.

Returns:

DeleteOutput

Throws:

UcmdbException - in case of an exception

deleteGracefully

DeleteStatus deleteGracefully(TopologyModificationData modificationData)

Similar to delete(TopologyModificationData, DeleteMode), except that on failure, instead of throwing an exception, the given modificationData is split to smaller chunks that are processed individually. That is done in attempt to isolate the failed CI and to process the input bulk as much as possible. Splitting is done logically by avoiding "breaking" relations that are essential in identifying the data.

Unlike delete(TopologyModificationData, DeleteMode), that has several deletion modes, this method supports a single mode: DeleteMode.IGNORE_NON_EXISTING.

Using this method may slow down performance when the modificationData causes failures, otherwise, performance is the same.

Parameters:

modificationData - specifies the elements to delete

Returns:

deletion status for the deleted and failed CIs and relations

execute

@Deprecated
ExecuteOutput execute(TopologyModification topologyModification,
                                  ModifyMode mode)
                           throws UcmdbException

Deprecated. Use execute(TopologyModificationBulk)

Modifies the specified set of CIs and relations in the UCMDB.
using the com.hp.ucmdb.api.topology.ModifyMode.OPTIMISTIC:

- When using the com.hp.ucmdb.api.topology.TopologyModification#setDataForCreate(...): is equivalent to com.hp.ucmdb.api.topology.CreateMode.UPDATE_EXISTING when calling to com.hp.ucmdb.api.topology.TopologyUpdateService#create(com.hp.ucmdb.api.topology.TopologyModificationData, com.hp.ucmdb.api.topology.CreateMode)

- When using the com.hp.ucmdb.api.topology.TopologyModification#setDataForUpdate(...): Will ignore non existing CIs (will not fail).

- When using the com.hp.ucmdb.api.topology.TopologyModification#setDataForDelete(...): is equivalent to com.hp.ucmdb.api.topology.DeleteMode.IGNORE_NON_EXISTING when calling to com.hp.ucmdb.api.topology.TopologyUpdateService#delete(com.hp.ucmdb.api.topology.TopologyModificationData, com.hp.ucmdb.api.topology.DeleteMode)

Parameters:

topologyModification - describes the CIs and relations to be modified

mode - specifies the behavior if CI or relation modification fails. See the ModifyMode enum.

Returns:

ExecuteOutput

Throws:

UcmdbException - in case of an exception

merge

MergeOutput merge(MergeInput idsToMerge)
           throws UcmdbException

Merge a set of CIs in the UCMDB. If the specified CIs do not exist, the operation fails and no elements are merged. You must specify the elements in modificationData with permanent UCMDB IDs.

Parameters:

idsToMerge - describes CIs to merge

Returns:

MergeOutput

Throws:

UcmdbException - in case of an exception

execute

ExecuteOutput execute(TopologyModificationBulk topologyModificationBulk)
               throws UcmdbException

Executes bulk of topology modifications

Parameters:

topologyModificationBulk - topology modification bulk

Returns:

the result of modification

Throws:

UcmdbException

Since:

UCMDB 10.1

executeGracefully

GracefulTopologyModificationOutput executeGracefully(SingleTopologyModification topologyModification)

Executes single topology modification gracefully. In case of a failure the given data is split to smaller chunks that are processed individually in attempt to isolate the failed CI and to process as much data as possible. Splitting avoids "breaking" relations that are essential in identifying the data.

Using this method may slow down performance when input causes failures. Otherwise, performance is the same.

Parameters:

topologyModification - specifies and the action to be taken on it

Returns:

the result of topology modification

Since:

UCMDB 10.1