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