com.cisco.provisioning.cpe.api
Interface IPDevice

All Superinterfaces:

ProvAPI

All Known Subinterfaces:

Batch

public interface IPDevice
extends ProvAPI

The IPDevice interface provides generic commands to manipulate IP Device objects and associated properties. APIs are defined with arguments and properties. Arguments are given to indicate the most commonly used fields that must be specified in an API call. In many cases, arguments may be set to NULL. Properties are specified in the form of a map containing key/value pairs.

Method Summary

void	add(DeviceType deviceType, List<DeviceID> deviceIDs, String hostName, String domainName, String ownerID, String cosName, String dhcpCriteria, Map<String,Object> properties) Add an IP Device.
void	addDeviceType(DeviceType deviceType) Adds a new custom DeviceType to the database.
void	addNode(NodeName nodeID, NodeType nodeType, Map<String,Object> properties) Adds a new node of the node type and name specified by the nodeID parameter.
void	addNodeType(NodeType nodeType) Adds a new node type with the specified node type name.
void	changeClassOfService(DeviceID deviceID, String newCOSName) Change the Class of Service of a device.
void	changeDefaults(DeviceType deviceType, Map<String,Object> newPropToAdd, List<String> propToDelete) Changes property defaults for the specified DeviceType.
void	changeDeviceID(DeviceID deviceID, List<DeviceID> newDeviceIDs) Change the existing device ID of a device and/or set the new device identifier to the exixting device ID.
void	changeDHCPCriteria(DeviceID deviceID, String newDHCPCriteria) Changes the DHCP Criteria for the the specified IP device.
void	changeDomainName(DeviceID deviceID, String newDomainName) Change the domain name of a device.
void	changeHostName(DeviceID deviceID, String newHostName) Change the host name of a device.
void	changeNodeName(NodeName nodeID, String newNodeName) Changes the name of a specified node.
void	changeNodeProperties(NodeName nodeID, Map<String,Object> changedProperties, List<String> propToDelete) Changes properties of the specified node.
void	changeNodeTypeProperties(NodeType nodeType, Map<String,Object> changedProperties, List<String> propToDelete) Changes the properties of specified node type.
void	changeOwnerID(DeviceID deviceID, String newOwnerID) Change the owner ID of a device.
void	changeProperties(DeviceID deviceID, Map<String,Object> newPropToAdd, List<String> propToDelete) Add, change, and remove properties to/from a device.
void	delete(DeviceID deviceID, boolean deleteDevicesBehind) Delete a device.
void	deleteDeviceType(DeviceType deviceType) Deletes an existing custom DeviceType from the database.
void	deleteNode(NodeName nodeID) Deletes the specified node from database.
void	deleteNodeType(NodeType nodeType) Deletes the specified node type from database.
void	getAllBehindDevice(DeviceID deviceID) Retrieve the List of device IDs downstream of a specific device.
void	getAllDeviceTypes() Retrieves a List of the pre-defined and custom DeviceType objects that have been entered in the system.
void	getAllForIPAddress(String ipAddress) Retrieves all known DHCP lease information about the specified IP Address from all provisioning groups.
void	getAllForIPAddress(String ipAddress, List<String> provGroups) Retrieves all known DHCP lease information about the specified IP Address within the specified provGroups parameter.
void	getAllForOwnerID(String ownerID) Retrieves a List of device identifier of all the devices that are matched with the specified ownerID Call ((RecordSearchResults)CommandStatus.getData()) on the return from this method to retrieve the data.
void	getAllNodeTypes() Returns a List containing all the NodeTypes defined in the system.
void	getDefaults(DeviceType deviceType) Retrieves the property defaults for the specified DeviceType.
void	getDetails(DeviceID deviceID, List<DeviceDetailsOption> options) Retrieve details of a device.
void	getNodeProperties(NodeName nodeID) Returns a Map containing properties of the specified node.
void	getNodeTypeProperties(NodeType nodeType) Returns a Map containing properties of the specified node type.
void	performOperation(DeviceOperation deviceOperation, DeviceID deviceID, Map<String,Object> parameters) Perform the task defined by the deviceOperation parameter.
void	regenConfigs(DeviceSearchType searchType) Submit a request to the RDU's Configuration Regeneration Service to regenerate configurations for the set of devices that match the specified searchType.
void	relateToIPDevice(NodeName nodeID, DeviceID deviceID) Associates a device to the specified node.
void	relateToNode(NodeName nodeID, NodeName relatedNodeID) Associates a node to the specified node.
void	searchDevice(DeviceSearchType searchType, SearchBookmark sb, int numberToReturn) Retrieve a list of Device object which satisfy a specific search criteria and search bookmark.
void	searchNode(NodeSearchType nodeSearchType, SearchBookmark sb, int numberToReturn) Retrieve a list of NodeName object which satisfies a specific search criteria and searchbookmark.
void	unregister(DeviceID deviceID) Unregister a device.
void	unrelateFromIPDevice(NodeName nodeID, DeviceID deviceID) Un-relate a device from a Node.
void	unrelateFromNode(NodeName nodeID, NodeName relatedNodeID) Unrelates a node from the specified node.

Method Detail

add

void add(DeviceType deviceType,
         List<DeviceID> deviceIDs,
         String hostName,
         String domainName,
         String ownerID,
         String cosName,
         String dhcpCriteria,
         Map<String,Object> properties)

Add an IP Device.

You must specify a device ID (e.g. MAC address or serial number) that is applicable for the device's type. If you specify an FQDN (or one is auto-generated), the device can be queried subsequently using either the device ID or the FQDN. See FqdnKeys for more information on FQDN auto-generation.

This method will fail if the deviceType parameter is null (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

A Batch containing this method will fail if the deviceType parameter is an unknown custom device type that has not yet been entered into the system (error: BatchStatusCode.BATCH_INVALID_LICENSES)

This method will fail if the device ID parameter is null or if it is specified in an improper format (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the cosName parameter is not null and begins with the TechnologyDefaultsKeys.DEFAULT_COS_PREFIX prefix (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the cosName parameter does not correspond to the name of an existing class of service (error: CommandStatusCode.CMD_ERROR_CLASS_OF_SERVICE_UNKNOWN)

This method will fail if the specified DUID corresponds to a device already in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_DUID_EXISTS)

This method will fail if the specified MAC Address corresponds to a device already in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_MAC_EXISTS)

This method will fail if the specified FQDN corresponds to a device already in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_FQDN_EXISTS)

This method will fail if the FQDN auto-generation properties are not properly set (errors: CommandStatusCode.CMD_ERROR_INVALID_AUTO_GEN_HOST_NAME) or CommandStatusCode.CMD_ERROR_INVALID_AUTO_GEN_DOMAIN)

