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 *      Portions Copyright 2010-2023 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.proxy.scripting;
028
029
030
031import java.util.List;
032
033import com.unboundid.directory.sdk.common.internal.Reconfigurable;
034import com.unboundid.directory.sdk.proxy.config.ProxyTransformationConfig;
035import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
036import com.unboundid.directory.sdk.proxy.internal.SearchResultProvider;
037import com.unboundid.directory.sdk.proxy.types.ProxyOperationContext;
038import com.unboundid.directory.sdk.proxy.types.ProxyServerContext;
039import com.unboundid.ldap.sdk.AddRequest;
040import com.unboundid.ldap.sdk.BindRequest;
041import com.unboundid.ldap.sdk.BindResult;
042import com.unboundid.ldap.sdk.CompareRequest;
043import com.unboundid.ldap.sdk.DeleteRequest;
044import com.unboundid.ldap.sdk.LDAPException;
045import com.unboundid.ldap.sdk.LDAPResult;
046import com.unboundid.ldap.sdk.ModifyRequest;
047import com.unboundid.ldap.sdk.ModifyDNRequest;
048import com.unboundid.ldap.sdk.ReadOnlyAddRequest;
049import com.unboundid.ldap.sdk.ReadOnlyCompareRequest;
050import com.unboundid.ldap.sdk.ReadOnlyDeleteRequest;
051import com.unboundid.ldap.sdk.ReadOnlyModifyRequest;
052import com.unboundid.ldap.sdk.ReadOnlyModifyDNRequest;
053import com.unboundid.ldap.sdk.ReadOnlySearchRequest;
054import com.unboundid.ldap.sdk.ResultCode;
055import com.unboundid.ldap.sdk.SearchRequest;
056import com.unboundid.ldap.sdk.SearchResult;
057import com.unboundid.ldap.sdk.SearchResultEntry;
058import com.unboundid.ldap.sdk.SearchResultReference;
059import com.unboundid.util.Extensible;
060import com.unboundid.util.ThreadSafety;
061import com.unboundid.util.ThreadSafetyLevel;
062import com.unboundid.util.args.ArgumentException;
063import com.unboundid.util.args.ArgumentParser;
064
065
066
067/**
068 * This class defines an API that must be implemented by scripted extensions
069 * which are used to transform requests and/or responses as they pass through
070 * the Directory Proxy Server.  They may be used to alter the contents of any
071 * add, bind, compare, delete, modify, modify DN, or search request or result
072 * passing through the Directory Proxy Server, or they may cause a result to be
073 * returned to the client without it being forwarded to a backend server.  In
074 * addition, transformations may be applied to search result entries and
075 * references to be returned to the client, or those entries and references may
076 * be silently dropped so that they are not returned.
077 * <BR>
078 * <H2>Configuring Groovy-Scripted Proxy Transformations</H2>
079 * In order to configure a scripted proxy transformation based on this API and
080 * written in the Groovy scripting language, use a command like:
081 * <PRE>
082 *      dsconfig create-proxy-transformation \
083 *           --transformation-name "<I>{transformation-name}</I>" \
084 *           --type groovy-scripted \
085 *           --set enabled:true \
086 *           --set "script-class:<I>{class-name}</I>" \
087 *           --set "script-argument:<I>{name=value}</I>"
088 * </PRE>
089 * where "<I>{transformation-name}</I>" is the name to use for the proxy
090 * transformation instance, "<I>{class-name}</I>" is the fully-qualified name of
091 * the Groovy class written using this API, and "<I>{name=value}</I>" represents
092 * name-value pairs for any arguments to provide to the proxy transformation.
093 * If multiple arguments should be provided to the proxy transformation, then
094 * the "<CODE>--set script-argument:<I>{name=value}</I></CODE>" option should be
095 * provided multiple times.
096 *
097 * @see  com.unboundid.directory.sdk.proxy.api.ProxyTransformation
098 */
099@Extensible()
100@DirectoryProxyServerExtension(appliesToLocalContent=false,
101     appliesToRemoteContent=true)
102@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
103public abstract class ScriptedProxyTransformation
104       implements Reconfigurable<ProxyTransformationConfig>
105{
106  /**
107   * Creates a new instance of this proxy transformation.  All proxy
108   * transformation implementations must include a default constructor, but any
109   * initialization should generally be done in the
110   * {@code initializeProxyTransformation} method.
111   */
112  public ScriptedProxyTransformation()
113  {
114    // No implementation is required.
115  }
116
117
118
119  /**
120   * {@inheritDoc}
121   */
122  public void defineConfigArguments(final ArgumentParser parser)
123         throws ArgumentException
124  {
125    // No arguments will be allowed by default.
126  }
127
128
129
130  /**
131   * Initializes this proxy transformation.
132   *
133   * @param  serverContext  A handle to the server context for the server in
134   *                        which this extension is running.
135   * @param  config         The general configuration for this proxy
136   *                        transformation.
137   * @param  parser         The argument parser which has been initialized from
138   *                        the configuration for this proxy transformation.
139   *
140   * @throws  LDAPException  If a problem occurs while initializing this proxy
141   *                         transformation.
142   */
143  public void initializeProxyTransformation(
144                   final ProxyServerContext serverContext,
145                   final ProxyTransformationConfig config,
146                   final ArgumentParser parser)
147         throws LDAPException
148  {
149    // No initialization will be performed by default.
150  }
151
152
153
154  /**
155   * Performs any cleanup which may be necessary when this proxy transformation
156   * is to be taken out of service.
157   */
158  public void finalizeProxyTransformation()
159  {
160    // No implementation is required.
161  }
162
163
164
165  /**
166   * {@inheritDoc}
167   */
168  public boolean isConfigurationAcceptable(
169                      final ProxyTransformationConfig config,
170                      final ArgumentParser parser,
171                      final List<String> unacceptableReasons)
172  {
173    // No extended validation will be performed.
174    return true;
175  }
176
177
178
179  /**
180   * {@inheritDoc}
181   */
182  public ResultCode applyConfiguration(final ProxyTransformationConfig config,
183                                       final ArgumentParser parser,
184                                       final List<String> adminActionsRequired,
185                                       final List<String> messages)
186  {
187    // By default, no configuration changes will be applied.  If there are any
188    // arguments, then add an admin action message indicating that the extension
189    // needs to be restarted for any changes to take effect.
190    if (! parser.getNamedArguments().isEmpty())
191    {
192      adminActionsRequired.add(
193           "No configuration change has actually been applied.  The new " +
194                "configuration will not take effect until this proxy " +
195                "transformation is disabled and re-enabled or until the " +
196                "server is restarted.");
197    }
198
199    return ResultCode.SUCCESS;
200  }
201
202
203
204  /**
205   * Applies any necessary transformation to the provided add request.
206   *
207   * @param  operationContext  Information about the operation being processed
208   *                           in the Directory Proxy Server.
209   * @param  addRequest        The add request to be transformed.
210   *
211   * @return  A new add request which has been transformed as necessary, or the
212   *          original request if no transformation is required or the provided
213   *          add request has been updated in place.
214   *
215   * @throws  LDAPException  If a problem is encountered while processing the
216   *                         transformation, or if the provided request should
217   *                         not be forwarded to a backend server.
218   */
219  public AddRequest transformAddRequest(
220                         final ProxyOperationContext operationContext,
221                         final AddRequest addRequest)
222         throws LDAPException
223  {
224    return addRequest;
225  }
226
227
228
229  /**
230   * Applies any necessary transformation to the provided add result.
231   *
232   * @param  operationContext  Information about the operation being processed
233   *                           in the Directory Proxy Server.
234   * @param  addRequest        The add request that was processed.
235   * @param  addResult         The add result to be transformed.
236   *
237   * @return  A new add result which has been transformed as necessary, or the
238   *          original result if no transformation is required or the provided
239   *          add result has been updated in place.
240   */
241  public LDAPResult transformAddResult(
242                         final ProxyOperationContext operationContext,
243                         final ReadOnlyAddRequest addRequest,
244                         final LDAPResult addResult)
245  {
246    return addResult;
247  }
248
249
250
251  /**
252   * Applies any necessary transformation to the provided bind request.
253   *
254   * @param  operationContext  Information about the operation being processed
255   *                           in the Directory Proxy Server.
256   * @param  bindRequest       The bind request to be transformed.
257   *
258   * @return  A new bind request which has been transformed as necessary, or the
259   *          original request if no transformation is required.
260   *
261   * @throws  LDAPException  If a problem is encountered while processing the
262   *                         transformation, or if the provided request should
263   *                         not be forwarded to a backend server.
264   */
265  public BindRequest transformBindRequest(
266                         final ProxyOperationContext operationContext,
267                         final BindRequest bindRequest)
268         throws LDAPException
269  {
270    return bindRequest;
271  }
272
273
274
275  /**
276   * Applies any necessary transformation to the provided bind request.
277   *
278   * @param  operationContext  Information about the operation being processed
279   *                           in the Directory Proxy Server.
280   * @param  bindRequest       The bind request that was processed.
281   * @param  bindResult        The bind result to be transformed.
282   *
283   * @return  A new bind result which has been transformed as necessary, or the
284   *          original result if no transformation is required.
285   */
286  public BindResult transformBindResult(
287                         final ProxyOperationContext operationContext,
288                         final BindRequest bindRequest,
289                         final BindResult bindResult)
290  {
291    return bindResult;
292  }
293
294
295
296  /**
297   * Applies any necessary transformation to the provided compare request.
298   *
299   * @param  operationContext  Information about the operation being processed
300   *                           in the Directory Proxy Server.
301   * @param  compareRequest    The compare request to be transformed.
302   *
303   * @return  A new compare request which has been transformed as necessary, or
304   *          the original request if no transformation is required or the
305   *          provided compare request has been updated in place.
306   *
307   * @throws  LDAPException  If a problem is encountered while processing the
308   *                         transformation, or if the provided request should
309   *                         not be forwarded to a backend server.
310   */
311  public CompareRequest transformCompareRequest(
312                             final ProxyOperationContext operationContext,
313                             final CompareRequest compareRequest)
314         throws LDAPException
315  {
316    return compareRequest;
317  }
318
319
320
321  /**
322   * Applies any necessary transformation to the provided compare result.
323   *
324   * @param  operationContext  Information about the operation being processed
325   *                           in the Directory Proxy Server.
326   * @param  compareRequest    The compare request that was processed.
327   * @param  compareResult     The compare result to be transformed.
328   *
329   * @return  A new compare result which has been transformed as necessary, or
330   *          the original result if no transformation is required or the
331   *          provided compare result has been updated in place.
332   */
333  public LDAPResult transformCompareResult(
334                         final ProxyOperationContext operationContext,
335                         final ReadOnlyCompareRequest compareRequest,
336                         final LDAPResult compareResult)
337  {
338    return compareResult;
339  }
340
341
342
343  /**
344   * Applies any necessary transformation to the provided delete request.
345   *
346   * @param  operationContext  Information about the operation being processed
347   *                           in the Directory Proxy Server.
348   * @param  deleteRequest     The delete request to be transformed.
349   *
350   * @return  A new delete request which has been transformed as necessary, or
351   *          the original request if no transformation is required or the
352   *          provided delete request has been updated in place.
353   *
354   * @throws  LDAPException  If a problem is encountered while processing the
355   *                         transformation, or if the provided request should
356   *                         not be forwarded to a backend server.
357   */
358  public DeleteRequest transformDeleteRequest(
359                            final ProxyOperationContext operationContext,
360                            final DeleteRequest deleteRequest)
361         throws LDAPException
362  {
363    return deleteRequest;
364  }
365
366
367
368  /**
369   * Applies any necessary transformation to the provided delete result.
370   *
371   * @param  operationContext  Information about the operation being processed
372   *                           in the Directory Proxy Server.
373   * @param  deleteRequest     The delete request that was processed.
374   * @param  deleteResult      The delete result to be transformed.
375   *
376   * @return  A new delete result which has been transformed as necessary, or
377   *          the original result if no transformation is required or the
378   *          provided delete result has been updated in place.
379   */
380  public LDAPResult transformDeleteResult(
381                         final ProxyOperationContext operationContext,
382                         final ReadOnlyDeleteRequest deleteRequest,
383                         final LDAPResult deleteResult)
384  {
385    return deleteResult;
386  }
387
388
389
390  /**
391   * Applies any necessary transformation to the provided modify request.
392   *
393   * @param  operationContext  Information about the operation being processed
394   *                           in the Directory Proxy Server.
395   * @param  modifyRequest     The modify request to be transformed.
396   *
397   * @return  A new modify request which has been transformed as necessary, or
398   *          the original request if no transformation is required or the
399   *          provided modify request has been updated in place.
400   *
401   * @throws  LDAPException  If a problem is encountered while processing the
402   *                         transformation, or if the provided request should
403   *                         not be forwarded to a backend server.
404   */
405  public ModifyRequest transformModifyRequest(
406                            final ProxyOperationContext operationContext,
407                            final ModifyRequest modifyRequest)
408         throws LDAPException
409  {
410    return modifyRequest;
411  }
412
413
414
415  /**
416   * Applies any necessary transformation to the provided modify result.
417   *
418   * @param  operationContext  Information about the operation being processed
419   *                           in the Directory Proxy Server.
420   * @param  modifyRequest     The modify request that was processed.
421   * @param  modifyResult      The modify result to be transformed.
422   *
423   * @return  A new modify result which has been transformed as necessary, or
424   *          the original result if no transformation is required or the
425   *          provided modify result has been updated in place.
426   */
427  public LDAPResult transformModifyResult(
428                         final ProxyOperationContext operationContext,
429                         final ReadOnlyModifyRequest modifyRequest,
430                         final LDAPResult modifyResult)
431  {
432    return modifyResult;
433  }
434
435
436
437  /**
438   * Applies any necessary transformation to the provided modify DN request.
439   *
440   * @param  operationContext  Information about the operation being processed
441   *                           in the Directory Proxy Server.
442   * @param  modifyDNRequest   The modify DN request to be transformed.
443   *
444   * @return  A new modify DN request which has been transformed as necessary,
445   *          or the original request if no transformation is required or the
446   *          provided modify DN request has been updated in place.
447   *
448   * @throws  LDAPException  If a problem is encountered while processing the
449   *                         transformation, or if the provided request should
450   *                         not be forwarded to a backend server.
451   */
452  public ModifyDNRequest transformModifyDNRequest(
453                              final ProxyOperationContext operationContext,
454                              final ModifyDNRequest modifyDNRequest)
455         throws LDAPException
456  {
457    return modifyDNRequest;
458  }
459
460
461
462  /**
463   * Applies any necessary transformation to the provided modify DN result.
464   *
465   * @param  operationContext  Information about the operation being processed
466   *                           in the Directory Proxy Server.
467   * @param  modifyDNRequest   The modify DN request that was processed.
468   * @param  modifyDNResult    The modify DN result to be transformed.
469   *
470   * @return  A new modify DN result which has been transformed as necessary, or
471   *          the original result if no transformation is required or the
472   *          provided modify DN result has been updated in place.
473   */
474  public LDAPResult transformModifyDNResult(
475                         final ProxyOperationContext operationContext,
476                         final ReadOnlyModifyDNRequest modifyDNRequest,
477                         final LDAPResult modifyDNResult)
478  {
479    return modifyDNResult;
480  }
481
482
483
484  /**
485   * Applies any necessary transformation to the provided search request.
486   *
487   * @param  operationContext  Information about the operation being processed
488   *                           in the Directory Proxy Server.
489   * @param  searchRequest     The search request to be transformed.
490   *
491   * @return  A new search request which has been transformed as necessary, or
492   *          the original request if no transformation is required or the
493   *          provided search request has been updated in place.
494   *
495   * @throws  LDAPException  If a problem is encountered while processing the
496   *                         transformation, or if the provided request should
497   *                         not be forwarded to a backend server.
498   */
499  public SearchRequest transformSearchRequest(
500                            final ProxyOperationContext operationContext,
501                            final SearchRequest searchRequest)
502         throws LDAPException
503  {
504    return searchRequest;
505  }
506
507
508
509  /**
510   * Applies any necessary transformation to the provided search result.
511   *
512   * @param  operationContext  Information about the operation being processed
513   *                           in the Directory Proxy Server.
514   * @param  searchRequest     The search request that was processed.
515   * @param  searchResult      The search result to be transformed.
516   * @param  resultProvider    The search result provider which may be used to
517   *                           send additional search result entries and/or
518   *                           references to the client.
519   *
520   * @return  A new search result which has been transformed as necessary, or
521   *          the original result if no transformation is required or the
522   *          provided search result has been updated in place.
523   */
524  public SearchResult transformSearchResult(
525                           final ProxyOperationContext operationContext,
526                           final ReadOnlySearchRequest searchRequest,
527                           final SearchResult searchResult,
528                           final SearchResultProvider resultProvider)
529  {
530    return searchResult;
531  }
532
533
534
535  /**
536   * Applies any necessary transformation to the provided search result entry.
537   *
538   * @param  operationContext  Information about the operation being processed
539   *                           in the Directory Proxy Server.
540   * @param  searchRequest     The search request that is being processed.
541   * @param  searchEntry       The search result entry to be transformed.
542   *
543   * @return  A new search result entry which has been transformed as necessary,
544   *          the original search result entry if no transformation is required,
545   *          or {@code null} if the entry should not be returned to the client.
546   */
547  public SearchResultEntry transformSearchResultEntry(
548                                final ProxyOperationContext operationContext,
549                                final ReadOnlySearchRequest searchRequest,
550                                final SearchResultEntry searchEntry)
551  {
552    return searchEntry;
553  }
554
555
556
557  /**
558   * Applies any necessary transformation to the provided search result
559   * reference.
560   *
561   * @param  operationContext  Information about the operation being processed
562   *                           in the Directory Proxy Server.
563   * @param  searchRequest     The search request that is being processed.
564   * @param  searchReference   The search result reference to be transformed.
565   *
566   * @return  A new search result reference which has been transformed as
567   *          necessary, the original search result reference if no
568   *          transformation is required, or {@code null} if the reference
569   *          should not be returned to the client.
570   */
571  public SearchResultReference transformSearchResultReference(
572              final ProxyOperationContext operationContext,
573              final ReadOnlySearchRequest searchRequest,
574              final SearchResultReference searchReference)
575  {
576    return searchReference;
577  }
578}