com.bmc.cmdb.api
Class CMDBInstance

java.lang.Object
  com.bmc.cmdb.api.CMDBInstance

All Implemented Interfaces:

java.io.Serializable

public class CMDBInstance
extends java.lang.Object
implements java.io.Serializable

The CMDBInstance class allows you to work with an instance of a CI or relationship class in BMC Atrium CMDB. CMDBClassNameKey, which is passed as a parameter for this class, holds the namespace and classname from which you want to create the instance. You can also pass the attribute values in an attribute map object to create the instance with the specified details. Once you create the instance, you can search for specific attributes, update the attributes, and delete the instance.

See Also:

Serialized Form

Field Summary

static int	CMDB_ATTACHMENT_LOCATION_BUFFER Specifies that the returned attachment is stored in a data buffer.
static int	CMDB_ATTACHMENT_LOCATION_FILE Specifies that the returned attachment is stored in a file.
static int	CMDB_ATTACHMENT_LOCATION_NONE Specifies that no attachment is stored.
static int	CMDB_DATASET_ACCESSIBILITY_READ_ONLY Specifies that the dataset value is read-only and cannot be accessed or modified.
static int	CMDB_DATASET_ACCESSIBILITY_WRITABLE Specifies that the dataset is writable.
static int	CMDB_DATASET_ACCESSIBLITY_WRITABLE_BY_CLIENT_TYPE Specifies that the dataset value can be accessed or modified by certain client types.
static int	CMDB_DATASET_TYPE_OVERLAY Specifies that the dataset is an overlay dataset, which overlays a regular dataset.
static int	CMDB_DATASET_TYPE_REGULAR Specifies that the dataset is a regular dataset that underlies the overlay dataset.
static int	CMDB_GET_DATASET_MODE_CURRENT Specifies that you can retrieve an instance from the current dataset only.
static int	CMDB_GET_MASK_NONE Specifies that you can retrieve an instance from the overlay dataset only.
static int	CMDB_NO_MAX_LIST_RETRIEVE Specifies that you can retrieve the maximum number of entries that match the criteria.
static int	CMDB_START_WITH_FIRST_INSTANCE Specifies that an instance is retrieved from the result set starting with the first instance.

Constructor Summary

CMDBInstance(CMDBClassNameKey aClassKey)
Creates an instance with the class name and namespace information specified in the aClassKey parameter.

CMDBInstance(CMDBClassNameKey aClassKey, java.util.Map anAttrValuesMap)
Creates an instance with the class name, namespace, and the required attributes, such as dataset ID and instance ID.

Method Summary

