001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    https://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.directory.api.ldap.extras.controls.ad;
021
022import java.util.EnumSet;
023import java.util.Set;
024
025import org.apache.directory.api.ldap.model.message.Control;
026
027
028/**
029 * The DirSync response control, as described in http://tools.ietf.org/html/draft-armijo-ldap-dirsync-00.
030 * Here is the ASN/1 description of the SearchRequest control :
031 *
032 * <pre>
033 * Repl    Control ::= SEQUENCE {
034 *     controlType             1.2.840.113556.1.4.841
035 *     controlValue            replControlValue
036 *     criticality             TRUE
037 * }
038 * </pre>
039 *
040 * the control value is :
041 * <pre>
042 * realReplControlValue ::= SEQUENCE {
043 *     flag                  integer
044 *     maxReturnLength       integer
045 *     cookie                OCTET STRING
046 * }
047 * </pre>
048 *
049 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
050 *
051 */
052public interface AdDirSyncResponse extends Control
053{
054    /** This control OID */
055    String OID = "1.2.840.113556.1.4.841";
056
057
058    /**
059     * @return The maximum length of attributes to be returned
060     */
061    int getMaxReturnLength();
062
063
064    /**
065     * @param maxReturnLength The maximum length of attributes to be returned
066     */
067    void setMaxReturnLength( int maxReturnLength );
068
069
070    /**
071     * @return The cookie used while processing the successive DirSync operations
072     */
073    byte[] getCookie();
074
075
076    /**
077     * @param cookie The cookie to send to the server. It's the value found in the response control. Should be null
078     * for the first control.
079     */
080    void setCookie( byte[] cookie );
081
082
083    /**
084     * @return The flags returned by the server. Zero or more of :
085     * <ul>
086     * <li>LDAP_DIRSYNC_OBJECT_SECURITY (0x0001)</li>
087     * <li>LDAP_DIRSYNC_ANCESTORS_FIRST_ORDER (0x0800)</li>
088     * <li>LDAP_DIRSYNC_PUBLIC_DATA_ONLY (0x2000)(</li>
089     * <li>LDAP_DIRSYNC_INCREMENTAL_VALUES (0x7FFFFFFF)</li>
090     * </ul>
091     */
092    Set<AdDirSyncResponseFlag> getFlags();
093
094
095    /**
096     * @param flags The flags to be set. See {@link EnumSet} for how to generate EnumSets.
097     */
098    void setFlags( Set<AdDirSyncResponseFlag> flags );
099
100
101    /**
102     * @param flag The flag to be added to the current collection of flags.
103     */
104    void addFlag( AdDirSyncResponseFlag flag );
105
106
107    /**
108     * @param flag The flag to be removed from the current collection of flags.
109     */
110    void removeFlag( AdDirSyncResponseFlag flag );
111}