001/* 002 * Copyright 2008-2018 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2015-2018 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 the virtual attributes only request 038 * control, which may be included in a search request to indicate that only 039 * virtual attributes should be included in matching entries. 040 * <BR> 041 * <BLOCKQUOTE> 042 * <B>NOTE:</B> This class, and other classes within the 043 * {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only 044 * supported for use against Ping Identity, UnboundID, and Alcatel-Lucent 8661 045 * server products. These classes provide support for proprietary 046 * functionality or for external specifications that are not considered stable 047 * or mature enough to be guaranteed to work in an interoperable way with 048 * other types of LDAP servers. 049 * </BLOCKQUOTE> 050 * <BR> 051 * This control is not based on any public standard, but was first introduced in 052 * the Netscape/iPlanet Directory Server. It is also supported in the Sun Java 053 * System Directory Server, OpenDS, and the Ping Identity, UnboundID, and 054 * Alcatel-Lucent 8661 Directory Server. It does not have a value. 055 * <BR><BR> 056 * <H2>Example</H2> 057 * The following example demonstrates the use of the virtual attributes only 058 * request control: 059 * <PRE> 060 * SearchRequest searchRequest = new SearchRequest("dc=example,dc=com", 061 * SearchScope.SUB, Filter.createEqualityFilter("uid", "john.doe")); 062 * 063 * searchRequest.addControl(new VirtualAttributesOnlyRequestControl()); 064 * SearchResult searchResult = connection.search(searchRequest); 065 * </PRE> 066 */ 067@NotMutable() 068@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 069public final class VirtualAttributesOnlyRequestControl 070 extends Control 071{ 072 /** 073 * The OID (2.16.840.1.113730.3.4.19) for the virtual attributes only request 074 * control. 075 */ 076 public static final String VIRTUAL_ATTRIBUTES_ONLY_REQUEST_OID = 077 "2.16.840.1.113730.3.4.19"; 078 079 080 081 /** 082 * The serial version UID for this serializable class. 083 */ 084 private static final long serialVersionUID = 1509094615426408618L; 085 086 087 088 /** 089 * Creates a new virtual attributes only request control. It will not be 090 * marked critical. 091 */ 092 public VirtualAttributesOnlyRequestControl() 093 { 094 this(false); 095 } 096 097 098 099 /** 100 * Creates a new virtual attributes only request control with the specified 101 * criticality. 102 * 103 * @param isCritical Indicates whether this control should be marked 104 * critical. 105 */ 106 public VirtualAttributesOnlyRequestControl(final boolean isCritical) 107 { 108 super(VIRTUAL_ATTRIBUTES_ONLY_REQUEST_OID, isCritical, null); 109 } 110 111 112 113 /** 114 * Creates a new virtual attributes only request control which is decoded from 115 * the provided generic control. 116 * 117 * @param control The generic control to be decoded as a virtual attributes 118 * only request control. 119 * 120 * @throws LDAPException If the provided control cannot be decoded as a 121 * virtual attributes only request control. 122 */ 123 public VirtualAttributesOnlyRequestControl(final Control control) 124 throws LDAPException 125 { 126 super(control); 127 128 if (control.hasValue()) 129 { 130 throw new LDAPException(ResultCode.DECODING_ERROR, 131 ERR_VIRTUAL_ATTRS_ONLY_REQUEST_HAS_VALUE.get()); 132 } 133 } 134 135 136 137 /** 138 * {@inheritDoc} 139 */ 140 @Override() 141 public String getControlName() 142 { 143 return INFO_CONTROL_NAME_VIRTUAL_ATTRS_ONLY_REQUEST.get(); 144 } 145 146 147 148 /** 149 * {@inheritDoc} 150 */ 151 @Override() 152 public void toString(final StringBuilder buffer) 153 { 154 buffer.append("VirtualAttributesOnlyRequestControl(isCritical="); 155 buffer.append(isCritical()); 156 buffer.append(')'); 157 } 158}