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 * http://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 */
020 package org.apache.directory.shared.ldap.message.control;
021
022
023 import org.apache.directory.shared.asn1.codec.EncoderException;
024 import org.apache.directory.shared.ldap.codec.search.controls.subEntry.SubEntryControlCodec;
025
026 import org.slf4j.Logger;
027 import org.slf4j.LoggerFactory;
028
029
030 /**
031 * The control for the visibility of subentries with search operations. For
032 * convenience we attach section 3 from <a
033 * href="http://www.faqs.org/rfcs/rfc3672.html"> RFC 3672</a> where the control
034 * is defined:
035 *
036 * <pre>
037 * 3. Subentries Control
038 *
039 * The subentries control MAY be sent with a searchRequest to control
040 * the visibility of entries and subentries which are within scope.
041 * Non-visible entries or subentries are not returned in response to the
042 * request.
043 *
044 * The subentries control is an LDAP Control whose controlType is
045 * 1.3.6.1.4.1.4203.1.10.1, criticality is TRUE or FALSE (hence absent),
046 * and controlValue contains a BER-encoded BOOLEAN indicating
047 * visibility. A controlValue containing the value TRUE indicates that
048 * subentries are visible and normal entries are not. A controlValue
049 * containing the value FALSE indicates that normal entries are visible
050 * and subentries are not.
051 *
052 * Note that TRUE visibility has the three octet encoding { 01 01 FF }
053 * and FALSE visibility has the three octet encoding { 01 01 00 }.
054 *
055 * The controlValue SHALL NOT be absent.
056 *
057 * In absence of this control, subentries are not visible to singleLevel
058 * and wholeSubtree scope Search requests but are visible to baseObject
059 * scope Search requests.
060 *
061 * There is no corresponding response control.
062 *
063 * This control is not appropriate for non-Search operations.
064 * </pre>
065 *
066 * @see <a href="http://www.faqs.org/rfcs/rfc3672.html">RFC 3672</a>
067 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
068 * @version $Rev: 764131 $
069 */
070 public class SubentriesControl extends InternalAbstractControl
071 {
072 private static final long serialVersionUID = -2356861450876343999L;
073
074 private static final Logger log = LoggerFactory.getLogger( SubentriesControl.class );
075
076 public static final String CONTROL_OID = "1.3.6.1.4.1.4203.1.10.1";
077
078 /** the visibility for this control */
079 private boolean visibility = false;
080
081
082 public SubentriesControl()
083 {
084 super();
085 setID( CONTROL_OID );
086 }
087
088
089 public void setVisibility( boolean visibility )
090 {
091 this.visibility = visibility;
092 }
093
094
095 public boolean isVisible()
096 {
097 return visibility;
098 }
099
100
101 public byte[] getEncodedValue()
102 {
103 SubEntryControlCodec ctl = new SubEntryControlCodec();
104 ctl.setVisibility( isVisible() );
105
106 try
107 {
108 return ctl.encode( null ).array();
109 }
110 catch ( EncoderException e )
111 {
112 log.error( "Failed to encode SubentriesControl", e );
113 throw new IllegalStateException( "Failed to encode control with encoder.", e );
114 }
115 }
116 }