Line data    Source code

       1             : // Copyright (C) 2018 The Android Open Source Project
       2             : //
       3             : // Licensed under the Apache License, Version 2.0 (the "License");
       4             : // you may not use this file except in compliance with the License.
       5             : // You may obtain a copy of the License at
       6             : //
       7             : // http://www.apache.org/licenses/LICENSE-2.0
       8             : //
       9             : // Unless required by applicable law or agreed to in writing, software
      10             : // distributed under the License is distributed on an "AS IS" BASIS,
      11             : // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      12             : // See the License for the specific language governing permissions and
      13             : // limitations under the License.
      14             : 
      15             : package com.google.gerrit.server.plugincontext;
      16             : 
      17             : import static java.util.Objects.requireNonNull;
      18             : 
      19             : import com.google.gerrit.extensions.registration.DynamicSet;
      20             : import com.google.gerrit.extensions.registration.Extension;
      21             : import com.google.gerrit.server.plugincontext.PluginContext.CheckedExtensionImplFunction;
      22             : import com.google.gerrit.server.plugincontext.PluginContext.ExtensionImplConsumer;
      23             : import com.google.gerrit.server.plugincontext.PluginContext.ExtensionImplFunction;
      24             : import com.google.gerrit.server.plugincontext.PluginContext.PluginMetrics;
      25             : 
      26             : /**
      27             :  * Context to invoke an extension from {@link DynamicSet}.
      28             :  *
      29             :  * <p>When the plugin extension is invoked a logging tag with the plugin name is set. This way any
      30             :  * errors that are triggered by the plugin extension (even if they happen in Gerrit code which is
      31             :  * called by the plugin extension) can be easily attributed to the plugin.
      32             :  *
      33             :  * <p>The run* methods execute the extension but don't deliver a result back to the caller.
      34             :  * Exceptions can be caught and logged.
      35             :  *
      36             :  * <p>The call* methods execute the extension and deliver a result back to the caller.
      37             :  *
      38             :  * <p>Example if all exceptions should be caught and logged:
      39             :  *
      40             :  * <pre>{@code
      41             :  * fooPluginSetEntryContext.run(foo -> foo.doFoo());
      42             :  * }</pre>
      43             :  *
      44             :  * <p>Example if all exceptions, but one, should be caught and logged:
      45             :  *
      46             :  * <pre>{@code
      47             :  * try {
      48             :  *   fooPluginSetEntryContext.run(foo -> foo.doFoo(), MyException.class);
      49             :  * } catch (MyException e) {
      50             :  *   // handle the exception
      51             :  * }
      52             :  * }</pre>
      53             :  *
      54             :  * <p>Example if return values should be handled:
      55             :  *
      56             :  * <pre>{@code
      57             :  * Object result = fooPluginSetEntryContext.call(foo -> foo.getFoo());
      58             :  * }</pre>
      59             :  *
      60             :  * <p>Example if return values and a single exception should be handled:
      61             :  *
      62             :  * <pre>{@code
      63             :  * Object result;
      64             :  * try {
      65             :  *   result = fooPluginSetEntryContext.call(foo -> foo.getFoo(), MyException.class);
      66             :  * } catch (MyException e) {
      67             :  *   // handle the exception
      68             :  * }
      69             :  * }</pre>
      70             :  *
      71             :  * <p>Example if several exceptions should be handled:
      72             :  *
      73             :  * <pre>{@code
      74             :  * for (Extension<Foo> fooExtension : fooDynamicSet.entries()) {
      75             :  *   try (TraceContext traceContext = PluginContext.newTrace(fooExtension)) {
      76             :  *     fooExtension.get().doFoo();
      77             :  *   } catch (MyException1 | MyException2 | MyException3 e) {
      78             :  *     // handle the exception
      79             :  *   }
      80             :  * }
      81             :  * }</pre>
      82             :  */
      83             : public class PluginSetEntryContext<T> {
      84             :   private final Extension<T> extension;
      85             :   private final PluginMetrics pluginMetrics;
      86             : 
      87         139 :   PluginSetEntryContext(Extension<T> extension, PluginMetrics pluginMetrics) {
      88         139 :     this.extension = requireNonNull(extension);
      89         139 :     this.pluginMetrics = pluginMetrics;
      90         139 :   }
      91             : 
      92             :   /**
      93             :    * Returns the name of the plugin that registered this extension.
      94             :    *
      95             :    * @return the plugin name
      96             :    */
      97             :   public String getPluginName() {
      98         103 :     return extension.getPluginName();
      99             :   }
     100             : 
     101             :   /**
     102             :    * Returns the implementation of this extension.
     103             :    *
     104             :    * <p>Should only be used in exceptional cases to get direct access to the extension
     105             :    * implementation. If possible the extension should be invoked through {@link
     106             :    * #run(PluginContext.ExtensionImplConsumer)}, {@link #run(PluginContext.ExtensionImplConsumer,
     107             :    * java.lang.Class)}, {@link #call(PluginContext.ExtensionImplFunction)} and {@link
     108             :    * #call(PluginContext.CheckedExtensionImplFunction, java.lang.Class)}.
     109             :    *
     110             :    * @return the implementation of this extension
     111             :    */
     112             :   public T get() {
     113          62 :     return extension.get();
     114             :   }
     115             : 
     116             :   /**
     117             :    * Invokes the plugin extension. All exceptions from the plugin extension are caught and logged.
     118             :    *
     119             :    * <p>The consumer gets the extension implementation provided that should be invoked.
     120             :    *
     121             :    * @param extensionImplConsumer consumer that invokes the extension
     122             :    */
     123             :   public void run(ExtensionImplConsumer<T> extensionImplConsumer) {
     124         116 :     PluginContext.runLogExceptions(pluginMetrics, extension, extensionImplConsumer);
     125         116 :   }
     126             : 
     127             :   /**
     128             :    * Invokes the plugin extension. All exceptions from the plugin extension are caught and logged.
     129             :    *
     130             :    * <p>The consumer gets the extension implementation provided that should be invoked.
     131             :    *
     132             :    * @param extensionImplConsumer consumer that invokes the extension
     133             :    * @param exceptionClass type of the exceptions that should be thrown
     134             :    * @throws X expected exception from the plugin extension
     135             :    */
     136             :   public <X extends Exception> void run(
     137             :       ExtensionImplConsumer<T> extensionImplConsumer, Class<X> exceptionClass) throws X {
     138           0 :     PluginContext.runLogExceptions(pluginMetrics, extension, extensionImplConsumer, exceptionClass);
     139           0 :   }
     140             : 
     141             :   /**
     142             :    * Calls the plugin extension and returns the result from the plugin extension call.
     143             :    *
     144             :    * <p>The function gets the extension point provided that should be invoked.
     145             :    *
     146             :    * @param extensionImplFunction function that invokes the extension
     147             :    * @return the result from the plugin extension
     148             :    */
     149             :   public <R> R call(ExtensionImplFunction<T, R> extensionImplFunction) {
     150         139 :     return PluginContext.call(pluginMetrics, extension, extensionImplFunction);
     151             :   }
     152             : 
     153             :   /**
     154             :    * Calls the plugin extension and returns the result from the plugin extension call. Exceptions of
     155             :    * the specified type are thrown and must be handled by the caller.
     156             :    *
     157             :    * <p>The function gets the extension implementation provided that should be invoked.
     158             :    *
     159             :    * @param checkedExtensionImplFunction function that invokes the extension
     160             :    * @param exceptionClass type of the exceptions that should be thrown
     161             :    * @return the result from the plugin extension
     162             :    * @throws X expected exception from the plugin extension
     163             :    */
     164             :   public <R, X extends Exception> R call(
     165             :       CheckedExtensionImplFunction<T, R, X> checkedExtensionImplFunction, Class<X> exceptionClass)
     166             :       throws X {
     167           0 :     return PluginContext.call(
     168             :         pluginMetrics, extension, checkedExtensionImplFunction, exceptionClass);
     169             :   }
     170             : }