001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: ISearch.java,v 1.6 2009/01/28 05:34:50 ww203982 Exp $
026 *
027 */
028
029package com.iplanet.ums;
030
031/**
032 * Represents interface for search methods. Using ISearch, client can get
033 * children, parent for the PersistentObject. It's main purpose is to find nodes
034 * matching to the search criterial. Customized search behavior is set through
035 * SearchControl. Results are captured in SearchResults. Each result is a
036 * PersistentObject. Filter String is defined based on LDAP search filter syntax
037 * (ftp://ftp.isi.edu/in-notes/rfc2254.txt)
038 * 
039 * <p>
040 * Examples:
041 * <p>
042 * To modify a user's telphone number
043 * <p>
044 * 
045 * <pre>
046 *       SearchResults searchResults = 
047 *              organization.search(
048 *                    &quot;(uid=smith)&quot;, { &quot;telephone&quot; }, null);
049 *       if (searchResults.hasMoreElements() == true) {
050 *                  PersistentObject userSmith = searchResults.next();
051 *           userSmith.modify(&quot;telephone&quot;, &quot;408-888-8888&quot;);
052 *           userSmith.save();
053 *             }
054 * </pre>
055 * 
056 * <p>
057 * To read data using VLV
058 * <p>
059 * 
060 * <pre>
061 *       SearchControl searchControl = new SearchControl();
062 * 
063 *       pageSize = 20;
064 *       startPos = 1;
065 *       for (pageIndex = 0; pageIndex &lt; 10; pageIndex ++) {
066 *           searchControl.setVLVRange(startPos,  0, pageSize);
067 *           searchControl.setSortAttributeNames( { &quot;cn&quot; } );
068 *               SearchResults searchResults = 
069 *                 organization.search(&quot;(department=sun)&quot;,
070 *                        { &quot;cn&quot;, &quot;sn&quot;, &quot;uid&quot; }, 
071 *                              searchControl);
072 *           while (searchResults.hasMoreElements() == true) {
073 *                      PersistentObject user = searchResults.next();
074 *               display(user);
075 *                 }
076 *           startPos = startPos + pageSize + 1;
077 *       }
078 * </pre>
079 * 
080 * @see com.iplanet.ums.SearchControl
081 * 
082 * @supported.all.api
083 */
084public interface ISearch {
085
086    /**
087     * Find all IDs for immediate children under current node based on search
088     * criteria specified in filter. Search behavior is controlled by
089     * searchControl.
090     * 
091     * @param filter
092     *            search filter
093     * @param searchControl
094     *            search control, use default setting if searchControl == null
095     * @exception InvalidSearchFilterException
096     *                if invalid search filter.
097     * @exception UMSException
098     *                if no result matches.
099     */
100    public SearchResults getChildren(String filter, SearchControl searchControl)
101            throws InvalidSearchFilterException, UMSException;
102
103    /**
104     * Search entries on immediate children based on criteria specified in
105     * filter. Each result contains values for given attribute names. Search
106     * behavior is controlled by searchControl.
107     * 
108     * @param filter
109     *            search filter
110     * @param resultAttributeNames
111     *            attribute name array
112     * @param searchControl
113     *            search control, use default setting if searchControl == null
114     * @exception InvalidSearchFilterException
115     *                if invalid search filter.
116     * @exception UMSException
117     *                if no result matches.
118     */
119    public SearchResults getChildren(String filter,
120            String[] resultAttributeNames, SearchControl searchControl)
121            throws InvalidSearchFilterException, UMSException;
122
123    /**
124     * Find all IDs for immediate children under current node based on search
125     * criteria specified in template, and return attributes specified there.
126     * Search behavior is controlled by searchControl.
127     * 
128     * @param template
129     *            search template
130     * @param searchControl
131     *            search control, use default setting if searchControl == null
132     */
133    public SearchResults getChildren(SearchTemplate template,
134            SearchControl searchControl) throws UMSException;
135
136    /**
137     * Search (subtree) entry IDs under currrent node based on criteria
138     * specified in search filter and searchControl
139     * 
140     * @param filter
141     *            search filter
142     * @param searchControl
143     *            search control, use default setting if searchControl == null
144     * @exception com.iplanet.ums.UMSException
145     * @return An search result class for reading IDs.
146     * @exception InvalidSearchFilterException
147     *                if search filter is invalid.
148     * @exception UMSException
149     *                if no result matches.
150     */
151    public SearchResults search(String filter, SearchControl searchControl)
152            throws InvalidSearchFilterException, UMSException;
153
154    /**
155     * Search (subtree) entries under current node based on criteria specified
156     * in filter. Search behavior is controlled by searchControl. Each result
157     * contains values for given attribute names.
158     * 
159     * @param filter Search filter.
160     * @param resultAttributeNames Attribute name array for retrieving.
161     * @param searchControl Search control, use default setting if
162     *        searchControl is <code>null</code>.
163     * @return An search result class for reading entries.
164     * @exception InvalidSearchFilterException
165     * @exception UMSException
166     */
167    public SearchResults search(
168        String filter,
169        String resultAttributeNames[],
170        SearchControl searchControl
171    ) throws InvalidSearchFilterException, UMSException;
172
173    /**
174     * Search (subtree) entries under current node based on criteria specified
175     * in template, which also indicates which attributes to return. Search
176     * behavior is controlled by searchControl.
177     * 
178     * @param template
179     *            search template
180     * @param searchControl
181     *            search control, use default setting if searchControl == null
182     * @exception com.iplanet.ums.UMSException
183     */
184    public SearchResults search(SearchTemplate template,
185            SearchControl searchControl) throws UMSException;
186
187    /**
188     * Search for immediate parent ID
189     * 
190     * @param searchControl
191     *            search control, use default setting if searchControl == null
192     * @return null if current node is root public String
193     *         getParentID(SearchControl searchControl);
194     */
195
196    /**
197     * Search for immediate parent ID
198     * 
199     * @return null if current node is root
200     */
201    public Guid getParentGuid();
202}