Programming Guides › Programming Guide for Java › Delegated Management Services API › Searches

Searches

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:

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 the filter parameter of an SmDmsSearch constructor or setFilter() method.
• The SELECT columns portion of the query is taken from attributes specified in either of the following parameters:
  • The propertyNames parameter of setPropertyNames(). These attributes are used when an SmDmsSearch object is passed to one of the search methods in SmDmsOrganization.
  • The attrNames parameter of a getGroups() or getMembers() method.
• The ORDER BY keywords portion is taken from the order of the attributes you specify in the sort parameter 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

Search an Organization

In the DMS API, searches are performed on an organization object.

To search an organization:

1. 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. The root parameter specifies a start point of o=swdev.org.

   SmDmsSearch mySearch = new SmDmsSearch (
              "(&(objectclass=organizationalUnit) (ou=groups))",
               "o=swdev.org");
   

   Note: The root is the top level of the SiteMinder user 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);
   

2. Optionally, define sorting and paging preferences in the SmDmsCursor object.
3. 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:
   

1. 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, the classId attribute of each object is set through the setClassId() method. For example, if the classId is 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);

// Search
SmDmsOrganization test = org.newOrganization("");
SmDmsSearch search = new SmDmsSearch (
              "(&(objectclass=organizationalUnit) (ou=groups))",
               "o=swdev.com");
// Define search parameters
search.setScope(2);           // Number of levels to search.
search.setNextItem(0);        // Initialize forward search start
search.setMaxItems(20);       // Max number of items to display
search.setPreviousItem(0);    // Initialize back search start
search.setMaxResults(500);    // Max items in the result set
result = 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 an SmDmsCursor 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 search
System.out.println(keys.nextElement() + " = " +
                                          values.nextElement() );