Search Capability

Waveset supports the Search capabilities described in the following table.

Search Filter Configuration

The DSML search filter is translated to a set of repository attribute conditions. A necessary part of the translation involves mapping the external DSML attribute name to a queryable repository attribute. A set of attribute mappings for each searchable type must be defined in the configuration.

The filter is analyzed and processed according to one of the following categories:

• Fully-indexed. The filter is converted to equivalent attribute conditions that find exactly the required objects from the repository. In this case, there is no need to further filter the resulting objects. A fully indexed search is much faster than a partially indexed or unindexed search because it does not instantiate views of the queried objects.

• Partially-indexed. At least one attribute condition is derived from the filter that finds a superset of the required objects from the repository. For each object, the system instantiates a view of the object that contains, at minimum, those attributes specified in the filter. It also checks whether the object matches the filter.

• Unindexed. No attribute conditions can be derived from the filter to apply against the repository. This type is similar to a partially-indexed search, except that all objects in the repository of the requested type are processed.

• Unsupported. The filter cannot be evaluated. The search operation is rejected.

The SPML2 configuration object contains the following properties

• SearchIndexRequired. Specifies whether partially-indexed or unindexed searches are accepted. An example of a search that is not fully-indexed is one whose filter specifies a non-queryable attribute. The possible values are as follows:

  • full. Indicates that only fully indexed search operations are accepted. This is the default value.

  • partial. Indicates that partial or fully indexed search operations are accepted.

  • none. Indicates that unindexed search operations are accepted, in addition to partial and fully indexed operations.

• SearchSizeLimit. An integer value specifying the maximum total number of objects that can be returned from a search request. If the search creates an iterator, all subsequent iterator responses are counted toward the total. A value of 0 indicates there is no limit.

  When the limit is exceeded, results are returned up to the limit, and an informational message is returned to the client indicating that the limit was exceeded.

• SearchTimeLimit. An integer value specifying the maximum time, in seconds, that an individual SPMLv2 search request or iterator request is allowed to take before a response is returned. A value of 0 means there is no limit.

• queryMappings. A map of existing SPML attribute names and Waveset repository attribute names.

• IteratorTimeout. An integer value specifying the maximum time, in seconds, that an SPMLv2 iterator remains valid after it was last provided in a response. A value must be specified.

The following capabilities are not supported:

• org.openspml.v2.profiles.dsml.ApproxMatch

• org.openspml.v2.profiles.dsml.ExtensibleMatch

Search Examples

The following examples illustrate how to perform searches.

Example 2–17 SearchRequest Example

ArrayList<PSO> psos = new ArrayList<PSO>();

SessionAwareSpml2Client client = new SessionAwareSpml2Client("http://example.com:8080
/idm/servlet/openspml2");
ListTargetsResponse loginInfo = client.login("Configurator", "configurator");

SearchRequest searchReq = new SearchRequest();
EqualityMatch acctIdTerm = new EqualityMatch("firstname", new DSMLValue("Marcus"));
Present emailTerm = new Present("emailAddress");
org.openspml.v2.profiles.dsml.And terms = new 
    org.openspml.v2.profiles.dsml.And(new FilterItem[] { acctIdTerm, emailTerm });
Filter filter = new Filter(terms);
Query q = new Query();
q.setScope(Scope.ONELEVEL);
q.addQueryClause(filter);

searchReq.setQuery(q);
searchReq.setReturnData(ReturnData.IDENTIFIER);
searchReq.setExecutionMode(ExecutionMode.SYNCHRONOUS);

SearchResponse searchRes = (SearchResponse) client.request(searchReq);
if (searchRes.getStatus().equals(StatusCode.SUCCESS)) {
    System.out.println("Received search response.");
    for (PSO pso : searchRes.getPSOs()) {
        psos.add(pso);
    }
    
    ResultsIterator iterator = searchRes.getIterator();

    while (iterator != null) {
        IterateRequest iterReq = new IterateRequest();
        iterReq.setIterator(iterator);
        iterReq.setExecutionMode(ExecutionMode.SYNCHRONOUS);
        IterateResponse iterRes = (IterateResponse) client.request(iterReq);
        if (iterRes.getStatus().equals(StatusCode.SUCCESS)) {
            System.out.println("Found an iterator.");
        }
        for (PSO pso : iterRes.getPSOs()) {
            psos.add(pso);
        }
        iterator = iterRes.getIterator();
    }
}

Example 2–18 CloseIterator Example

// Close iterator example
ArrayList<PSO> psos = new ArrayList<PSO>();

SessionAwareSpml2Client client = new 
SessionAwareSpml2Client("http://example.com:8080/idm/servlet/openspml2");
ListTargetsResponse loginInfo = client.login("Configurator", "configurator");

SearchRequest searchReq = new SearchRequest();

Present term = new Present("emailAddress");
Filter filter = new Filter(term);
Query q = new Query();
q.setScope(Scope.ONELEVEL);
q.addQueryClause(filter);

searchReq.setQuery(q);
searchReq.setReturnData(ReturnData.EVERYTHING);
searchReq.setExecutionMode(ExecutionMode.SYNCHRONOUS);

SearchResponse searchRes = (SearchResponse) client.request(searchReq);
if (searchRes.getStatus().equals(StatusCode.SUCCESS)) {
    System.out.println("Received search response.");
    for (PSO pso : searchRes.getPSOs()) {
        psos.add(pso);
    }
    
    ResultsIterator iterator = searchRes.getIterator();

    while (iterator != null) {
        IterateRequest iterReq = new IterateRequest();
        iterReq.setIterator(iterator);
        iterReq.setExecutionMode(ExecutionMode.SYNCHRONOUS);
        IterateResponse iterRes = (IterateResponse) client.request(iterReq);
        if (iterRes.getStatus().equals(StatusCode.SUCCESS)) {
            System.out.println("Found an iterator.");
        }
        for (PSO pso : iterRes.getPSOs()) {
            psos.add(pso);
        }
        iterator = iterRes.getIterator();
        
        // For this example, always close the iterator
        if (true) {
            CloseIteratorRequest closeIterReq = new CloseIteratorRequest();
            closeIterReq.setIterator(iterator);
            closeIterReq.setExecutionMode(ExecutionMode.SYNCHRONOUS);
            CloseIteratorResponse closeIterRes = (CloseIteratorResponse) 
                client.request(closeIterReq);
            if (closeIterRes.getStatus().equals(StatusCode.SUCCESS)) {
                System.out.println("Closed iterator.");
                break;
            }
        }
    }
}