void	create(ARServerUser context) Creates the instance in BMC Atrium CMDB.
void	create(ARServerUser context, java.lang.String aDatasetId) Creates the instance with the specified dataset ID.
static void	delete(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String instanceId, int deleteOption) Deletes the instance from BMC Atrium CMDB.
static void	delete(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, java.lang.String instanceId, int deleteOption) Deletes the instance from the specified dataset.
static java.lang.String[]	find(ARServerUser context, CMDBClassNameKey aClassKey, QualifierInfo query, CMDBSort[] sortArray, int firstRetrieve, int maxRetrieve, java.lang.Integer numMatches) Gets a list of all the instances that match the query, beginning with the specified instance and containing no more than the specified number of entries.
static java.lang.String[]	find(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String query, CMDBSort[] sortArray, int firstRetrieve, int maxRetrieve, java.lang.Integer numMatches) Gets a list of all the instances that match the specified query, beginning with the specified instance and containing the specified number of entries.
static java.lang.String[]	find(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, QualifierInfo query, CMDBSort[] sortArray, int firstRetrieve, int maxRetrieve, java.lang.Integer numMatches) Gets a list of all the qualified instances from the specified dataset, beginning with the specified instance and containing no more than the specified number of entries.
static java.lang.String[]	find(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, java.lang.String query, CMDBSort[] sortArray, int firstRetrieve, int maxRetrieve, java.lang.Integer numMatches) Gets a list of all the instances from the specified dataset, beginning with the specified instance and containing no more than the specified number of entries.
static void	findBlobByKey(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, java.lang.String instanceId, java.lang.String attributeName, AttachmentValue attachment) Finds the specified attachment attribute from the specified dataset.
static void	findBlobByKey(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String instanceId, java.lang.String attributeName, AttachmentValue attachment) Finds the specified attachment attribute from BMC Atrium CMDB.
static CMDBInstance	findByKey(ARServerUser context, CMDBClassNameKey aClassKey, int aGetMask, java.lang.String aDatasetId, java.lang.String instanceId, java.lang.String[] attributeNames) Gets the instance from the specified dataset that matches the specified instance ID.
static CMDBInstance	findByKey(ARServerUser context, java.lang.String instanceId, CMDBClassNameKey aClassKey, java.lang.String[] attributeNames) Gets the instance that matches the specified instance ID.
static CMDBInstance[]	findObjects(ARServerUser context, CMDBClassNameKey aClassKey, QualifierInfo query, java.lang.String[] attributeGetList, CMDBSort[] sortArray, int firstRetrieve, int maxRetrieve, java.lang.Integer numMatches) Gets a list of the qualified instances from the specified dataset that have attributes that match the specified query.
static CMDBInstance[]	findObjects(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String[] instanceIds, java.lang.String[] attributeGetList) Gets a list of the instances that match the specified instance IDs.
static CMDBInstance[]	findObjects(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, QualifierInfo query, java.lang.String[] attributeGetList, CMDBSort[] sortArray, int firstRetrieve, int maxRetrieve, java.lang.Integer numMatches) Gets a list of the qualified instances from the specified dataset that have attributes that match the specified query.
static CMDBInstance[]	findObjects(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, java.lang.String[] instanceIds, java.lang.String[] attributeGetList) Gets a list of all the instances from the specified dataset that contain attributes matching the specified query.
static CMDBInstance[]	findObjects(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String aDatasetId, int aGetMask, java.lang.String query, java.lang.String[] attributeGetList, CMDBSort[] sortArray, int firstRetrieve, int maxRetrieve, java.lang.Integer numMatches) Gets a list of the instances from the specified dataset that have attributes that match the specified query.
static CMDBInstance[]	findObjects(ARServerUser context, CMDBClassNameKey aClassKey, java.lang.String query, java.lang.String[] attributeGetList, CMDBSort[] sortArray, int firstRetrieve, int maxRetrieve, java.lang.Integer numMatches) Gets a list of the instances that have attributes that match the specified query.
CMDBAttributeValue	getAttributeValueByName(java.lang.String name) Gets the attribute value using the attribute name as a map key.
java.util.Map	getAttributeValues() Gets the attribute values.
CMDBClassNameKey	getClassKey() Gets the name key of the class to which the instance belongs.
int	getGetMask() Gets the dataset mode of the instance.
java.lang.String	getId() Gets the instance ID.
void	setAttributeValues(java.util.Map newAttrValueMap) Replaces the attribute values of the instance.
void	update(ARServerUser context) Updates the instance.
void	update(ARServerUser context, java.lang.String aDatasetId) Updates the instance with the new dataset value.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CMDB_START_WITH_FIRST_INSTANCE

public static final int CMDB_START_WITH_FIRST_INSTANCE

Specifies that an instance is retrieved from the result set starting with the first instance.

See Also:

Constant Field Values

CMDB_NO_MAX_LIST_RETRIEVE

public static final int CMDB_NO_MAX_LIST_RETRIEVE

Specifies that you can retrieve the maximum number of entries that match the criteria.

See Also:

Constant Field Values

CMDB_ATTACHMENT_LOCATION_NONE

public static final int CMDB_ATTACHMENT_LOCATION_NONE

Specifies that no attachment is stored.

See Also:

Constant Field Values

CMDB_ATTACHMENT_LOCATION_FILE

public static final int CMDB_ATTACHMENT_LOCATION_FILE

Specifies that the returned attachment is stored in a file.

