Searches
Contents
sm1252sp1
Contents
You can search LDAP directories and ODBC directories. You search an organization using one of the search... methods in the class SmDmsOrganization.
You define a search using the following objects:
- SmDmsSearch to set search parameters such as the search starting point, the maximum number of records to retrieve, and the search filter. The following sections describe the use of this object.
- SmDmsCursor to define optional sorting and paging preferences.
You can specify the search parameters to use when searching the directory. There are two times when you can specify search parameters:
- When you create the search object
- After you create the search object
You can use either option or both options. They are not mutually exclusive.
Set Search Parameters When Creating the Search Object
To specify a search parameter when you create a search object, pass one or more search parameter names to the constructor of the SmDmsSearch class.
There are some search parameters that you cannot specify during creation of the search object—for example, scope. The constructor for the SmDmsSearch class accepts only the following search parameters:
- filter
- root
- propertyNames
- maxItems
You can create an SmDmsSearch object without passing any search parameters to the constructor.
Set Search Parameters After Creating the Search Object
After a search object is created, you can use the set... methods in the SmDmsSearch class to:
- Set additional search parameters.
- Reset search parameters that you set when the search object was created.
By using the set... methods, you can set or reset any of the parameters shown in the following table:
Parameter | Default | Set Method | Definition |
classId | Unknown (not set yet) | setClassId() | Class identifier. |
filter | " " | setFilter() | Search filter, or the string you want to find. Can also be set when the search object is created. |
maxItems | 50 | setMaxItems() | Maximum number of result set items to display at a time. Can also be set when the search object is created. |
nMaxResults | -1 | setMaxResults() | Maximum number of items for the result set. For example, if nMaxResults is 500, but 750 items match the search criteria, only the first 500 matches will be returned from the search. |
nextItem | -1 | setNextItem() | The item to start with on the next search forward—for example: nextItem += maxItems |
previousItem | -1 | setPreviousItem() | The item to start with on the next search backward—for example: previousItem-=maxItems |
propertyNames | null | setPropertyNames() | Properties to return from the search. Can also be set when the search object is created. |
root | " " | setRoot() | Directory entry where the search should start. Can also be set when the search object is created. Valid for LDAP searches only. |
scope | None | setScope() | Levels searched. For LDAP searches only. |
timeout | -1 | setTimeout() | Maximum duration of the search, in seconds. |
Set the Search Filter
The search filter defines the items you want to retrieve in the search. You can set the search filter through an SmDmsSearch constructor or through the SmDmsSearch method setFilter().
The search filter is described differently for LDAP directories and ODBC directories.
Set the Search Filter for LDAP Directories
With LDAP directories, you provide a complete LDAP search filter in the
filter
parameter of an SmDmsSearch constructor or setFilter() method. For example, if you pass filter
and root
to the SmDmsSearch constructor to search the organization swdev.com for groups, you could specify the following:SmDmsSearch search = new SmDmsSearch ("(&(objectclass=organizationalUnit) (ou=groups))","o=swdev.com");
Set the Search Filter for ODBC Directories
A search of an ODBC directory is performed through a SQL query. The DMS API supports the SQL SELECT statement.
The information you provide in the search filter depends on whether your search uses an SmDmsCursor object to provide sorting and paging operations:
- With ODBC searches that do not pass an SmDmsCursor object to the search method, use a fully defined SQL SELECT statement in the search filter.
- With ODBC searches that do pass an SmDmsCursor object to the search method, use a partial SQL SELECT statement in the search filter, consisting only of FROM and WHERE clauses.
With ODBC database searches that pass an SmDmsCursor object to the search method, the DMS API constructs the complete SQL SELECT statement from various sources, as follows:
- The FROM and WHERE clauses are taken from thefilterparameter of an SmDmsSearch constructor or setFilter() method.
- The SELECTcolumnsportion of the query is taken from attributes specified in either of the following parameters:
- ThepropertyNamesparameter of setPropertyNames(). These attributes are used when an SmDmsSearch object is passed to one of the search methods in SmDmsOrganization.
- TheattrNamesparameter of a getGroups() or getMembers() method.
- The ORDER BYkeywordsportion is taken from the orderof the attributes you specify in thesortparameter of the SmDmsCursor constructor.
Consider the following code fragment:
String DIR_ROOT = "root";String SRCH_FILTER ="from SmGroup";SmDmsSearch search = new SmDmsSearch(SRCH_FILTER);String[] prop = {"Name", "'Group' as Class"};search.setPropertyNames(prop);Vector SortOrder = new Vector();SortOrder.add("uid");SmDmsCursor cursor = new SmDmsCursor(SortOrder,blockSize,false,true);
The DMS API uses the information in the previous example to build the following SQL statement:
SELECT Name, 'Group' AS Class FROM SmGroup ORDER BY uid ASC
Code Source | Portion of SQL Statement |
SRCH_FILTER parameter of SmDmsSearch constructor | from SmGroup |
SortOrder parameter of SmDmsCursor constructor | order by uid asc |
prop parameter of setPropertyNames() | select Name, 'Group' as Class |
Search an Organization
In the DMS API, searches are performed on an organization object.
To search an organization:
- Create a search object. This search object holds the search parameters.For example, the following SmDmsSearch constructor call creates a search object to search for groups. Therootparameter specifies a start point of o=swdev.org.SmDmsSearch mySearch = new SmDmsSearch ("(&(objectclass=organizationalUnit) (ou=groups))","o=swdev.org");The root is the top level of theCA Single Sign-Onuser directory to search. It is not necessarily the top level of the entire directory structure.Use the set... methods in the SmDmsSearch class to set any other search parameters—for example:mySearch.setScope(2);
- Optionally, define sorting and paging preferences in the SmDmsCursor object.
- Call the search() method in class SmDmsOrganization on the organization you want to search—for example:result = targetOrg.search (mySearch, 1);The second parameter of the search() method indicates the direction to search, as shown in the following table:
Direction | Integer Value |
Reset | 0 |
Forward | 1 |
Back | 2 |
Refresh | 3 |
- To get the items returned from the search, call getResults() on the search object—for example:Vector mySearchResults = search.getResults();The first element of the results vector contains the search parameters in a SmDmsSearchResultParams object. The remaining elements are SmDmsObject objects. To distinguish object types, theclassIdattribute of each object is set through the setClassId() method. For example, if theclassIdis DMSOBJECT_CLASS_USER, the object is a user. If the classId is DMSOBJECT_CLASS_GROUP, the object is a group.
Examples of a Search
The following example searches an organization using the search parameters set through the search.set... methods below. The results of the forward search are assigned to the vector
vsearch
and are printed along with the search parameters.SmDmsContext dmsContext = new SmDmsContext();SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();SmApiResult result = new SmApiResult();SmDmsOrganization org = dmsDir.newOrganization (DIR_ROOT);// SearchSmDmsOrganization test = org.newOrganization("");SmDmsSearch search = new SmDmsSearch ("(&(objectclass=organizationalUnit) (ou=groups))", "o=swdev.com");// Define search parameterssearch.setScope(2);// Number of levels to search.search.setNextItem(0);// Initialize forward search startsearch.setMaxItems(20);// Max number of items to displaysearch.setPreviousItem(0);// Initialize back search startsearch.setMaxResults(500);// Max items in the result setresult = test.search(search, 1);Vector vsearch = search.getResults();System.out.println("Search object vector size " + vsearch.size());SmDmsSearchResultParams searchParams = (SmDmsSearchResultParams)vsearch.firstElement();System.out.println("***Search Parameters***");System.out.println(searchParams.toString());System.out.println("removed element at 0");vsearch.removeElementAt(0);System.out.println("Search object vector size " + vsearch.size());for (int i=0; i<vsearch.size(); i++){SmDmsObject dmsObj = (SmDmsObject)vsearch.elementAt(i);System.out.println("***Search**** " + dmsObj);printObject (dmsObj, result);}Hashtable attrs = dmsObj.getAttributes();Enumeration keys = attrs.keys();Enumeration values = attrs.elements();while(values.hasMoreElements() )
The following code fragment configures sorting and paging features through anSmDmsCursor object and performs a search. The parameters for the SmDmsSearch object search would be defined in the same way as in the previous example:
Vector SortOrder = new Vector();SortOrder.add("uid");int blockSize = 20;SmDmsCursor cursor=new SmDmsCursor(SortOrder,blockSize,false,true);cursor.setOffset(15);result = org.search(search, cursor, 1);//Forward searchSystem.out.println(keys.nextElement() + " = " +values.nextElement() );