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  
23  import org.apache.directory.api.ldap.model.message.Control;
24  
25  import java.util.EnumSet;
26  import java.util.Set;
27  
28  /**
29   * The DirSync control, as described in http://tools.ietf.org/html/draft-armijo-ldap-dirsync-00.
30   * We use the same control for both the SearchRequest and the SearchResultDone. Here is the
31   * ASN/1 description of the SearchRequest control :
32   * 
33   * <pre>
34   * Repl    Control ::= SEQUENCE {
35   *     controlType             1.2.840.113556.1.4.841
36   *     controlValue            replControlValue
37   *     criticality             TRUE
38   * }
39   * 
40   * the control value can be one of the two structures :
41   * 
42   * Client side :
43   * realReplControlValue ::= SEQUENCE {
44   *     flags                 integer
45   *     maxBytes              integer
46   *     cookie                OCTET STRING
47   * }
48   * 
49   * or
50   * 
51   * server side :
52   * realReplControlValue ::= SEQUENCE {
53   *     flag                  integer
54   *     maxBytes              integer
55   *     cookie                OCTET STRING
56   * }
57   * </pre> 
58   *
59   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
60   *
61   */
62  public interface AdDirSync extends Control
63  {
64      /** This control OID */
65      String OID = "1.2.840.113556.1.4.841";
66  
67      /**
68       * @return The maximum length of attributes to be returned
69       */
70      int getMaxReturnLength();
71  
72  
73      /**
74       * @param maxReturnLength The maximum length of attributes to be returned
75       */
76      void setMaxReturnLength( int maxReturnLength );
77  
78  
79      /**
80       * @return The cookie used while processing the successive DirSync operations
81       */
82      byte[] getCookie();
83  
84  
85      /**
86       * @param cookie The cookie to send to the server. It's the value found in the response control. Should be null
87       * for the first control.
88       */
89      void setCookie( byte[] cookie );
90  
91  
92      /**
93       * @return The flags returned by the server. Zero or more of :
94       * <ul>
95       * <li>LDAP_DIRSYNC_OBJECT_SECURITY (0x0001)</li>
96       * <li>LDAP_DIRSYNC_ANCESTORS_FIRST_ORDER (0x0800)</li>
97       * <li>LDAP_DIRSYNC_PUBLIC_DATA_ONLY (0x2000)(</li>
98       * <li>LDAP_DIRSYNC_INCREMENTAL_VALUES (0x7FFFFFFF)</li>
99       * </ul>
100      */
101     Set<AdDirSyncFlag> getFlags();
102 
103 
104     /**
105      * @param flags The flags to be set. See {@link EnumSet} for how to generate EnumSets.
106      */
107     void setFlags( Set<AdDirSyncFlag> flags );
108 
109 
110     /**
111      * @param flag The flag to be added to the current collection of flags.
112      */
113     void addFlag( AdDirSyncFlag flag );
114 
115 
116     /**
117      * @param flag The flag to be removed from the current collection of flags. 
118      */
119     void removeFlag( AdDirSyncFlag flag );
120 }