See Also:

Constant Field Values

CMDB_ATTACHMENT_LOCATION_BUFFER

public static final int CMDB_ATTACHMENT_LOCATION_BUFFER

Specifies that the returned attachment is stored in a data buffer.

See Also:

Constant Field Values

CMDB_GET_MASK_NONE

public static final int CMDB_GET_MASK_NONE

Specifies that you can retrieve an instance from the overlay dataset only.

See Also:

Constant Field Values

CMDB_GET_DATASET_MODE_CURRENT

public static final int CMDB_GET_DATASET_MODE_CURRENT

Specifies that you can retrieve an instance from the current dataset only.

See Also:

Constant Field Values

CMDB_DATASET_ACCESSIBILITY_WRITABLE

public static final int CMDB_DATASET_ACCESSIBILITY_WRITABLE

Specifies that the dataset is writable.

See Also:

Constant Field Values

CMDB_DATASET_ACCESSIBILITY_READ_ONLY

public static final int CMDB_DATASET_ACCESSIBILITY_READ_ONLY

Specifies that the dataset value is read-only and cannot be accessed or modified.

See Also:

Constant Field Values

CMDB_DATASET_ACCESSIBLITY_WRITABLE_BY_CLIENT_TYPE

public static final int CMDB_DATASET_ACCESSIBLITY_WRITABLE_BY_CLIENT_TYPE

Specifies that the dataset value can be accessed or modified by certain client types.

See Also:

Constant Field Values

CMDB_DATASET_TYPE_REGULAR

public static final int CMDB_DATASET_TYPE_REGULAR

Specifies that the dataset is a regular dataset that underlies the overlay dataset.

See Also:

Constant Field Values

CMDB_DATASET_TYPE_OVERLAY

public static final int CMDB_DATASET_TYPE_OVERLAY

Specifies that the dataset is an overlay dataset, which overlays a regular dataset.

See Also:

Constant Field Values

Constructor Detail

CMDBInstance

public CMDBInstance(CMDBClassNameKey aClassKey)

Creates an instance with the class name and namespace information specified in the aClassKey parameter. The CMDBClassNameKey parameter contains the class name and the namespace definitions for the instance.

Parameters:

aClassKey - the class key of the CMDB Class to which the instance is associated

CMDBInstance

public CMDBInstance(CMDBClassNameKey aClassKey,
                    java.util.Map anAttrValuesMap)

Creates an instance with the class name, namespace, and the required attributes, such as dataset ID and instance ID.

Parameters:

aClassKey - the name key of the class to which the instance is associated

anAttrValuesMap - the attribute values are organized into a map that uses the attribute name as its map key, and CMDBAttributeValue as its mapped value

Throws:

java.lang.IllegalArgumentException - if map value is not CMDBAttributeValue

Method Detail

getClassKey

public CMDBClassNameKey getClassKey()

Gets the name key of the class to which the instance belongs.

Returns:

a CMDBClass key

getId

public java.lang.String getId()

Gets the instance ID.

Returns:

the ID of the instance

getGetMask

public int getGetMask()

Gets the dataset mode of the instance. The dataset mode determines from which dataset to retrieve the instance.

Returns:

the dataset mode of the instance

getAttributeValues

public java.util.Map getAttributeValues()

Gets the attribute values. The values are organized into a map that uses the attribute name as its map key. The type of mapped values is CMDBAttributeValue.

Returns:

the attribute values that are collected into a map

getAttributeValueByName

public CMDBAttributeValue getAttributeValueByName(java.lang.String name)

Gets the attribute value using the attribute name as a map key.

Parameters:

name - the name of the attribute

Returns:

the attribute value

setAttributeValues

public void setAttributeValues(java.util.Map newAttrValueMap)

Replaces the attribute values of the instance. The new values are organized into a map that uses the attribute name as its map key. The type of mapped values is CMDBAttributeValue.

Parameters:

newAttrValueMap - the new attribute values to be set

Throws:

java.lang.IllegalArgumentException - if map value is not CMDBAttributeValue