For more on FQDN auto-generation, FqdnKeys

This method will fail if the FQDN auto-generation is disabled and the domainName parameter has a valid value but the hostName parameter is null or empty (errors: CommandStatusCode.CMD_ERROR_FQDN_INVALID)

This method will fail if (IPDeviceKeys.IP_RESERVATION) is used in the properties map but its value is null or improperly formatted (errors: CommandStatusCode.CMD_ERROR_IPADDRESS_INVALID)

This method will fail if IPDeviceKeys.IP_RESERVATION is specified in the properties map and the value is already use by another device (errors: CommandStatusCode.CMD_ERROR_IPADDRESS_INVALID)

This method will fail if IPDeviceKeys.MUST_BE_BEHIND_DEVICE is specified in the properties map and the value is invalid. (errors: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the properties specified in the properties parameter are relevant properties for the specified device type but the property value is null or data type is invalid. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

Parameters:

deviceType - Identifies the type of device to add. This value is required and cannot be null.

deviceIDs - An list of unique device identifier. This value is required and cannot be null.

hostName - The host name to assign to the new device. If FQDN auto-generation is configured, this must be null or a host name will not be generated. Also, if it is unknown or not applicable, specify null.

domainName - The domain name to assign to the new device. If FQDN auto-generation is configured, this must be null or a domain name will not be generated. Also, if it is unknown or not applicable, pass null.

ownerID - The owner identifier for the new device. This will often be an owner account number as maintained by the OSS. If the owner is unknown or not applicable, specify null.

cosName - The identifier of the class of service that is to be assigned to the new device. This class of service determines which template or configuration file should be used to build this device's configuration. This parameter is optional. If set to null, the device will be automatically assigned to the default class of service for its technology.

dhcpCriteria - The dhcpcriteria name for the new device.

properties - A map of key/value pairs to add to the specified device's property set. See specific DeviceType for the valid key names. This value is optional and can be specified as null.

Events fired:

DeviceListener.NEW_PROV_DEVICE

Relevant Property Keys:

See DeviceType for more information.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_FQDN_EXISTS
• CommandStatusCode.CMD_ERROR_DEVICE_MAC_EXISTS
• CommandStatusCode.CMD_ERROR_DEVICE_DUID_EXISTS
• CommandStatusCode.CMD_ERROR_CLASS_OF_SERVICE_UNKNOWN
• CommandStatusCode.CMD_ERROR_INVALID_AUTO_GEN_HOST_NAME
• CommandStatusCode.CMD_ERROR_INVALID_AUTO_GEN_DOMAIN
• CommandStatusCode.CMD_ERROR_FQDN_INVALID
• CommandStatusCode.CMD_ERROR_VALIDATE

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage - Add a device with MACAddress and DUID:

       ...
      List devIds = new ArrayList();
      devIds.add(new MACAddress("1,6,00:00:00:00:00:99"));
      devIds.add(new DUID("00:03:00:01:00:02:FC:A5:DC:1C"));
      
      String dhcpCriteria = "unprovisioned-docsis";
      
      Batch batch = conn.newBatch();
      batch.add(DeviceType.DOCSIS, devIds,
                "testHost", "testIsp.com", "testOwnerID", "testCoS", dhcpCriteria, null);
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeDeviceID

void changeDeviceID(DeviceID deviceID,
                    List<DeviceID> newDeviceIDs)

Change the existing device ID of a device and/or set the new device identifier to the exixting device ID.

Note: This API call may delete all un-registered devices behind the specified device. It may also unlink the registered devices behind this device until such relationship is reestablished through a reboot/restart.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter is not a valid device ID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the newDeviceID parameter is null or if it is specified in an improper format (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

This method will fail if the device ID specified by the newDeviceID parameter is a Mac Address and is already in use by another device (error: CommandStatusCode.CMD_ERROR_DEVICE_MAC_EXISTS)

This method will fail if the device ID specified by the newDeviceID parameter is a DUID and is already in use by another device (error: CommandStatusCode.CMD_ERROR_DEVICE_DUID_EXISTS)

This method will fail if the device ID specified by the newDeviceID parameter is a fqdn and is already in use by another device (error: CommandStatusCode.CMD_ERROR_DEVICE_FQDN_EXISTS)

Parameters:

deviceID - The unique identifier for this device. This can be either the current device ID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

newDeviceIDs - The new deviceIDs for the device. This parameter is required and cannot be null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN
• CommandStatusCode.CMD_ERROR_DEVICE_FQDN_EXISTS
• CommandStatusCode.CMD_ERROR_DEVICE_MAC_EXISTS
• CommandStatusCode.CMD_ERROR_DEVICE_DUID_EXISTS

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage - Change an existing DeviceID to a new DeviceID:

       ...
      List devIds = new ArrayList();
      devIds.add(new MACAddress("1,6,00:00:00:00:00:02"));
      Batch batch = conn.newBatch();
      batch.changeDeviceID(new MACAddress("1,6,00:00:00:00:00:01"),
                           devIds);
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

Sample Usage - Set DUID to an existing DeviceID:

       ...
      List devIds = new ArrayList();
      devIds.add(new DUID("00:00:00:00:00:89"));
      Batch batch = conn.newBatch();
      batch.changeDeviceID(new MACAddress("1,6,00:00:00:00:00:99"),
                           devIds);
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeHostName

void changeHostName(DeviceID deviceID,
                    String newHostName)

Change the host name of a device.

This method will fail if the device ID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the device specified by the device ID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

This method will fail if the device ID parameter is not a valid device ID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the newHostName parameter is null and the FQDN auto-generation properties are not properly configured (error: CommandStatusCode.CMD_ERROR_INVALID_AUTO_GEN_HOST_NAME)

For more on FQDN auto-generation, FqdnKeys

This method will fail if the FQDN auto-generation is disabled and the domainName is already exist in the device but the hostName parameter is null or empty (errors: CommandStatusCode.CMD_ERROR_FQDN_INVALID)

This method will fail if the FQDN formed with the new host name is already in use by another device (error: CommandStatusCode.CMD_ERROR_DEVICE_FQDN_EXISTS)

This method will fail if the MAC address already in use by another device (error: CommandStatusCode.CMD_ERROR_DEVICE_MAC_EXISTS)

This method will fail if the DUID already in use by another device (error: CommandStatusCode.CMD_ERROR_DEVICE_DUID_EXISTS)

Parameters:

deviceID - The unique identifier for this device. This can be either the current device ID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

newHostName - The new host name to assign to the device. If FQDN auto-generation is configured, this must be null or a host name will not be generated. Specify null if host name is unknown or not applicable.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN
• CommandStatusCode.CMD_ERROR_INVALID_AUTO_GEN_HOST_NAME
• CommandStatusCode.CMD_ERROR_FQDN_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_FQDN_EXISTS

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.changeHostName(new MACAddress("1,6,00:00:00:00:00:99"),
                           "myNewHostName");
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeDomainName

void changeDomainName(DeviceID deviceID,
                      String newDomainName)

Change the domain name of a device.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

This method will fail if the deviceID parameter is not a valid device ID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the newDomainName parameter is null and the FQDN auto generation feature is enabled in system defaults or in the properties hierarchy and the fqdn domain name properties defined in FqdnKeys are not properly configured (error: CommandStatusCode.CMD_ERROR_INVALID_AUTO_GEN_DOMAIN)

For more on FQDN auto-generation, FqdnKeys

This method will fail if the FQDN auto-generation is disabled and the domainName parameter has a valid value but the host name on existing device is null or empty (errors: CommandStatusCode.CMD_ERROR_FQDN_INVALID)

This method will fail if the FQDN formed with the new host name is already in use by another device (error: CommandStatusCode.CMD_ERROR_DEVICE_FQDN_EXISTS)

Parameters:

deviceID - The unique identifier for this device. This can be either the current deviceID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

newDomainName - The new domain name to assign to the device. If FQDN auto-generation is configured, this must be null or a domain name will not be generated. Specify null if domain name is unknown or not applicable.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN
• CommandStatusCode.CMD_ERROR_INVALID_AUTO_GEN_DOMAIN
• CommandStatusCode.CMD_ERROR_DEVICE_FQDN_EXISTS
• CommandStatusCode.CMD_ERROR_FQDN_INVALID

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
       ...
      Batch batch = conn.newBatch();
      batch.changeDomainName(new MACAddress("1,6,00:00:00:00:00:99"),
                             "myNewDomainName.com");
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeOwnerID

void changeOwnerID(DeviceID deviceID,
                   String newOwnerID)

Change the owner ID of a device.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter is not a valid device ID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

Parameters:

deviceID - The unique identifier for this device. This can be either the current deviceID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

newOwnerID - The new Owner ID to assign to the device. This value is optional and can be set to null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.changeOwnerID(new MACAddress("1,6,00:00:00:00:00:99"),
                          "newOwnerID");
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeClassOfService

void changeClassOfService(DeviceID deviceID,
                          String newCOSName)

Change the Class of Service of a device.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the Class of Service name is specified as null or if the specified class of service does not exist. (error: CommandStatusCode.CMD_ERROR_CLASS_OF_SERVICE_UNKNOWN)

This method will fail if the deviceID parameter is not a valid deviceID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

Parameters:

deviceID - The unique identifier for this device. This can be either the current device ID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

newCOSName - The identifier of the class of service to which this device will be assigned. This parameter is optional. If set to null or "", the device will automatically be assigned to the default class of service for the device's technology.

Events fired:

DeviceListener.CHANGED_COS

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_CLASS_OF_SERVICE_UNKNOWN
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      DeviceID id = new MACAddress("1,6,00:00:00:00:00:99");
      batch.changeClassOfService(id, "newClassOfServiceName");
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
       ...
 

See Also:

CommandStatusCode

changeDHCPCriteria

void changeDHCPCriteria(DeviceID deviceID,
                        String newDHCPCriteria)

Changes the DHCP Criteria for the the specified IP device.

Note: Changes the DHCP Criteria for the the specified IP device, in some cases, might cause the subsequent IP reservations in IPDevice.changeProperties(...) and/or IPDevice.changeMACAddress(...) to fail for the device. Caution should be taken to make sure the assigned client class and/or Include Selection Tags in the new DHCP Criteria falls into the same DHCP scope as the previously assigned client class and/or Include Selection Tags to avoid IP reservation failures.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceId parameter is not a valid MAC address or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the specified DHCP Criteria does not exist (error: CommandStatusCode.CMD_ERROR_DHCP_CRITERIA_UNKNOWN)

This method will fail if the IP device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

Parameters:

deviceID - The unique identifier for this IP device. This can be either the current macAddress or the fqdn (fully qualified domain name). This parameter is required and cannot be null.

newDHCPCriteria - The new DHCP criteria to assign to the IP device. Pass null if you want to use the default unprovisioned DHCP criteria for this technology..

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DHCP_CRITERIA_UNKNOWN
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN

Events fired:

DeviceListener.CHANGED_DHCP_CRITERIA

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.changeDHCPCriteria(new MACAddress("1,6,00:00:00:00:00:99"),
                               "newDHCPCriteria");
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeProperties

void changeProperties(DeviceID deviceID,
                      Map<String,Object> newPropToAdd,
                      List<String> propToDelete)

Add, change, and remove properties to/from a device.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter is not a valid device ID (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

This method will fail if the properties specified in the newPropToAdd parameter are relevant properties for the specified device but the property value is null or data type is invalid. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the property specified in the newPropToAdd parameter also exist in propToDelete parameter. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

Parameters:

deviceID - The unique identifier for this device. This can be MacAddress, DUID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

newPropToAdd - A map of key/value pairs to add/change to the specified device's property set. See specific DeviceType for the valid key names. This value is optional and can be specified as null.

propToDelete - A List of key names to remove from the properties Map. This value is optional and can be specified as null. If this list has value, the system will process this list first then process the newPropToAdd map.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE

Relevant Property Keys:

See DeviceType for more information.

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      
      Map newProperties = new HashMap();
      newProperties.put(FqdnKeys.AUTO_FQDN_DOMAIN, "cisco.com");
      newProperties.put(FqdnKeys.AUTO_FQDN_ENABLE, Boolean.TRUE);
      
      List removeProperties = null;
      batch.changeProperties(new MACAddress("1,6,00:00:00:00:00:99"),
                             newProperties, removeProperties);
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

delete

void delete(DeviceID deviceID,
            boolean deleteDevicesBehind)

Delete a device.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter is not a valid device ID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

Parameters:

deviceID - The unique identifier for this device. This can be either the current device ID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

deleteDevicesBehind - A boolean flag to determine whether to delete the devices (if any) behind the specified IP device. If deleteDevicesBehind flag is set to true, all devices behind the specified device will be deleted. If deleteDevicesBehind flag is set to false, unregistered devices behind the specified device will be deleted. Registered devices will have their discovered DHCP data and provisioning group relationship delete leaving only their registered data.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN
• CommandStatusCode.CMD_ERROR_WRITE

Events fired:

DeviceListener.DELETED_DEVICE

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.delete(new MACAddress("1,6,00:00:00:00:00:99"), true);
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

getDetails

void getDetails(DeviceID deviceID,
                List<DeviceDetailsOption> options)

Retrieve details of a device. If the client chooses to retreive DHCP leases information see DeviceDetailsOption.INCLUDE_LEASE_INFO and the device has DHCP leases, this call will return the lease information in both IPv4 and IPv6.

Note: This method will result in a batch warning ( BatchStatusCode.BATCH_WARNING), if the includeLeaseInfo flag is set to true and the DHCP servers could not be contacted in order to obtain any active lease information.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter is not a valid device ID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

Parameters:

deviceID - The unique identifier for this device. This parameter is required and cannot be null.

options - A List of DeviceDetailsOption. This list controls inclusion of optional result content. This parameter may be specified as null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN

Returned Property Keys:

• GenericObjectKeys.OID_REVISION_NUMBER
• See DeviceDetailsKeys for more details

Returned Data Type code:

CommandStatus.DATA_MAP

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      DeviceID id = new MACAddress("1,6,00:00:00:00:00:99");
      batch.getDetails(id, null);
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeDefaults

void changeDefaults(DeviceType deviceType,
                    Map<String,Object> newPropToAdd,
                    List<String> propToDelete)

Changes property defaults for the specified DeviceType.

This method will fail if the deviceType parameter is specified as null or it specifies a DeviceType that does not exist in the database (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the default DHCP Criteria and Class of Service are not present as a result of the changes specified in the parameters to this call (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the default DHCP Criteria specified in the parameters to this call does not exists in the database (error: CommandStatusCode.CMD_ERROR_DHCP_CRITERIA_UNKNOWN)

This method will fail if the default Class of Service specified in the parameters to this call does not exists in the database (error: CommandStatusCode.CMD_ERROR_CLASS_OF_SERVICE_UNKNOWN)

This method will fail if the properties specified in the newPropToAdd parameter are not relevant properties for the specified device type (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the properties specified in the newPropToAdd parameter are relevant properties for the specified device type but the property value is null or invalid. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the property specified in the newPropToAdd parameter also exist in propToDelete parameter. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

The batch containing a call to this method will fail if properties that attach classes to extension points are invalid as a result of the changes specified in the parameters to this call (error: BatchStatusCode.BATCH_FAILED_EXTENSION_RELOAD)

Parameters:

deviceType - Identifies the device type to change the defaults for. This value is required and cannot be null.

newPropToAdd - A map of key/value pairs to add/change in the specified device properties Map. See DeviceType for the valid key names. This value is optional and can be specified as null.

propToDelete - A List of key names to remove from the defaults Map. This value is optional and can be specified as null. If this list has value, the system will process this list first then process the newPropToAdd map.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_VALIDATE

Relevant Property Keys:

See DeviceType for more information.

Events fired:

DeviceTypeListener.DEVICE_TYPE_PROPS_CHANGE

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      Map propsToUpdate = new HashMap();
          propsToUpdate.put(FqdnKeys.AUTO_FQDN_ENABLE, Boolean.TRUE);
          
      List propsToremove = null;
      batch.changeDefaults(DeviceType.DOCSIS,
                           propsToUpdate, propsToRemove);
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

BatchStatusCode, CommandStatusCode

getDefaults

void getDefaults(DeviceType deviceType)

Retrieves the property defaults for the specified DeviceType.

This method will fail if the deviceType parameter is specified as null or it specifies a DeviceType that does not exist in the database (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

Parameters:

deviceType - Identifies the type device to retrieve the defaults for. This value is required and cannot be null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE

Returned Data Type code:

CommandStatus.DATA_MAP

Returned Property Keys:

• GenericObjectKeys.OID_REVISION_NUMBER
• See TechnologyDefaultsKeys for more details

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.getDefaults(DeviceType.DOCSIS);

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

addDeviceType

void addDeviceType(DeviceType deviceType)

Adds a new custom DeviceType to the database.

This method will fail if the deviceType parameter is specified as null (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the deviceType parameter represents a type that is already in the database (error: CommandStatusCode.CMD_ERROR_CUSTOM_CPE_TYPE_EXISTS)

The batch containing a call to this method will fail if the batch does not also contain a call to the changeDefaults method that configures clases for the required configuration generation and disruption extension points (error: BatchStatusCode.BATCH_FAILED_EXTENSION_RELOAD)

Parameters:

deviceType - Identifies the custom device type to add. This value is required and cannot be null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_CUSTOM_CPE_TYPE_EXISTS

Events fired:

DeviceTypeListener.NEW_DEVICE_TYPE

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.addDeviceType(DeviceType.getDeviceType("MyNewDeviceType");
      
      Map propsToUpdate = new HashMap();
      propsToUpdate.put(
          TechnologyDefaultsKeys.CONFIG_GENERATION_EXTENSION_POINT,
          "extensions.buildin.configgeneration.MyNewDeviceType";
         
      propsToUpdate.put(
         TechnologyDefaultsKeys.ACTIVATION_EXTENSION_POINT,
         "extensions.buildin.disruption.MyNewDeviceType");

      propsToUpdate.put(
          TechnologyDefaultsKeys.SERVICE_LEVEL_SELECTION_EXTENSION_POINT,
          "extensions.buildin.service.MyNewDeviceType");
   
      propsToUpdate.put(
          TechnologyDefaultsKeys.DEFAULT_CLASS_OF_SERVICE,
          "unprovisioned-docsis");
          
      propsToUpdate.put(
          TechnologyDefaultsKeys.DEFAULT_DHCP_CRITERIA,
          "unprovisioned-docsis");
        batch.changeDefaults(DeviceType.getDeviceType("MyNewDeviceType"),
                         propsToUpdate, null);

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

BatchStatusCode, CommandStatusCode, TechnologyDefaultsKeys.ACTIVATION_EXTENSION_POINT, TechnologyDefaultsKeys.CONFIG_GENERATION_EXTENSION_POINT, TechnologyDefaultsKeys.SERVICE_LEVEL_SELECTION_EXTENSION_POINT, TechnologyDefaultsKeys.DEFAULT_CLASS_OF_SERVICE, TechnologyDefaultsKeys.DEFAULT_DHCP_CRITERIA

deleteDeviceType

void deleteDeviceType(DeviceType deviceType)

Deletes an existing custom DeviceType from the database. This will also delete all the classes of service of the device type being deleted.

This method will fail if the deviceType parameter is specified as null or if the specified device type is not a custom device type (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the deviceType parameter represents a type that is not already in the database (error: CommandStatusCode.CMD_ERROR_CUSTOM_CPE_TYPE_UNKNOWN)

Parameters:

deviceType - Identifies the custom device type to remove. This value is required and cannot be null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_CUSTOM_CPE_TYPE_UNKNOWN
• CommandStatusCode.CMD_ERROR_WRITE

Events fired:

DeviceTypeListener.DELETED_DEVICE_TYPE

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      DeviceType deviceType =
          DeviceType.getDeviceType("MyNewDeviceType");
      batch.deleteDeviceType(deviceType);

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

performOperation

void performOperation(DeviceOperation deviceOperation,
                      DeviceID deviceID,
                      Map<String,Object> parameters)

Perform the task defined by the deviceOperation parameter.

This method will fail if the deviceOperation parameter is specified as null (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the properties specified in the parameters parameter are relevant properties for the specified device operation but the property value is null or data type is invalid. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter is not a valid MAC address or DUID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail (error: CommandStatusCode.CMD_ERROR_VALIDATE) if the batch flags used are not supported by the deviceOperation parameter specified. Please see DeviceOperation for more details.

This method will fail if the specified deviceID parameter does not specify a device that is in the database (error: CommandStatusCode.CMD_ERROR_WRITE)

This method will fail if performing the DeviceOperation.CHANGE_PROVISIONING_GROUP operation and the specified provisioning group does not exist in the database (error: CommandStatusCode.CMD_ERROR_PROVISIONING_GROUP_UNKNOWN) This method will fail if performing the DeviceOperation.ENABLE_SNMPV3_ACCESS or DeviceOperation.INCREMENTAL_UPDATE or operation and the lease info are not available (error: CommandStatusCode.CMD_ERROR_LEASE_INFO_NOT_AVAILABLE)

This method will fail if performing

Parameters:

deviceOperation - The operation to perform on the specified device

deviceID - The unique identifier for this IP device. This can be either the current macAddress, duid or the fqdn (fully qualified domain name). This parameter is required and cannot be null.

parameters - A Map of parameters for the specified DeviceOperation

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_WRITE
• CommandStatusCode.CMD_ERROR_UNKNOWN_DEVICE_OPERATION
• CommandStatusCode.CMD_ERROR_PROVISIONING_GROUP_UNKNOWN
• CommandStatusCode.CMD_ERROR_LEASE_INFO_NOT_AVAILABLE

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch(ActivationMode.AUTOMATIC);
      batch.performOperation(DeviceOperation.RESET,
                             new MACAddress("1,6,00:00:00:00:00:99"), 
                             null);
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

regenConfigs

void regenConfigs(DeviceSearchType searchType)

Submit a request to the RDU's Configuration Regeneration Service to regenerate configurations for the set of devices that match the specified searchType. The submitted request will be queued for processing. The command will return immediately. When the RDU completes the regeneration, a CRSCompleteEvent event will be fired containing the batch ID of the batch which submitted the original request.

This method will fail if the searchType parameter is specified as null (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

NOTE - On success, this method will return a batch warning (BatchStatusCode.BATCH_WARNING), describing that a CRSCompleteEvent event will be fired when CRS has completed processing the request.

Parameters:

searchType - defines the set of devices for which configurations will be generated.

Events fired:

CRSCompleteListener.CRS_COMPLETED

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.regenConfigs(
          DeviceSearchType.getByDeviceType(
              DeviceType.DOCSIS, ReturnParameters.ALL));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

getAllDeviceTypes

void getAllDeviceTypes()

Retrieves a List of the pre-defined and custom DeviceType objects that have been entered in the system. If there is no pre-defined or custom device type, an empty List will be returned.

Returned Command Status codes:

• CommandStatusCode.CMD_OK

Returned Data Type code:

• CommandStatus.DATA_LIST

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.getAllDeviceTypes();

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode, CommandStatus, List

getAllForIPAddress

void getAllForIPAddress(String ipAddress)

Retrieves all known DHCP lease information about the specified IP Address from all provisioning groups. This method returns a LeaseResults object on success.

This method will fail if the ipAddress parameter is null or if it is not in the form of a valid IP address (error: CommandStatusCode.CMD_ERROR_IPADDRESS_INVALID)

This method will fail if the the DHCP server could not be contacted to retrieve the DHCP lease information (error: CommandStatusCode.CMD_ERROR_LEASE_INFO_NOT_AVAILABLE)

Parameters:

ipAddress - The IP address to search for lease information. This parameter is required and can not be specified as null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_IPADDRESS_INVALID
• CommandStatusCode.CMD_ERROR_LEASE_INFO_NOT_AVAILABLE

Returned Data Type code:

CommandStatus.DATA_LEASE_RESULTS

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.getAllForIPAddress("10.0.0.123");

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

getAllForIPAddress

void getAllForIPAddress(String ipAddress,
                        List<String> provGroups)

Retrieves all known DHCP lease information about the specified IP Address within the specified provGroups parameter.

Call ((LeaseResults)CommandStatus.getData()) on the return from this method to retrieve the data.

This method will fail if the ipAddress parameter is null or if it is not in the form of a valid IP address (error: CommandStatusCode.CMD_ERROR_IPADDRESS_INVALID)

This method will fail if the provGroups List contains a non-String value (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the provGroups List contains a provisioning group name that is unknown (error: CommandStatusCode.CMD_ERROR_PROVISIONING_GROUP_UNKNOWN)

This method will fail if the the DHCP server could not be contacted to retreive the DHCP lease information (error: CommandStatusCode.CMD_ERROR_LEASE_INFO_NOT_AVAILABLE)

Parameters:

ipAddress - The IP address to search for lease information. This parameter is required and can not be specified as null.

provGroups - a list of provisining group names to search for lease information about the specified ipAddress. This parameter is optional. If specified as null, all provisioning groups will be searched.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_IPADDRESS_INVALID
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_PROVISIONING_GROUP_UNKNOWN
• CommandStatusCode.CMD_ERROR_LEASE_INFO_NOT_AVAILABLE

Returned Data Type code:

CommandStatus.DATA_LEASE_RESULTS

Sample Usage:

       ...
      List provGroupsToSearch = new ArrayList();
      provGroupsToSearch.add("docsisProGroup");
      
      Batch batch = conn.newBatch();
      batch.getAllForIPAddress("10.0.0.123", provGroupsToSearch);

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

getAllForOwnerID

void getAllForOwnerID(String ownerID)

Retrieves a List of device identifier of all the devices that are matched with the specified ownerID

Call ((RecordSearchResults)CommandStatus.getData()) on the return from this method to retrieve the data. If there are records that match with the specified ownerID, this CommandStatus.DATA_RECORD_SEARCH_RESULTS will contain a list of Key object which is a DeviceID object, otherwise, the List in will be empty.

This method will fail if the ownerID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the specified ownerID does not exist in the database (error: CommandStatusCode.CMD_ERROR_OWNERID_UNKNOWN)

Parameters:

ownerID - The name of the ownerID to retrieve the devices for. This parameter is required and cannot be specified as null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_OWNERID_UNKNOWN

Returned Data Type code:

• CommandStatus.DATA_RECORD_SEARCH_RESULTS

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.getAllForOwnerID("ownerid1");

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
      
      
      //batch success without error, retrieve the result
      RecordSearchResults results = (RecordSearchResults)commandStatus.getData();
      List detailList = results.getRecordData();
   
      if (detailList != null)
      {
          //getting the data
          for (int i=0; i<detailList.size(); i++)
          {
              RecordData dataObj = (RecordData)detailList.get(i);
           
              // get the list of the devices
              List devices = dataObj.getSecondaryKeys();
           
          }
      }
     
     
     
 

See Also:

CommandStatusCode, CommandStatus

getAllBehindDevice

void getAllBehindDevice(DeviceID deviceID)

Retrieve the List of device IDs downstream of a specific device.

Call ((List)CommandStatus.getData()) on the return from this method to retrieve the data. The List will consist of String that is the devices identifer. If the device does not act as a relay agent or does not have any devices downstream of it, then an empty List will be returned.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter is not a valid device ID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if there is no device with the specified deviceID that exists in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

Parameters:

deviceID - The unique identifier for this device. This can be either the current device ID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN

Returned Data Type code:

• CommandStatus.DATA_NULL
• CommandStatus.DATA_LIST

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.getAllBehindDevice(new MACAddress("1,6,00:00:00:00:00:99"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

searchDevice

void searchDevice(DeviceSearchType searchType,
                  SearchBookmark sb,
                  int numberToReturn)

Retrieve a list of Device object which satisfy a specific search criteria and search bookmark.

Call ((RecordSearchResults)CommandStatus.getData()) on the return from this method to retrieve the data. If there are records that match the search criteria and search bookmark, this CommandStatus.DATA_RECORD_SEARCH_RESULTS will contain a list of Key object which is a DeviceID object, otherwise, the List in will be empty.

This method will fail if the searchType parameter is specified as null (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the numberToReturn parameter is specified as negative or 0. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

Parameters:

searchType - A DeviceSearchType describing the search to perform DeviceSearchType.

sb - A SearchBookmark from which the search will begin. If this is null, the search will begin from the first device matched SearchBookmark.

numberToReturn - Specify how many matching records to be returned from the search query.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_CLASS_OF_SERVICE_UNKNOWN
• CommandStatusCode.CMD_ERROR_DHCP_CRITERIA_UNKNOWN
• CommandStatusCode.CMD_ERROR_PROV_GROUP_UNKNOWN
• CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND
• CommandStatusCode.CMD_ERROR_UNKNOWN_TECHNOLOGY_NAME

Returned Data Type code:

CommandStatus.DATA_RECORD_SEARCH_RESULTS

Sample Usage:

       ...
       
 public static void getAllDevicesByDeviceType() throws Exception
 {
      DeviceSearchType dst = DeviceSearchType.getByDeviceType(
          DeviceType.getDeviceType(DeviceTypeValues.DOCSIS_MODEM), 
          ReturnParameters.ALL);
          
      RecordSearchResults rs = null;
      
      SearchBookmark sb = null;
      
      rs = searchDevice(dst, sb);
      sb = rs.getSearchBookmark();
      
      while (sb != null)
      {
          // print out the data in the record search result.
          sb = printRecordSearchResults(rs);
          
          // call the search routine again
          rs = searchDevice(dst, sb);                
      }
 }
 
 private static RecordSearchResults searchDevice(DeviceSearchType dst,
                SearchBookmark sb) throws Exception
 {
      RecordSearchResults rs = null;
      final Batch batch = s_conn.newBatch();
      final int numberOfRecordReturn = 10;
      
      //calling the search API
      batch.searchDevice(dst, sb, numberOfRecordReturn);
      
      // Call the RDU.
      BatchStatus batchStatus = batch.post();
      
      // Check for success.
      CommandStatus commandStatus = null;
      
      if (0 < batchStatus.getCommandCount())
      {
          commandStatus = batchStatus.getCommandStatus(0);
      }
      
      //check to see if there is an error
      if (batchStatus.isError()
      || batchStatus.isWarning()
      || commandStatus == null 
      || commandStatus.isError())
      {
          System.out.println("report batch error.");
          return null;
      }
      
      //batch success without error, retrieve the result
      //this is a list of devices
      rs = (RecordSearchResults)commandStatus.getData();
      return rs;
 }
 

 private static SearchBookmark printRecordSearchResults(RecordSearchResults rs) 
 throws Exception
 {
   
      SearchBookmark sb = rs.getSearchBookmark();

      List<RecordData> rdlist = rs.getRecordData();
      Iterator<RecordData> iter = rdlist.iterator();
   
      while (iter.hasNext())
      {
          RecordData rdObj = iter.next();
          Key keyObj = rdObj.getPrimaryKey();
       
           System.out.println("DeviceOID: " + ((DeviceID)keyObj).getDeviceId());
      
          //this is for secondary keys.
          List<Key> deviceList = rdObj.getSecondaryKeys();
       
          if (deviceList != null && !deviceList.isEmpty())
          {
              for (int i=0; i<deviceList.size(); i++)
              {
                  Key key = deviceList.get(i);
                  System.out.println("DeviceID : " + key.toString());
              }
          }
      }
      return sb;
   
 }
   ...
 

See Also:

CommandStatusCode

searchNode

void searchNode(NodeSearchType nodeSearchType,
                SearchBookmark sb,
                int numberToReturn)

Retrieve a list of NodeName object which satisfies a specific search criteria and searchbookmark.

Call ((RecordSearchResults)CommandStatus.getData()) on the return from this method to retrieve the data. If there are records that match the search criteria and search bookmark, this CommandStatus.DATA_RECORD_SEARCH_RESULTS will contains a list of Key objects which is a NodeName object, otherwise, the List is empty.

This method will fail if the nodeSearchType parameter is specified as null or nodeSearchType is invalid (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the numberToReturn parameter is specified as negative or 0. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

Parameters:

nodeSearchType - The NodeSearchType describing the search to perform.

sb - The SearchBookmark from which to start the search. If this is null, the search will begin from the first node matched.

numberToReturn - Specify how many matching records to be returned from the search query.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND
• CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND

Returned Data Type code:

CommandStatus.DATA_RECORD_SEARCH_RESULTS

Sample Usage:

       ...
   // Create the batch.
   //
   Batch batch = s_conn.newBatch();
   
   // We will be searching for nodes of type "SampleType".
   //
   NodeType nodeType = NodeType.getNodeType("SampleType");
   
   // Search filter specifies search for all nodes of type "SampleType",
   // including first match, maximum of 100 results to be returned.
   //
   NodeSearchType nst = 
      NodeSearchType.getByNodeType(nodeType);
   
   SearchBookmark sb = null;
   
   // Add the search API call to the batch.
   // Execute the batch.
   //
   batch.searchNode(nst, sb, 100);
   BatchStatus bs = batch.post(5000);
   if ( bs.isError() )
   {
       fail(bs);
   }
   else
   {
       pass(bs);
   }
   
   CommandStatus commandStatus = null;
   if (0 < bs.getCommandCount())
   {
       commandStatus = bs.getCommandStatus(0);
   }
   

   //batch success without error, retrieve the result
   RecordSearchResults results = (RecordSearchResults)commandStatus.getData();
   List nodeList = results.getRecordData();
   
   if (nodeList != null)
   {
       //getting the data
       for (int i=0; i<nodeList.size(); i++)
       {
           RecordData dataObj = (RecordData)nodeList.get(i);
           
           // the Key object should be the NodeName class
           Key obj = dataObj.getPrimaryKey();
           
       }
   }
   ...
 

See Also:

CommandStatusCode, CommandStatus, RecordSearchResults

unregister

void unregister(DeviceID deviceID)

Unregister a device. If the device is registered, transition the device to the unregistered state. If the device is unregistered, it will be deleted from the database.

This method will fail if the deviceID parameter is specified as null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter is not a valid device ID or FQDN (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the deviceID does not specify a device that is in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

Parameters:

deviceID - The unique identifier for this device. This can be either the current device ID or the FQDN (fully qualified domain name). This parameter is required and cannot be null.

Returned Command Status codes:

• CommandStatusCode.CMD_OK
• CommandStatusCode.CMD_ERROR_VALIDATE
• CommandStatusCode.CMD_ERROR_DEVICEID_INVALID
• CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE
• CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN
• CommandStatusCode.CMD_ERROR_DEVICE_UNREGISTER_UNREGISTERED_ERROR
• CommandStatusCode.CMD_ERROR_DEVICE_UNREGISTER_OFFLINE_ERROR

Events fired:

DeviceListener.DELETED_DEVICE

DeviceListener.CHANGED_COS

DeviceListener.CHANGED_DHCP_CRITERIA

Returned Data Type code:

CommandStatus.DATA_VOID

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.unregister(new MACAddress("1,6,00:00:00:00:00:99"));
      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

addNodeType

void addNodeType(NodeType nodeType)

Adds a new node type with the specified node type name.

This method will fail if the nodeType parameter is null or invalid. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the a Node Type with the specified name already exists in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_EXISTS)

Parameters:

nodeType - The NodeType object representing the node being defined. Required.

Events fired:

NodeTypeListener.NEW_NODE_TYPE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.addNodeType(NodeType.getNodeType("MyNodeType"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeNodeTypeProperties

void changeNodeTypeProperties(NodeType nodeType,
                              Map<String,Object> changedProperties,
                              List<String> propToDelete)

Changes the properties of specified node type.

This method will fail if the nodeType parameter is null or invalid. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if a Node Type with the specified name is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

This method will fail if the changedProperties Map contain unrecognized/ invalid parameters or property value is null or data type is invalid. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the property specified in the changedProperties parameter also exist in propToDelete parameter. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

Parameters:

nodeType - The NodeTypeobject representing the node type being changed. Required.

changedProperties - A map of key/value pairs to add/change in the specified node type properties Map. This value is optional and can be specified as null.

propToDelete - A List of key names to remove from the node type properties Map. This value is optional and can be specified as null. If this list has value, the system will process this list first then process the changedProperties map.

Events fired:

NodeTypeListener.CHANGED_NODE_TYPE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.changeNodeTypeProperties(Nodetype.getNodeType("MyNodeType")
                       changedProperties, propToDelete);

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

getNodeTypeProperties

void getNodeTypeProperties(NodeType nodeType)

Returns a Map containing properties of the specified node type. Returns an empty Map if the node type has no properties associated with it.

This method will fail if the nodeType parameter is null or invalid. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if a Node Type with the specified name is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

Parameters:

nodeType - The NodeType object representing the node type being used for the query. Required.

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.getNodeTypeProperties(NodeType.getNodeType("MyNodeType"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

getAllNodeTypes

void getAllNodeTypes()

Returns a List containing all the NodeTypes defined in the system. Returns an empty list if there are no NodeTypes present in the system.

Returned Command Status codes:

• CommandStatusCode.CMD_OK

Returned Data Type code:

• CommandStatus.DATA_LIST

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.getAllNodeTypes();

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode, CommandStatus, List

deleteNodeType

void deleteNodeType(NodeType nodeType)

Deletes the specified node type from database. All nodes in the specified node type will also be deleted. This API call will also unlink all the relationships between nodes of the specified type with other nodes and devices.

This method will fail if the nodeType parameter is null (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if a Node Type with the specified name is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

Parameters:

nodeType - The NodeTypeobject representing the node type being deleted. Required.

Events fired:

NodeTypeListener.DELETDE_NODE_TYPE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.deleteNodeType(NodeType.getNodeType("MyNodeType"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

addNode

void addNode(NodeName nodeID,
             NodeType nodeType,
             Map<String,Object> properties)

Adds a new node of the node type and name specified by the nodeID parameter.

This method will fail if the nodeID parameter is null. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if a Node Type with the specified name is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

This method will fail if the a node with the specified name already exists in the database(error: CommandStatusCode.CMD_ERROR_NODE_EXISTS)

This method will fail if the properties Map contain unrecognized/ invalid parameters or property value is null or data type is invalid. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

Parameters:

nodeID - The Nodeobject representing the node being added. Required.

properties - A map of key/value pairs containing the properties of this node. This value is optional and can be specified as null.

Events fired:

NodeListener.NEW_NODE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.addNode(NodeName.getNodeName("MyNode"), 
                        NodeType.getNodeType("NodeType"),
                        null);

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeNodeProperties

void changeNodeProperties(NodeName nodeID,
                          Map<String,Object> changedProperties,
                          List<String> propToDelete)

Changes properties of the specified node.

This method will fail if the nodeID parameter is null. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if a node type specified is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

This method will fail if a node with the specified name is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND)

This method will fail if the changedProperties Map contain unrecognized/ invalid parameters or property value is null or data type is invalid. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the property specified in the changedProperties parameter also exist in propToDelete parameter. (error: CommandStatusCode.CMD_ERROR_VALIDATE)

Parameters:

nodeID - The NodeNameobject representing the node being updated. Required.

changedProperties - A map of key/value pairs to add/change in the specified node's properties Map. This value is optional and can be specified as null.

propToDelete - A List of key names to remove from the node's properties Map. This value is optional and can be specified as null. If this list has value, the system will process this list first then process the changedProperties map.

Events fired:

NodeListener.CHANGED_NODE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.changeNodeProperties(NodeName.getNodeName("MyNodeName"),
                       changedProperties, propToDelete);

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

changeNodeName

void changeNodeName(NodeName nodeID,
                    String newNodeName)

Changes the name of a specified node.

This method will fail if the nodeID parameter is null. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if a node type specified is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

This method will fail if a node with the specified name is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND)

This method will fail if a node of the same type and specified "newNodeName" already exists in the database(error: CommandStatusCode.CMD_ERROR_NODE_EXISTS)

Parameters:

nodeID - The NodeNameobject representing the node being updated. Required.

newNodeName - A string representing the new name for the node specified.

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.changeNodeName(NodeName.getNodeName("MyNodeName"),
                           "MyNewNodeName");

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

getNodeProperties

void getNodeProperties(NodeName nodeID)

Returns a Map containing properties of the specified node.

This method will fail if the nodeID parameter is null. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if a node type specified is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

This method will fail if a node with the specified name is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND)

Parameters:

nodeID - The NodeNameobject representing the node being queried. Required.

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.getNodeProperties(NodeName.getNodeName("MyNodeName"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

deleteNode

void deleteNode(NodeName nodeID)

Deletes the specified node from database. This method also unlinks all relationship between the specified node and other devices and/or nodes.

This method will fail if the nodeID parameter is null. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if node type is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

This method will fail if a node with the specified name is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND)

Parameters:

nodeID - The NodeNameobject representing the node being deleted. Required.

Events fired:

NodeListener.DELETED_NODE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.deleteNode(NodeName.getNodeName("MyNodeName"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

relateToIPDevice

void relateToIPDevice(NodeName nodeID,
                      DeviceID deviceID)

Associates a device to the specified node.

This method will fail if the nodeID parameter is null. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the nodeID specified is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND)

This method will fail if the deviceID parameter null (error: CommandStatusCode.CMD_ERROR_VALIDATE)

This method will fail if the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

This method will fail if the deviceID parameter is not a valid device identifier (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if a device added to the system:diagnostics node exceeds the maximum allowable for that node(error: CommandStatusCode.CMD_ERROR_MAXIMUM_DEVICE_COUNT_EXCEEDED)

Parameters:

nodeID - The NodeName object representing the node being updated. Required.

deviceID - The DeviceID being added to the speficied node name. Required.

Events fired:

NodeListener.RELATE_TO_IPDEVICE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.relateToIPDevice(NodeName.getNodeName("MyNodeName"),
                       new MACAddress("1,6,00:00:00:00:00:11"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

relateToNode

void relateToNode(NodeName nodeID,
                  NodeName relatedNodeID)

Associates a node to the specified node.

This method will fail if the nodeID/relatedNodeID parameter is/are null. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if any of the nodeID/relatedNodeID specified are not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND)

Parameters:

nodeID - The NodeNameobject representing the first node. Required.

relatedNodeID - The NodeNameobject representing the second node. Required.

Events fired:

NodeListener.RELATE_TO_NODE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.relateToNode(NodeName.getNodeName("MyNodeName"),
                       NodeName.getNodeName("RelatedNodeName"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

unrelateFromIPDevice

void unrelateFromIPDevice(NodeName nodeID,
                          DeviceID deviceID)

Un-relate a device from a Node.

This method will fail if the nodeID parameter is null. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the NodeType specified in the nodeID parameter is not found in the database (error:CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

This method will fail if the Node specified by the nodeID parameter is not found in the database(error: CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND)

This method will fail if the device specified by the deviceID parameter does not exist in the database (error: CommandStatusCode.CMD_ERROR_DEVICE_ID_UNKNOWN)

This method will fail if the device ID parameter is not a valid device ID (error: CommandStatusCode.CMD_ERROR_DEVICEID_INVALID)

This method will fail if the device specified by the deviceID parameter is not related to the specified Node (error: CommandStatusCode.CMD_ERROR_DEVICE_IS_NOT_RELATED_TO_NODE)

Parameters:

nodeID - The Node from which the device will be dis-associated. This parameter is required and can not be specified as null.

deviceID - The ID of the device to be dis-associated from the specified node. This parameter is required and can not be specified as null.

Events fired:

NodeListener.UNRELATE_FROM_IPDEVICE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.unrelateFromIPDevice(NodeName.getNodeName("MyNodeName"),
                       new MACAddress("1,6,00:00:00:00:00:99"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode

unrelateFromNode

void unrelateFromNode(NodeName nodeID,
                      NodeName relatedNodeID)

Unrelates a node from the specified node.

This method will fail if the nodeType and/or nodeName specified in the nodeID parameter is/are null or empty or blank or invalid. (error: CommandStatusCode.CMD_ERROR_ILLEGAL_PARAM_VALUE)

This method will fail if the any of the node types specified in nodeID/relatedNodeID are not found in the database (error: CommandStatusCode.CMD_ERROR_NODE_TYPE_NOT_FOUND)

This method will fail if any of the nodes specified by nodeID/ relatedNodeID is not found in the database (error:CommandStatusCode.CMD_ERROR_NODE_NOT_FOUND)

This method will fail if the node specified using nodeID parameter is not related to the node specified relatedNodeID (error: CommandStatusCode.CMD_ERROR_NODE_IS_NOT_RELATED_TO_NODE)

Parameters:

nodeID - The NodeNameobject representing the first node. Required.

relatedNodeID - The NodeNameobject representing the second node. Required.

Events fired:

NodeListener.UNRELATE_FROM_NODE

Sample Usage:

       ...
      Batch batch = conn.newBatch();
      batch.unrelateFromNode(NodeName.getNodeName("MyNodeName"),
                       NodeName.getNodeName("RelatedNodeName"));

      BatchStatus status = batch.post();
      if ( status.isError() )
      {
          fail(status);
      }
      else
      {
          pass(status);
      }
       ...
 

See Also:

CommandStatusCode