Package 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 Details

    • 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

    • deleteEnrichmentByName

      boolean deleteEnrichmentByName(String enrichmentName)
      Deletes an enrichment rule by name
      Parameters:
      enrichmentName - name of the enrichment that has to bedeleted
      Returns:
      boolean variable representing the status of the delete operation

    • deleteCorrelationByName

      boolean deleteCorrelationByName(String correlationName)
      Deletes a correlation by name
      Parameters:
      correlationName - name of the correlation rule that has to be deleted
      Returns:
      boolean variable representing the status of the delete operation