create

public void create(ARServerUser context)
            throws ARException

Creates the instance in BMC Atrium CMDB.

Parameters:

context - ARServerUser structure that contains AR System user and host information

Throws:

ARException - if the instance cannot be created in AR System

create

public void create(ARServerUser context,
                   java.lang.String aDatasetId)
            throws ARException

Creates the instance with the specified dataset ID.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aDatasetId - the name of the dataset to which the instance is associated

Throws:

ARException - if the instance cannot be created in BMC Atrium CMDB.

delete

public static void delete(ARServerUser context,
                          CMDBClassNameKey aClassKey,
                          java.lang.String instanceId,
                          int deleteOption)
                   throws ARException

Deletes the instance from BMC Atrium CMDB. The deleteOption parameter is a constant defined in BMC Atrium CMDB.

Parameters:

context - ARServerUser structure that contains AR Server user and host information

aClassKey - the name key of the class to which the instance is associated

instanceId - the ID of the instance to be deleted

deleteOption - option for deleting the instance from BMC Atrium CMDB. Possible values are:

• 0: For a derived class, delete only if an instance is found.
• 1: Delete unconditionally.

Throws:

ARException - if the instance cannot be deleted

delete

public static void delete(ARServerUser context,
                          CMDBClassNameKey aClassKey,
                          java.lang.String aDatasetId,
                          java.lang.String instanceId,
                          int deleteOption)
                   throws ARException

Deletes the instance from the specified dataset. The deleteOption parameter is a constant defined in BMC Atrium CMDB.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the name key of the class to which the instance belongs

aDatasetId - the dataset to which the instance is associated

instanceId - the ID of the instance to be deleted

deleteOption - option for deleting the instance from BMC Atrium CMDB. Possible values are:

• 0: For a derived class, delete only if an instance is found.
• 1: Delete unconditionally.

Throws:

ARException - if the instance cannot be deleted

findBlobByKey

public static void findBlobByKey(ARServerUser context,
                                 CMDBClassNameKey aClassKey,
                                 java.lang.String instanceId,
                                 java.lang.String attributeName,
                                 AttachmentValue attachment)
                          throws ARException

Finds the specified attachment attribute from BMC Atrium CMDB. The attachment can be placed in a buffer or a file. The system returns information based on the access privileges of the user you specify for the ARServerUser parameter. User permissions are verified for the specified attribute. If the user cannot access the attribute, the system returns an error message.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the name key of the class to which the instance belongs

instanceId - the ID of the instance to look for

attributeName - name of the attribute that has the attachment

attachment - the location of the returned attachment The attachment can be stored in a file CMDB_ATTACHMENT_LOCATION_FILE or in a buffer CMDB_ATTACHMENT_LOCATION_BUFFER. If it is stored in a file, then the file name should be specified in this argument. The returned attachment object is also saved in this object.

Throws:

ARException - if the specified attachment cannot be located.

findBlobByKey

public static void findBlobByKey(ARServerUser context,
                                 CMDBClassNameKey aClassKey,
                                 java.lang.String aDatasetId,
                                 int aGetMask,
                                 java.lang.String instanceId,
                                 java.lang.String attributeName,
                                 AttachmentValue attachment)
                          throws ARException

Finds the specified attachment attribute from the specified dataset. The attachment can be placed in a buffer or a file. The system returns information based on the access privileges of the user you specify for the ARServerUser parameter. User permissions are verified for the specified attribute. If the user cannot access the attribute, the system returns an error message.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the name key of the class to which the instance belongs

aDatasetId - the name of the dataset to which the instance belongs

aGetMask - the dataset type. Based on the dataset ID being passed, instances are retrieved from the overlay or the original dataset.

instanceId - the ID of the instance to look for

attributeName - name of the attribute that has the attachment

attachment - the location of the returned attachment. The attachment can be stored in a file CMDB_ATTACHMENT_LOCATION_FILE or in a buffer CMDB_ATTACHMENT_LOCATION_BUFFER. If it is stored in a file, then the file name should be specified in this argument. The returned attachment object is also saved in this object.

