View Javadoc
1   /*
2    *  Licensed to the Apache Software Foundation (ASF) under one
3    *  or more contributor license agreements.  See the NOTICE file
4    *  distributed with this work for additional information
5    *  regarding copyright ownership.  The ASF licenses this file
6    *  to you under the Apache License, Version 2.0 (the
7    *  "License"); you may not use this file except in compliance
8    *  with the License.  You may obtain a copy of the License at
9    *
10   *    http://www.apache.org/licenses/LICENSE-2.0
11   *
12   *  Unless required by applicable law or agreed to in writing,
13   *  software distributed under the License is distributed on an
14   *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   *  KIND, either express or implied.  See the License for the
16   *  specific language governing permissions and limitations
17   *  under the License.
18   *
19   */
20  package org.apache.directory.api.ldap.extras.controls.ad;
21  
22  import org.apache.directory.api.ldap.model.message.Control;
23  
24  /**
25   * The DirSync control, as described in http://tools.ietf.org/html/draft-armijo-ldap-dirsync-00.
26   * We use the same control for both the SearchRequest and the SearchResultDone. Here is the
27   * ASN/1 description of the SearchRequest control :
28   * 
29   * <pre>
30   * Repl    Control ::= SEQUENCE {
31   *     controlType             1.2.840.113556.1.4.841
32   *     controlValue            replControlValue
33   *     criticality             TRUE
34   * }
35   * 
36   * the control value can be one of the two structures :
37   * 
38   * Client side :
39   * realReplControlValue ::= SEQUENCE {
40   *     parentsFirst            integer
41   *     maxReturnLength         integer
42   *     cookie                  OCTET STRING
43   * }
44   * 
45   * or
46   * 
47   * server side :
48   * realReplControlValue ::= SEQUENCE {
49   *     flag                  integer
50   *     maxReturnLength       integer
51   *     cookie                OCTET STRING
52   * }
53   * </pre> 
54   *
55   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
56   *
57   */
58  public interface AdDirSync extends Control
59  {
60      /** This control OID */
61      static final String OID = "1.2.840.113556.1.4.841";
62      
63      /**
64       * @return 1 if the parents are guaranteed to be returned before the children.
65       */
66      int getParentFirst();
67      
68      
69      /**
70       * @param parentFirst The parentFirst flag. A value of 1 will tell the server to return the parents first.
71       */
72      void setParentFirst( int parentFirst );
73      
74      
75      /**
76       * @return The maximum length of attributes to be returned
77       */
78      int getMaxReturnLength();
79      
80      
81      /**
82       * @param maxReturnLength The maximum length of attributes to be returned
83       */
84      void setMaxReturnLength( int maxReturnLength );
85      
86      
87      /**
88       * @return The cookie used while processing the successive DirSync operations
89       */
90      byte[] getCookie();
91      
92      
93      /**
94       * @param cookie The cookie to send to the server. It's the value found in the response control. Should be null
95       * for the first control.
96       */
97      void setCookie( byte[] cookie );
98      
99      
100     /**
101      * @return The flag returned by the server. One of :
102      * <ul>
103      * <li>LDAP_DIRSYNC_OBJECT_SECURITY (0x0001)</li>
104      * <li>LDAP_DIRSYNC_ANCESTORS_FIRST_ORDER (0x0800)</li>
105      * <li>LDAP_DIRSYNC_PUBLIC_DATA_ONLY (0x2000)(</li>
106      * <li>LDAP_DIRSYNC_INCREMENTAL_VALUES (0x7FFFFFFF)</li>
107      * </ul>
108      */
109     AdDirSyncFlag getFlag();
110     
111     
112     /**
113      * @param flag The flag. 
114      */
115     void setFlag( AdDirSyncFlag flag );
116 }