001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * docs/licenses/cddl.txt. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2013-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.ds.api; 028 029 030 031 import java.util.Collections; 032 import java.util.List; 033 import java.util.Map; 034 035 import com.unboundid.directory.sdk.broker.internal.IdentityBrokerExtension; 036 import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider; 037 import com.unboundid.directory.sdk.common.internal.Reconfigurable; 038 import com.unboundid.directory.sdk.common.internal.UnboundIDExtension; 039 import com.unboundid.directory.sdk.common.types.OperationContext; 040 import com.unboundid.directory.sdk.ds.config.SearchReferenceCriteriaConfig; 041 import com.unboundid.directory.sdk.ds.types.DirectoryServerContext; 042 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 043 import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension; 044 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension; 045 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension; 046 import com.unboundid.ldap.sdk.Control; 047 import com.unboundid.ldap.sdk.LDAPException; 048 import com.unboundid.ldap.sdk.ResultCode; 049 import com.unboundid.util.Extensible; 050 import com.unboundid.util.ThreadSafety; 051 import com.unboundid.util.ThreadSafetyLevel; 052 import com.unboundid.util.args.ArgumentException; 053 import com.unboundid.util.args.ArgumentParser; 054 055 056 057 /** 058 * This class defines an API that must be implemented by extensions which can 059 * be used to classify client search result entries. 060 * <BR> 061 * <H2>Configuring Search Reference Criteria</H2> 062 * In order to configure a search reference criteria object created using this 063 * API, use a command like: 064 * <PRE> 065 * dsconfig create-search-reference-criteria \ 066 * --criteria-name "<I>{criteria-name}</I>" \ 067 * --type third-party \ 068 * --set enabled:true \ 069 * --set "extension-class:<I>{class-name}</I>" \ 070 * --set "extension-argument:<I>{name=value}</I>" 071 * </PRE> 072 * where "<I>{criteria-name}</I>" is the name to use for the search reference 073 * criteria instance, "<I>{class-name}</I>" is the fully-qualified name of the 074 * Java class that extends 075 * {@code com.unboundid.directory.sdk.ds.api.SearchReferenceCriteria}, and 076 * "<I>{name=value}</I>" represents name-value pairs for any arguments to 077 * provide to the search reference criteria. If multiple arguments should be 078 * provided to the search reference criteria instance, then the 079 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be 080 * provided multiple times. 081 */ 082 @Extensible() 083 @DirectoryServerExtension() 084 @DirectoryProxyServerExtension(appliesToLocalContent=true, 085 appliesToRemoteContent=true) 086 @SynchronizationServerExtension(appliesToLocalContent=true, 087 appliesToSynchronizedContent=false) 088 @MetricsEngineExtension() 089 @IdentityBrokerExtension() 090 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 091 public abstract class SearchReferenceCriteria 092 implements UnboundIDExtension, 093 Reconfigurable<SearchReferenceCriteriaConfig>, 094 ExampleUsageProvider 095 { 096 /** 097 * Creates a new instance of this search reference criteria. All search 098 * reference criteria implementations must include a default constructor, but 099 * any initialization should generally be done in the 100 * {@code initializeSearchReferenceCriteria} method. 101 */ 102 public SearchReferenceCriteria() 103 { 104 // No implementation is required. 105 } 106 107 108 109 /** 110 * {@inheritDoc} 111 */ 112 public abstract String getExtensionName(); 113 114 115 116 /** 117 * {@inheritDoc} 118 */ 119 public abstract String[] getExtensionDescription(); 120 121 122 123 /** 124 * {@inheritDoc} 125 */ 126 public void defineConfigArguments(final ArgumentParser parser) 127 throws ArgumentException 128 { 129 // No arguments will be allowed by default. 130 } 131 132 133 134 /** 135 * Initializes this search reference criteria. 136 * 137 * @param serverContext A handle to the server context for the server in 138 * which this extension is running. 139 * @param config The general configuration for this search reference 140 * criteria. 141 * @param parser The argument parser which has been initialized from 142 * the configuration for this search reference 143 * criteria. 144 * 145 * @throws LDAPException If a problem occurs while initializing this search 146 * reference criteria. 147 */ 148 public void initializeSearchReferenceCriteria( 149 final DirectoryServerContext serverContext, 150 final SearchReferenceCriteriaConfig config, 151 final ArgumentParser parser) 152 throws LDAPException 153 { 154 // No initialization will be performed by default. 155 } 156 157 158 159 /** 160 * {@inheritDoc} 161 */ 162 public boolean isConfigurationAcceptable( 163 final SearchReferenceCriteriaConfig config, 164 final ArgumentParser parser, 165 final List<String> unacceptableReasons) 166 { 167 // No extended validation will be performed by default. 168 return true; 169 } 170 171 172 173 /** 174 * {@inheritDoc} 175 */ 176 public ResultCode applyConfiguration( 177 final SearchReferenceCriteriaConfig config, 178 final ArgumentParser parser, 179 final List<String> adminActionsRequired, 180 final List<String> messages) 181 { 182 // By default, no configuration changes will be applied. If there are any 183 // arguments, then add an admin action message indicating that the extension 184 // needs to be restarted for any changes to take effect. 185 if (! parser.getNamedArguments().isEmpty()) 186 { 187 adminActionsRequired.add( 188 "No configuration change has actually been applied. The new " + 189 "configuration will not take effect until this search " + 190 "reference criteria is disabled and re-enabled or until the " + 191 "server is restarted."); 192 } 193 194 return ResultCode.SUCCESS; 195 } 196 197 198 199 /** 200 * Performs any cleanup which may be necessary when this search reference 201 * criteria is to be taken out of service. 202 */ 203 public void finalizeSearchReferenceCriteria() 204 { 205 // No implementation is required. 206 } 207 208 209 210 /** 211 * Indicates whether the provided operation matches the criteria for this 212 * search reference criteria object. 213 * 214 * @param o The context for the associated search operation. 215 * @param referralURLs The URLs for the reference for which to make the 216 * determination. 217 * @param controls The controls included with the search result entry. 218 * 219 * @return {@code true} if the provided operation matches the criteria for 220 * this search entry criteria object, or {@code false} if not. 221 */ 222 public abstract boolean matches(final OperationContext o, 223 final List<String> referralURLs, 224 final List<Control> controls); 225 226 227 228 /** 229 * {@inheritDoc} 230 */ 231 public Map<List<String>,String> getExamplesArgumentSets() 232 { 233 return Collections.emptyMap(); 234 } 235 }