Throws:

ARException - if the specified attachment can't be located.

find

public static java.lang.String[] find(ARServerUser context,
                                      CMDBClassNameKey aClassKey,
                                      java.lang.String query,
                                      CMDBSort[] sortArray,
                                      int firstRetrieve,
                                      int maxRetrieve,
                                      java.lang.Integer numMatches)
                               throws ARException

Gets a list of all the instances that match the specified query, beginning with the specified instance and containing the specified number of entries. The maxRetrieve and firstRetrieve parameters are constants defined in BMC Atrium CMDB.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the name key of the class to which the instance belongs

query - a string where you specify a qualification for retrieving instances. For example, to locate instances of class BMC:AssetBase, where Cost Center is "BMC" and Order ID is 5, the qualification will be: 'Cost Center' = "BMC" AND 'Order ID' = 5. So, the name of the attribute for which you are querying is always surrounded in single quotes. For each attribute, if the datatype is string, enclose the string you are looking for in double quotes (as in the above example, "BMC"). For integers, you do not need to put any quotes around it.

firstRetrieve - first instance retrieved for the query chunk CMDB_START_WITH_FIRST_INSTANCE means retrieve the first instance from BMC Atrium CMDB.

maxRetrieve - maximum instances to retrieve for the query. CMDB_NO_MAX_LIST_RETRIEVE means unlimited instances are retrieved.

numMatches - total number of (accessible) instances that match the qualification criteria. Specify null for this parameter if you do not want to retrieve this count.

Returns:

the IDs of all matching instances

Throws:

ARException - if failed to return all matched instances

find

public static java.lang.String[] find(ARServerUser context,
                                      CMDBClassNameKey aClassKey,
                                      java.lang.String aDatasetId,
                                      int aGetMask,
                                      java.lang.String query,
                                      CMDBSort[] sortArray,
                                      int firstRetrieve,
                                      int maxRetrieve,
                                      java.lang.Integer numMatches)
                               throws ARException

Gets a list of all the instances from the specified dataset, beginning with the specified instance and containing no more than the specified number of entries. The maxRetrieve and firstRetrieve parameters are constants defined in BMC Atrium CMDB.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the name key of the class to which the instance belongs

aDatasetId - name of the dataset to which the instance belongs

aGetMask - the dataset type. Based on the datasetId being passed, instances are retrieved from the overlay or the original dataset.

query - a string where you specify a qualification for retrieving instances. For example, to locate instances of class BMC:AssetBase, where Cost Center is "BMC" and Order ID is 5, the qualification will be: 'Cost Center' = "BMC" AND 'Order ID' = 5. So, the name of the attribute you are querying for is always surrounded in single quotes. For each attribute, if the datatype is string, enclose the string you are looking for in double quotes (as in the above example, "BMC"). For integers, you do not need to put any quotes around it.

firstRetrieve - first instance retrieved for the query chunk CMDB_START_WITH_FIRST_INSTANCE means retrieve the first instance from AR System.

maxRetrieve - maximum instances to retrieve for the query. CMDB_NO_MAX_LIST_RETRIEVE means unlimited instances are retrieved.

numMatches - total number of (accessible) instances that match the qualification. Specify NULL for this parameter if you do not want to retrieve this count.

Returns:

the IDs of all matching instances

Throws:

ARException - if failed to return all matched instances

find

public static java.lang.String[] find(ARServerUser context,
                                      CMDBClassNameKey aClassKey,
                                      QualifierInfo query,
                                      CMDBSort[] sortArray,
                                      int firstRetrieve,
                                      int maxRetrieve,
                                      java.lang.Integer numMatches)
                               throws ARException

Gets a list of all the instances that match the query, beginning with the specified instance and containing no more than the specified number of entries.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the name key of the class to which the instance belongs

query - a query object where you specify a qualification for retrieving instances

firstRetrieve - first instance retrieved for the query chunk CMDB_START_WITH_FIRST_INSTANCE means retrieve the first instance from AR System.

