Some Web Services methods return lists, represented by a unique integer handle. A list is simply a collection of same-type objects. Lists are especially useful when dealing with a large collection of objects (for example, all the contacts in the system) because you can retrieve information about items in a range of the list. The disadvantage is that you must make more method calls to obtain a list handle, retrieve information, and finally, free the list handle. If the expected number of list rows is small, use methods that do not involve list handles, such as doSelect().
The following describes more details about lists:
List may only contain objects of a single type, for example, lists of contacts, list of organizations, and so on.
For example, if a list object is obtained for all contacts and another contact is added to the system, the update is not reflected in the list. Another list handle must be obtained to get the most current data.
A request for a list returns an integer handle representing the list of same-type objects. No other information is sent to the client. The client may query the list for specific information about its rows. When a client is finished with a list, the handle must be released with freeListHandles(). The CA SDM server maintains the list, consuming system resources. Therefore, it is important to free lists. Unlike object handles, list handles are not persistent across sessions.
Several methods require an integer index into a list. Lists are zero-based so the first element is at index = 0.
As previously mentioned, using list handles is most useful for larger sets of data that may be queried multiple times. For some operations, however, lists are excessive. Several methods are provided, but the most notable is doSelect(), as it returns requested information about a set of data without the overhead of list handles.
The decision to use list handles versus methods, such as doSelect(), is one of performance and convenience. For example, suppose your application does processing on all 15,000 Contacts in your system. The doSelect() method can retrieve all the contact data in one call, but the reply will be delayed and will negatively impact overall system performance while it assembles and returns a very large data set. The doQuery() method, in this case, will return a list reference very quickly. Ranges of data can be queried from the list to improve response times from the server. A good practice to follow is to use list references if the data set exceeds 250 items.
Sometimes it does not make sense to use list handles. For example, an issue has a list of Activity Logs. Depending on the installation, the number of logs can range from a few to several dozen. It is probably faster to request the data all at once instead of requesting a list reference, querying it for data, and then releasing the list.
Examples of methods that return data sets instead of list references include the following:
As previously stated, queries that return a large number of rows can severely impact the performance of the server. To protect against this, CA SDM limits the number of rows returned to 250. This affects all CA SDM Web Services methods that return lists of objects, including the following:
This limit applies even if you request one of these methods to retrieve more than 250 rows.
To retrieve large numbers of rows, you should obtain a handle to the list of results and use getListValues() to retrieve chunks of 250 or fewer rows each. This strategy helps keep the server from becoming slow while serving huge amounts of data.
|
Copyright © 2013 CA.
All rights reserved.
|
|