001/* 002 * Copyright 2008-2019 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2015-2019 Ping Identity Corporation 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 */ 021package com.unboundid.ldap.sdk.unboundidds.controls; 022 023 024 025import com.unboundid.ldap.sdk.Control; 026import com.unboundid.ldap.sdk.LDAPException; 027import com.unboundid.ldap.sdk.ResultCode; 028import com.unboundid.util.NotMutable; 029import com.unboundid.util.ThreadSafety; 030import com.unboundid.util.ThreadSafetyLevel; 031 032import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*; 033 034 035 036/** 037 * This class provides an implementation of a control which can be used to 038 * request that the Directory Server include extended information when returning 039 * a subschema subentry. In the Ping Identity, UnboundID, and 040 * Nokia/Alcatel-Lucent 8661 Directory Server, this will cause the server to 041 * include the X-SCHEMA-FILE extension (which contains the path to the file in 042 * which that schema element is defined) and the X-READ-ONLY extension (which 043 * indicates whether that schema element is read-only and cannot be altered by 044 * external clients). 045 * <BR> 046 * <BLOCKQUOTE> 047 * <B>NOTE:</B> This class, and other classes within the 048 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 049 * supported for use against Ping Identity, UnboundID, and 050 * Nokia/Alcatel-Lucent 8661 server products. These classes provide support 051 * for proprietary functionality or for external specifications that are not 052 * considered stable or mature enough to be guaranteed to work in an 053 * interoperable way with other types of LDAP servers. 054 * </BLOCKQUOTE> 055 * <BR> 056 * This control is not based on any public specification, and has been defined 057 * by Ping Identity Corporation It does not have a value, and may or may not be 058 * critical. It should only be included in search requests. 059 * <BR><BR> 060 * <H2>Example</H2> 061 * The following example demonstrates the procedure to use for requesting the 062 * Directory Server schema with extended information. Note that the 063 * {@code LDAPInterface.getSchema} and {@code Schema.getSchema} convenience 064 * methods cannot be used because they do not allow you to include controls in 065 * the request. 066 * <PRE> 067 * String schemaDN = Schema.getSubschemaSubentryDN(connection, ""); 068 * SearchRequest searchRequest = new SearchRequest(schemaDN, SearchScope.BASE, 069 * Filter.createPresenceFilter("objectClass"), "*", "+"); 070 * searchRequest.addControl(new ExtendedSchemaInfoRequestControl()); 071 * SearchResult searchResult = connection.search(searchRequest); 072 * 073 * Schema schema = null; 074 * if (searchResult.getEntryCount() == 1) 075 * { 076 * schema = new Schema(searchResult.getSearchEntries().get(0)); 077 * } 078 * </PRE> 079 */ 080@NotMutable() 081@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 082public final class ExtendedSchemaInfoRequestControl 083 extends Control 084{ 085 /** 086 * The OID (1.3.6.1.4.1.30221.2.5.12) for the extended schema info request 087 * control. 088 */ 089 public static final String EXTENDED_SCHEMA_INFO_REQUEST_OID = 090 "1.3.6.1.4.1.30221.2.5.12"; 091 092 093 /** 094 * The serial version UID for this serializable class. 095 */ 096 private static final long serialVersionUID = -5668945270252160026L; 097 098 099 100 /** 101 * Creates a new extended schema info request control. It will not be 102 * marked critical. 103 */ 104 public ExtendedSchemaInfoRequestControl() 105 { 106 this(false); 107 } 108 109 110 111 /** 112 * Creates a new extended schema info request control with the specified 113 * criticality. 114 * 115 * @param isCritical Indicates whether this control should be marked 116 * critical. 117 */ 118 public ExtendedSchemaInfoRequestControl(final boolean isCritical) 119 { 120 super(EXTENDED_SCHEMA_INFO_REQUEST_OID, isCritical, null); 121 } 122 123 124 125 /** 126 * Creates a new extended schema info request control which is decoded from 127 * the provided generic control. 128 * 129 * @param control The generic control to be decoded as an extended schema 130 * info request control. 131 * 132 * @throws LDAPException If the provided control cannot be decoded as an 133 * extended schema info request control. 134 */ 135 public ExtendedSchemaInfoRequestControl(final Control control) 136 throws LDAPException 137 { 138 super(control); 139 140 if (control.hasValue()) 141 { 142 throw new LDAPException(ResultCode.DECODING_ERROR, 143 ERR_EXTENDED_SCHEMA_INFO_REQUEST_HAS_VALUE.get()); 144 } 145 } 146 147 148 149 /** 150 * {@inheritDoc} 151 */ 152 @Override() 153 public String getControlName() 154 { 155 return INFO_CONTROL_NAME_EXTENDED_SCHEMA_INFO.get(); 156 } 157 158 159 160 /** 161 * {@inheritDoc} 162 */ 163 @Override() 164 public void toString(final StringBuilder buffer) 165 { 166 buffer.append("ExtendedSchemaInfoRequestControl(isCritical="); 167 buffer.append(isCritical()); 168 buffer.append(')'); 169 } 170}