001 /*
002 * Copyright 2008-2013 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2008-2013 UnboundID Corp.
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021 package com.unboundid.ldap.sdk.controls;
022
023
024
025 import com.unboundid.ldap.sdk.Control;
026 import com.unboundid.ldap.sdk.LDAPException;
027 import com.unboundid.ldap.sdk.ResultCode;
028 import com.unboundid.util.NotMutable;
029 import com.unboundid.util.ThreadSafety;
030 import com.unboundid.util.ThreadSafetyLevel;
031
032 import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
033
034
035
036 /**
037 * This class provides an implementation of the LDAP subentries request control
038 * as defined in draft-ietf-ldup-subentry. It may be included in a search
039 * request to indicate that the entries with the {@code ldapSubentry} object
040 * class should be included in the search results.
041 * <BR><BR>
042 * Entries containing the {@code ldapSubentry} object class are special in that
043 * they are normally excluded from search results, unless the target entry is
044 * requested with a base-level search. They are used to store operational
045 * information that controls how the server should behave rather than user data.
046 * Because they do not hold user data, it is generally desirable to have them
047 * excluded from search results, but for cases in which a client needs to
048 * retrieve such an entry, then this subentries request control may be included
049 * in the search request.
050 * <BR><BR>
051 * There is no corresponding response control.
052 * <BR><BR>
053 * <H2>Example</H2>
054 * The following example illustrates the use of the subentries request control.
055 * It attempts to retrieve all subentries defined below "dc=example,dc=com":
056 * <PRE>
057 * SearchRequest searchRequest =
058 * new SearchRequest("dc=example,dc=com", SearchScope.SUB,
059 * "(objectClass=ldapSubentry)");
060 * searchRequest.addControl(new SubentriesRequestControl());
061 * SearchResult searchResult = connection.search(searchRequest());
062 *
063 * for (SearchResultEntry e : searchResult.getSearchEntries())
064 * {
065 * // Do something with the entry.
066 * }
067 * </PRE>
068 */
069 @NotMutable()
070 @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
071 public final class SubentriesRequestControl
072 extends Control
073 {
074 /**
075 * The OID (1.3.6.1.4.1.7628.5.101.1) for the LDAP subentries request control.
076 */
077 public static final String SUBENTRIES_REQUEST_OID =
078 "1.3.6.1.4.1.7628.5.101.1";
079
080
081
082 /**
083 * The serial version UID for this serializable class.
084 */
085 private static final long serialVersionUID = 4772130172594841481L;
086
087
088
089 /**
090 * Creates a new subentries request control. it will not be marked critical.
091 */
092 public SubentriesRequestControl()
093 {
094 this(false);
095 }
096
097
098
099 /**
100 * Creates a new subentries request control with the specified criticality.
101 *
102 * @param isCritical Indicates whether this control should be marked
103 * critical.
104 */
105 public SubentriesRequestControl(final boolean isCritical)
106 {
107 super(SUBENTRIES_REQUEST_OID, isCritical, null);
108 }
109
110
111
112 /**
113 * Creates a new subentries request control which is decoded from the provided
114 * generic control.
115 *
116 * @param control The generic control to be decoded as a subentries request
117 * control.
118 *
119 * @throws LDAPException If the provided control cannot be decoded as a
120 * subentries request control.
121 */
122 public SubentriesRequestControl(final Control control)
123 throws LDAPException
124 {
125 super(control);
126
127 if (control.hasValue())
128 {
129 throw new LDAPException(ResultCode.DECODING_ERROR,
130 ERR_SUBENTRIES_HAS_VALUE.get());
131 }
132 }
133
134
135
136 /**
137 * {@inheritDoc}
138 */
139 @Override()
140 public String getControlName()
141 {
142 return INFO_CONTROL_NAME_SUBENTRIES_REQUEST.get();
143 }
144
145
146
147 /**
148 * {@inheritDoc}
149 */
150 @Override()
151 public void toString(final StringBuilder buffer)
152 {
153 buffer.append("SubentriesRequestControl(isCritical=");
154 buffer.append(isCritical());
155 buffer.append(')');
156 }
157 }