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 * "(uid=smith)", { "telephone" }, null); 049 * if (searchResults.hasMoreElements() == true) { 050 * PersistentObject userSmith = searchResults.next(); 051 * userSmith.modify("telephone", "408-888-8888"); 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 < 10; pageIndex ++) { 066 * searchControl.setVLVRange(startPos, 0, pageSize); 067 * searchControl.setSortAttributeNames( { "cn" } ); 068 * SearchResults searchResults = 069 * organization.search("(department=sun)", 070 * { "cn", "sn", "uid" }, 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}
Copyright © 2010-2017, ForgeRock All Rights Reserved.