maxRetrieve - maximum instances to retrieve for the query. CMDB_NO_MAX_LIST_RETRIEVE means unlimited instances are retrieved.

numMatches - total number of (accessible) instances that match the qualification. Specify NULL for this parameter if you do not want to retrieve this count.

Returns:

the IDs of all matching instances

Throws:

ARException - if failed to return all matched instances

find

public static java.lang.String[] find(ARServerUser context,
                                      CMDBClassNameKey aClassKey,
                                      java.lang.String aDatasetId,
                                      int aGetMask,
                                      QualifierInfo query,
                                      CMDBSort[] sortArray,
                                      int firstRetrieve,
                                      int maxRetrieve,
                                      java.lang.Integer numMatches)
                               throws ARException

Gets a list of all the qualified instances from the specified dataset, beginning with the specified instance and containing no more than the specified number of entries.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the name key of the class to which the instance belongs

aDatasetId - name of the dataset to which the instance belongs

aGetMask - the dataset type. Based on the datasetId being passed, instances are retrieved from the overlay or the original dataset.

query - a query object where you specify a qualification for retrieving instances

firstRetrieve - first instance retrieved for the query chunk CMDB_START_WITH_FIRST_INSTANCE means retrieve the first instance from AR System.

maxRetrieve - maximum instances to retrieve for the query. CMDB_NO_MAX_LIST_RETRIEVE means unlimited instances are retrieved.

numMatches - total number of (accessible) instances that match the qualification criteria. Specify null for this parameter if you do not want to retrieve this count.

Returns:

the IDs of all matching instances

Throws:

ARException - if failed to return all matched instances

findObjects

public static CMDBInstance[] findObjects(ARServerUser context,
                                         CMDBClassNameKey aClassKey,
                                         java.lang.String query,
                                         java.lang.String[] attributeGetList,
                                         CMDBSort[] sortArray,
                                         int firstRetrieve,
                                         int maxRetrieve,
                                         java.lang.Integer numMatches)
                                  throws ARException

Gets a list of the instances that have attributes that match the specified query. Note - The specified key is applied to all returned objects without validating real namespace:classname

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the key of the class to which the instance belongs

query - a string where you specify a qualification for retrieving instances. For example, to locate instances of class BMC:AssetBase, where Cost Center is "BMC" and Order ID is 5, the qualification will be: 'Cost Center' = "BMC" AND = 'Order ID' = 5. The name of the attribute for which you are querying should be surrounded in single quotes. For each attribute, if the datatype is string, enclose the string you are looking for in double quotes (as in the above example, "BMC"). For integers, you do not need to put any quotes around it.

attributeGetList - the attribute to be retrieved. If attributeGetList is NULL, then all attribute values of the instance will be returned.

firstRetrieve - first instance retrieved for the query chunk CMDB_START_WITH_FIRST_INSTANCE means retrieve the first instance from AR System.

maxRetrieve - maximum instances to retrieve for the query. CMDB_NO_MAX_LIST_RETRIEVE means unlimited instances are retrieved.

numMatches - number of (accessible) instances that match the qualification criteria. Specify NULL for this parameter if you do not want to retrieve this count.

Returns:

all matching instances. If attributeGetList is NULL, then all attributeValue in each instance will be retrieved.

Throws:

ARException - if failed to return all matched instances

findObjects

public static CMDBInstance[] findObjects(ARServerUser context,
                                         CMDBClassNameKey aClassKey,
                                         java.lang.String aDatasetId,
                                         int aGetMask,
                                         java.lang.String query,
                                         java.lang.String[] attributeGetList,
                                         CMDBSort[] sortArray,
                                         int firstRetrieve,
                                         int maxRetrieve,
                                         java.lang.Integer numMatches)
                                  throws ARException

Gets a list of the instances from the specified dataset that have attributes that match the specified query.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the key of the class to which the instance belongs

aDatasetId - dataset ID of the instances you want to retrieve

