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