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 org.apache.directory.api.ldap.model.message.Control;
023
024
025/**
026 * The DirSync request control, as described in http://tools.ietf.org/html/draft-armijo-ldap-dirsync-00.
027 * Here is the ASN/1 description of the SearchRequest control :
028 *
029 * <pre>
030 * Repl    Control ::= SEQUENCE {
031 *     controlType             1.2.840.113556.1.4.841
032 *     controlValue            replControlValue
033 *     criticality             TRUE
034 * }
035 * </pre>
036 *
037 * the control value is :
038 *
039 * <pre>
040 * Client side :
041 * realReplControlValue ::= SEQUENCE {
042 *     parentsFirst            integer
043 *     maxAttributeCount       integer
044 *     cookie                  OCTET STRING
045 * }
046 * </pre>
047 *
048 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
049 *
050 */
051public interface AdDirSyncRequest extends Control
052{
053    /** This control OID */
054    String OID = "1.2.840.113556.1.4.841";
055
056    /**
057     * @return 1 if the parents of the children comes before their children
058     */
059    int getParentsFirst();
060
061
062    /**
063     * Tell the server that it should send the parents of the children before
064     * their children.
065     * NOTE: it should have been a boolean, it's an integer instead.
066     *
067     * @param parentsFirst When set to 1, will return the parents before children
068     */
069    void setParentsFirst( int parentsFirst );
070
071
072    /**
073     * @return The maximum attribute count to be returned
074     */
075    int getMaxAttributeCount();
076
077
078    /**
079     * @param maxAttributeCount The maximum attribute count to be returned
080     */
081    void setMaxAttributeCount( int maxAttributeCount );
082
083
084    /**
085     * @return The cookie used while processing the successive DirSync operations
086     */
087    byte[] getCookie();
088
089
090    /**
091     * @param cookie The cookie to send to the server. It's the value found in the response control. Should be null
092     * for the first control.
093     */
094    void setCookie( byte[] cookie );
095}