aGetMask - the dataset type. Based on the dataset ID being passed, instances are retrieved from the overlay or the original dataset.

query - a string where you specify a qualification for retrieving instances. For example, to locate instances of class BMC:AssetBase, where Cost Center is "BMC" and Order ID is 5, the qualification will be: 'Cost Center' = "BMC" AND = 'Order ID' = 5. So, the name of the attribute you are querying for is always surrounded in single quotes. For each attribute, if the datatype is string, enclose the string you are looking for in double quotes (as in the above example, "BMC"). For integers, you do not need to put any quotes around it.

attributeGetList - the attribute to be retrieved. If attributeGetList is NULL, then all attribute values of the instance will be returned.

firstRetrieve - first instance retrieved for the query chunk CMDB_START_WITH_FIRST_INSTANCE means retrieve the first instance from AR System.

maxRetrieve - maximum instances to retrieve for the query CMDB_NO_MAX_LIST_RETRIEVE means unlimited instances are retrieved.

numMatches - Will return the total number of (accessible) instances that match the qualification criteria. Specify NULL for this parameter if you do not want to retrieve this count.

Returns:

all matching instances. If attributeGetList is NULL, then all attributeValue in each instance will be retrieved.

Throws:

ARException - if failed to return all matched instances

findObjects

public static CMDBInstance[] findObjects(ARServerUser context,
                                         CMDBClassNameKey aClassKey,
                                         QualifierInfo query,
                                         java.lang.String[] attributeGetList,
                                         CMDBSort[] sortArray,
                                         int firstRetrieve,
                                         int maxRetrieve,
                                         java.lang.Integer numMatches)
                                  throws ARException

Gets a list of the qualified instances from the specified dataset that have attributes that match the specified query.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the key of the class that the instance belongs to

query - a string where you specify a qualification for retrieving instances. For example, to locate instances of class BMC:AssetBase, where Cost Center is "BMC" and Order ID is 5, the qualification will be: 'Cost Center' = "BMC" AND 'Order ID' = 5. So, the name of the attribute you are querying for is always surrounded in single quotes. For each attribute, if the datatype is string, enclose the string you are looking for in double quotes (as in the above example, "BMC"). For integers, you do not need to put any quotes around it.

attributeGetList - the attribute to be retrieved. If attributeGetList is NULL, then all attribute values of the instance will be returned.

firstRetrieve - first instance retrieved for the query chunk CMDB_START_WITH_FIRST_INSTANCE means retrieve the first instance from AR System.

maxRetrieve - maximum instances to retrieve for the query CMDB_NO_MAX_LIST_RETRIEVE means unlimited instances are retrieved.

numMatches - the total number of (accessible) instances that match the qualification criteria. Specify NULL for this parameter if you do not want to retrieve this count.

Returns:

all matching instances. If attributeGetList is NULL, then all attributeValue in each instance will be retrieved.

Throws:

ARException - if failed to return all matched instances

findObjects

public static CMDBInstance[] findObjects(ARServerUser context,
                                         CMDBClassNameKey aClassKey,
                                         java.lang.String aDatasetId,
                                         int aGetMask,
                                         QualifierInfo query,
                                         java.lang.String[] attributeGetList,
                                         CMDBSort[] sortArray,
                                         int firstRetrieve,
                                         int maxRetrieve,
                                         java.lang.Integer numMatches)
                                  throws ARException

Gets a list of the qualified instances from the specified dataset that have attributes that match the specified query.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the key of the class to which the instance belongs

aDatasetId - dataset ID of the instances you want to retrieve

aGetMask - dataset type. Based on the dataset ID being passed, instances are retrieved from the overlay or the original dataset.

query - a query object where you specify a qualification for retrieving instances

attributeGetList - the attribute to be retrieved. If attributeGetList is NULL, then all attribute values of the instance will be returned.

firstRetrieve - first instance retrieved for the query chunk CMDB_START_WITH_FIRST_INSTANCE means retrieve the first instance from AR System.

