idnits 2.17.1 draft-ietf-asid-ldap-java-controls-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-24) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 12 longer pages, the longest (page 2) being 63 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 13 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 9 instances of too long lines in the document, the longest one being 4 characters in excess of 72. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 257 has weird spacing: '...rray of contr...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 26, 1997) is 9707 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '5' on line 332 looks like a reference -- Missing reference section? '6' on line 336 looks like a reference -- Missing reference section? '2' on line 476 looks like a reference -- Missing reference section? '1' on line 481 looks like a reference -- Missing reference section? '3' on line 380 looks like a reference -- Missing reference section? '4' on line 329 looks like a reference -- Missing reference section? '0' on line 503 looks like a reference -- Missing reference section? '7' on line 530 looks like a reference Summary: 8 errors (**), 0 flaws (~~), 6 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Rob Weltman 3 INTERNET-DRAFT Netscape Communications Corp. 4 September 26, 1997 6 Java LDAP Controls 7 draft-ietf-asid-ldap-java-controls-00.txt 9 Status of this Memo 11 This document is an Internet-Draft. Internet-Drafts are working docu- 12 ments of the Internet Engineering Task Force (IETF), its areas, and its 13 working groups. Note that other groups may also distribute working 14 documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet-Drafts as reference material 19 or to cite them other than as ``work in progress.'' 21 To learn the current status of any Internet-Draft, please check the 22 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 23 Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), 24 ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). 26 Abstract 28 This document defines support for the Preferred Language Control, the 29 Server Sorting Control, and the Virtual List Control in the java LDAP 30 API. Controls are an LDAP protocol version 3 extension, to allow pass- 31 ing arbitrary control information along with a standard request to a 32 server, and to receive arbitrary information back with a standard 33 result. 35 1. Introduction 37 Version 3 of the LDAP protocol provides a means of supplying arbitrary 38 additional information along with a request to an LDAP server, and 39 receiving arbitrary additional response information. A few applications 40 of the Control mechanism have been identified as having general 41 interest, and the protocol defined for their transmission [5] and [6]. 42 This document defines how support for the Preferred Language Control, 43 the Server Sorting Control, and the Virtual List Control are supported 44 in the java LDAP API. The java LDAP API in general is described in [2]. 45 The Control protocol extension is described in [1], section 4.1.12, and 46 applications of it in [5] and [6]. 48 JAVA LDAP CONTROLS September 1997 50 2. Overview of the LDAP Control classes 52 LDAPControl is part of a basic LDAP class package. Specific 53 applications/implementations of Controls are in a subpackage called 54 "controls". 56 The base class LDAPControl is defined in [2] as: 58 public class LDAPControl implements Cloneable 60 An LDAPControl encapsulates optional additional parameters or con- 61 straints to be applied to LDAP operations. If set as a Server Con- 62 trol, it is sent to the server along with operation requests. If set 63 as a Client Control, it is not sent to the server, but rather inter- 64 preted locally by the client. LDAPControl is an LDAPv3 extension, and 65 is not supported in an LDAPv2 environment. 67 Constructors 69 public LDAPControl(String id, 70 boolean critical, 71 byte vals[]) 73 Parameters are: 75 id The type of the Control, as a string. 77 critical True if the LDAP operation should be discarded if 78 the server does not support this Control. 80 vals Control-specific data. 82 getID 84 public String getID() 86 Returns the identifier of the control. 88 isCritical 90 public boolean isCritical() 92 Returns true if the control must be supported for an associated 93 operation to be executed. 95 getValue 97 public byte[] getValue() 99 JAVA LDAP CONTROLS September 1997 101 Returns the control-specific data of the object. 103 The following Controls are defined for the controls subpackage: 105 LDAPLanguageControl Is used to set a preferred language for results 106 from the server. 108 LDAPVirtualListControlEncapsulates requests for a subset of a virtual 109 list of search results, and the response of a 110 server to such a request. 112 LDAPSortControl Encapsulates a requested sorting order for search 113 results returned by a server, and the server's 114 response to the request. 116 3. The java LDAP Control classes 118 3.1. public class LDAPLanguageControl extends LDAPControl 120 The LDAPLanguageControl class represents control data for setting a pre- 121 ferred language for results returned by a Directory Server. 123 3.1.1. Constructors 125 public LDAPLanguageControl(String lang) 127 Constructs a new LDAPLanguageControl object using a a string specifi- 128 cation of language and optionally also country and a variant. 130 public LDAPLanguageControl(Locale locale) 132 Constructs a new LDAPLanguageControl object using a Locale object to 133 select language. 135 Parameters are: 137 lang A string of the form "en" or "ja-JP-kanji". The syn- 138 tax is defined in [3] and [4]. The first two charac- 139 ters are a language specification (as defined in ISO 141 JAVA LDAP CONTROLS September 1997 143 639); they may be followed by a dash and a two char- 144 acter country specification (as defined in ISO 3166); 145 the latter may be followed by a dash and a language 146 variant. Examples: 147 "lang-en" 148 "lang-en-us" 149 "lang-ja-JP-kanji" 151 locale A Locale object to be used to define the preferred 152 language. A control for the default locale language 153 may be created with 154 LDAPLanguageControl lc = new LDAPLanguageControl( 155 Locale.getDefault() ); 157 3.1.2. public class LDAPVirtualListControl extends LDAPControl 159 LDAPVirtualListControl is a Server Control to specify that results from 160 a search are to be returned in pages, subsets of the entire virtual 161 result set. On success, an updated LDAPVirtualList object is returned as 162 a response Control, containing information on the virtual list size and 163 the actual first index. This object can then be updated by the client 164 with a new requested position or length and sent to the server to obtain 165 a different segment of the virtual list. 167 3.1.2.1. Constructors 169 public LDAPVirtualListControl( String subFilter, 170 int beforeCount, 171 int afterCount ) 173 Constructs a virtual list control using the specified filter expres- 174 sion, which defines the extent of the virtual search results, and the 175 number of entries before and after a located index to be returned. 177 Parameters are: 179 subFilter A search expression that defines the extent of the 180 virtual search results. The filter expression in the 181 search operation itself may be, for example, 182 "objectclass=person" and the subFilter expression in 183 the virtual list control may be "cn=m*", to retrieve 184 a subset of entries starting at or centered around 185 those with a common name beginning with the letter 186 "M". 188 beforeCount The number of entries before "listIndex" to be 190 JAVA LDAP CONTROLS September 1997 192 returned. 194 afterCount The number of entries after "listIndex" to be 195 returned. 197 3.1.2.2. getAfterCount 199 public int getAfterCount() 201 Returns the number of entries after the top/center one to return per 202 page of results. 204 3.1.2.3. getBeforeCount 206 public int getBeforeCount() 208 Returns the number of entries before the top/center one to return per 209 page of results. 211 3.1.2.4. getListSize 213 public int getListSize() 215 Returns the size of the virtual search results list. For a newly con- 216 structed control - one which is not the result of parseResponse on a 217 control returned by a server - the method returns -1. 219 3.1.2.5. setRange 221 public void setRange( int listIndex, 222 int beforeCount, 223 int afterCount ) 225 Sets the center or starting list index to return, and the number of 226 results before and after. 228 Parameters are: 230 listIndex The center or starting list index to be returned. 232 beforeCount The number of entries before "listIndex" to be 233 returned. 235 afterCount The number of entries after "listIndex" to be 237 JAVA LDAP CONTROLS September 1997 239 returned. 241 3.1.2.6. parseResult 243 public LDAPVirtualListControl parseResponse() 245 public static LDAPVirtualListControl parseResponse( 246 LDAPControl[] controls ) 248 When applied to a virtual list control returned by a server, par- 249 seResponse returns a new virtual list control which can be used for 250 subsequent searches using the same substringFilter. The second form 251 processes a list of controls, one of which may or may not be an LDAP- 252 VirtualListControl. The input is typically provided with the 253 LDAPConnection.getResponseControls method. 255 Parameters are: 257 controls An array of controls. It may be null. 259 3.1.3. public class LDAPSortControl extends LDAPControl 261 LDAPSortControl is a Server Control to specify how search results are to 262 be sorted by the server (see [5]). If a server does not support sorting 263 in general or for a particular query, the results will be returned 264 unsorted, along with a control indicating why they were not sorted (or 265 that sort controls are not supported). If the control was marked "criti- 266 cal", the whole search operation will fail if the sort control is not 267 supported. 269 3.1.3.1. Constructors 271 public LDAPSortControl( LDAPSortKey key, boolean critical) 273 Constructs a sort control with a single key. 275 public LDAPSortControl( LDAPSortKey[] keys, boolean critical) 277 Constructs a sort control with multiple sort keys. 279 Parameters are: 281 key A sort key object, which specifies attribute, order, 283 JAVA LDAP CONTROLS September 1997 285 and optional matching rule. 287 keys An array of sort key objects, to be processed in 288 order. 290 critical True if the search operation is to fail if the server 291 does not support this control. 293 3.1.3.2. parseResponse 295 public static String parseResponse( LDAPControl[] controls, 296 int results[] ) 298 Processes an array of Server Controls to determine if sorting was 299 rejected, and if so, why. If sorting was rejected, the return value 300 is the attribute name which caused sorting to fail. results[0] con- 301 tains the result code on return. The result code is one defined in 302 [1], section 4.1.10. 304 Parameters are: 306 controls An array of Server Controls, typically obtained with 307 LDAPConnection.getResponseControls(). It may be null, 308 which is equivalent to no error. 310 4. Security Considerations 312 See [2] for security considerations in the java LDAP API. 314 JAVA LDAP CONTROLS September 1997 316 5. Bibliography 318 [1] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol 319 (v3)", Internet Draft draft-ietf-asid-ldapv3-protocol-06.txt, July 320 1997. 322 [2] R. Weltman, T. Howes, M. Smith, "The Java LDAP Application Program 323 Interface", Internet Draft draft-ietf-asid-ldap-java-api-01.txt, 324 September 1997. 326 [3] H. Alvestrans, "Tags for the Identification of Languages", Request 327 for Comments 1766, March 1995. 329 [4] M. Wahl, T. Howes, "Use of Language Codes in LDAPv3", Internet 330 Draft draft-ietf-asid-ldapv3-lang-02.txt, June 1997. 332 [5] A. Herron, T. Howes, M. Wahl, "LDAP Control Extension for Server 333 Side Sorting of Search Results", Internet Draft draft-ietf-asid- 334 ldapv3-sorting-00.txt, April 1997. 336 [6] D. Boreham, "LDAP Control Extension for Virtual List View Browsing 337 of Search Results", Internet Draft draft-ietf-asid-ldapv3- 338 virtuallistview-01.txt, October 1997. 340 [7] C. Weider, A Herron, T. Howes, "LDAP Control Extension for Simple 341 Paged Results Manipulation", Internet Draft draft-ietf-asid- 342 ldapv3-simple-paged-01.txt, March 1997. 344 6. Author's Address 346 Rob Weltman 347 Netscape Communications Corp. 348 501 E. Middlefield Rd. 349 Mountain View, CA 94043 350 USA 351 +1 650 937-3301 352 rweltman@netscape.com 354 7. Appendix A - Sample usage of the java LDAP controls 356 Doing a search with results sorted on the server 358 import netscape.ldap.*; 359 import netscape.ldap.controls.*; 360 import java.util.*; 362 public class SearchJensenSorted { 364 JAVA LDAP CONTROLS September 1997 366 public static void main( String[] args ) 367 { 368 try { 369 LDAPConnection ld = new LDAPConnection(); 370 /* Connect to server */ 371 String MY_HOST = "localhost"; 372 int MY_PORT = 389; 373 ld.connect( MY_HOST, MY_PORT ); 375 /* search for all entries with surname of Jensen */ 376 String MY_FILTER = "sn=Jensen"; 377 String MY_SEARCHBASE = "o=Ace Industry, c=US"; 379 /* Get the common name, uid, and telephone number */ 380 String[] attrs = new String[3]; 381 attrs[0] = "cn"; 382 attrs[1] = "telephonenumber"; 383 attrs[2] = "uid"; 385 /* Sort by lastname, firstname */ 386 LDAPSortKey[] keys = new LDAPSortKey[2]; 387 keys[0] = new LDAPSortKey( "sn" ); 388 keys[1] = new LDAPSortKey( "givenname" ); 389 LDAPSortControl sort = new LDAPSortControl( keys, true ); 390 ld.setOption( LDAPConnection.SERVERCONTROLS, sort ); 392 LDAPSearchResults res = ld.search( MY_SEARCHBASE, 393 LDAPConnection.SCOPE_ONE, 394 MY_FILTER, 395 attrs, 396 false ); 398 /* Loop on results until finished */ 399 while ( res.hasMoreElements() ) { 401 /* Next directory entry */ 402 LDAPEntry findEntry = (LDAPEntry)res.nextElement(); 403 System.out.println( findEntry.getDN() ); 405 /* Get the attributes of the entry */ 406 LDAPAttributeSet findAttrs = findEntry.getAttributeSet(); 407 Enumeration enumAttrs = findAttrs.getAttributes(); 408 System.out.println( "Attributes: " ); 410 /* Loop on attributes */ 411 while ( enumAttrs.hasMoreElements() ) { 412 LDAPAttribute anAttr = 413 (LDAPAttribute)enumAttrs.nextElement(); 415 JAVA LDAP CONTROLS September 1997 417 String attrName = anAttr.getName(); 418 System.out.println( "" + attrName ); 419 /* Loop on values for this attribute */ 420 Enumeration enumVals = anAttr.getStringValues(); 421 while ( enumVals.hasMoreElements() ) { 422 String aVal = ( String )enumVals.nextElement(); 423 System.out.println( "" + aVal ); 424 } 425 } 426 } 428 /* Check if the server had something to say about the 429 sort request */ 430 LDAPControl[] controls = ld.getResponseControls(); 431 if ( controls != null ) { 432 int[] results = new int[1]; 433 String bad = LDAPSortControl.parseResponse( controls, 434 results ); 435 if ( results[0] != 0 ) { 436 System.out.println( "Error code: " + results[0] ); 437 if ( bad != null ) 438 System.out.println( "Offending attribute: " + 439 bad ); 440 else 441 System.out.println( "No offending attribute + 442 "returned" ); 443 } 444 } 445 } 446 catch( LDAPException e ) { 447 System.out.println( "Error: " + e.toString() ); 448 } 449 /* Done, so disconnect */ 450 if ( ld.isConnected() ) 451 ld.disconnect(); 452 } 453 } 455 JAVA LDAP CONTROLS September 1997 457 Using virtual list controls - excerpts from an application 459 import netscape.ldap.*; 460 import netscape.ldap.controls.*; 462 // Call this to initialize the list box, whenever the search 463 // conditions change. 464 // "filter" may be "objectclass=person", for example, and 465 // "subFilter" might be "cn>=m*" 466 void initListBox( String base, int scope, String filter, 467 String attrs, String subFilter ) { 468 // Record the virtual list box settings 469 beforeCount = 2; 470 afterCount = getScrollVisibleSize() - beforeCount - 1; 471 this.base = base; 472 this.scope = scope; 473 this.filter = filter; 474 this.attrs = attrs; 475 // Create the initial virtual list control 476 pageControls = new LDAPControl[2]; 477 pageControls[0] = new LDAPVirtualListControl( subFilter, 478 beforeCount, 479 afterCount ); 480 // virtual list also require a sort control 481 pageControls[1] = new LDAPSortControl( new LDAPSortKey("cn"), 482 true ); 483 // We have no idea yet how big the virtual list is, so just 484 // hint that there is more than what is visible 485 setScrollRange( 0, 100 ); 486 // Do an initial update of the scroll box 487 onScrollListBox(); 488 } 490 // This is called any time the list box needs to be updated. It 491 // fetches an appropriate page of results from the server. 492 void onScrollListBox() { 493 // Where is the list scrolled to now? 494 int topOfList = getScrollTop(); 495 // Check if we have a control returned from a previous search 496 LDAPVirtualListControl nextCont = 497 LDAPVirtualListControl.parseResponse( 498 ld.getResponseControls() ); 499 // If this is the first search, use the initial settings; 500 // otherwise use the just-retrieved control 501 if ( nextCont != null ) { 502 nextCont.setRange( topOfList, beforeCount, afterCount ); 503 pageControls[0] = nextCont; 504 // Now we know the total size of the virtual list box 506 JAVA LDAP CONTROLS September 1997 508 setScrollRange( 0, nextCont.getListSize() ); 509 } 510 ld.setControls( pageControls ); 511 // Fetch a page of results 512 LDAPSearchResults res = ld.search( base, scope, filter, 513 attrs, false ); 514 // and display them in the list box 515 showResults( res ); 516 } 518 private int beforeCount, afterCount; 519 private String base, filter, attrs; 520 private int scope; 521 private LDAPControl[] pageControls; 523 JAVA LDAP CONTROLS September 1997 525 8. Appendix D - Outstanding issues 527 8.1. Virtual List Control 529 The described LDAPVirtualListControl does not correspond to the Paged 530 Results Control described in [7], which was found to be less useful than 531 the one described in this document. 533 1. Introduction...................................................1 534 2. Overview of the LDAP Control classes...........................2 535 3. The java LDAP Control classes..................................3 536 3.1. LDAPLanguageControl..........................................3 537 3.1.1. Constructors.............................................3 538 3.1.2. LDAPVirtualListControl....................................4 539 3.1.2.1. Constructors..........................................4 540 3.1.2.2. getAfterCount.........................................5 541 3.1.2.3. getBeforeCount........................................5 542 3.1.2.4. getListSize...........................................5 543 3.1.2.5. setRange..............................................5 544 3.1.2.6. parseResult...........................................6 545 3.1.3. LDAPSortControl...........................................6 546 3.1.3.1. Constructors..........................................6 547 4. Security Considerations........................................7 548 5. Bibliography...................................................8 549 6. Author's Address...............................................8 550 7. Appendix A - Sample usage of the java LDAP controls............8 551 8. Appendix D - Outstanding issues................................13 552 8.1. Virtual List Control........................................13