maxRetrieve - maximum instances to retrieve for the query CMDB_NO_MAX_LIST_RETRIEVE means unlimited instances are retrieved.

numMatches - total number of (accessible) instances that match the qualification criteria. Specify NULL for this parameter if you do not want to retrieve this count.

Returns:

all matching instances. If attributeGetList is NULL, then all attributeValue in each instance will be retrieved.

Throws:

ARException - if failed to return all matched instances

findObjects

public static CMDBInstance[] findObjects(ARServerUser context,
                                         CMDBClassNameKey aClassKey,
                                         java.lang.String[] instanceIds,
                                         java.lang.String[] attributeGetList)
                                  throws ARException

Gets a list of the instances that match the specified instance IDs.

Parameters:

context - ARServerUser structure that contains user and host information

aClassKey - the key of the class to which the instance belongs

instanceIds - an array of instance IDs

attributeGetList - the attribute to be retrieved. If attributeGetList is NULL, then all attribute values of the instance will be returned.

Returns:

all specified instances. If attributeGetList is NULL, then all attributeValue in each instance will be retrieved.

Throws:

ARException - if failed to return all matched instances

findObjects

public static CMDBInstance[] findObjects(ARServerUser context,
                                         CMDBClassNameKey aClassKey,
                                         java.lang.String aDatasetId,
                                         int aGetMask,
                                         java.lang.String[] instanceIds,
                                         java.lang.String[] attributeGetList)
                                  throws ARException

Gets a list of all the instances from the specified dataset that contain attributes matching the specified query.

Parameters:

context - ARServerUser structure that contains user and host information

aClassKey - the key of the class to which the instance belongs

aDatasetId - name of the dataset to which the instance belongs

aGetMask - the dataset type. Based on the dataset ID being passed, instances are retrieved from the overlay or the original dataset.

instanceIds - an array of instance IDs

attributeGetList - the attribute to be retrieved. If attributeGetList is NULL, then all attribute values of the instance will be returned.

Returns:

all specified instances. If attributeGetList is NULL, then all attributeValue in each instance will be retrieved.

Throws:

ARException - if failed to return all matched instances

findByKey

public static CMDBInstance findByKey(ARServerUser context,
                                     java.lang.String instanceId,
                                     CMDBClassNameKey aClassKey,
                                     java.lang.String[] attributeNames)
                              throws ARException

Gets the instance that matches the specified instance ID.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the key of the class to which the instance belongs

instanceId - the ID of the instance to look for

attributeNames - the list of attributes to retrieve

Returns:

the CMDBinstance instance with the specified attribute value. If attributeNames is NULL, then all attributeValue in the instance will be retrieved.

Throws:

ARException - if the specified instance can't be located

findByKey

public static CMDBInstance findByKey(ARServerUser context,
                                     CMDBClassNameKey aClassKey,
                                     int aGetMask,
                                     java.lang.String aDatasetId,
                                     java.lang.String instanceId,
                                     java.lang.String[] attributeNames)
                              throws ARException

Gets the instance from the specified dataset that matches the specified instance ID.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aClassKey - the key of the class to which the instance belongs

instanceId - the ID of the instance to look for

aDatasetId - the name of the dataset to which the instance belongs

aGetMask - the dataset type. Based on the dataset ID being passed, instances are retrieved from the overlay or the original dataset.

attributeNames - the list of attributes to retrieve.

Returns:

the CMDBinstance instance with the specified attribute value. If attributeNames is NULL, then all attributeValue in the instance will be retrieved.

Throws:

ARException - if the specified instance can't be located

update

public void update(ARServerUser context)
            throws ARException

Updates the instance.

Parameters:

context - ARServerUser structure that contains AR System user and host information

Throws:

ARException - if the instance cannot be updated in AR System

update

public void update(ARServerUser context,
                   java.lang.String aDatasetId)
            throws ARException

Updates the instance with the new dataset value.

Parameters:

context - ARServerUser structure that contains AR System user and host information

aDatasetId - the name of the dataset to which the instance belongs

Throws:

ARException - if the instance cannot be updated in AR System