Line data    Source code

       1             : // Copyright (C) 2014 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.plugins;
      16             : 
      17             : import java.io.IOException;
      18             : import java.io.InputStream;
      19             : import java.lang.annotation.Annotation;
      20             : import java.nio.file.NoSuchFileException;
      21             : import java.util.Collections;
      22             : import java.util.Map;
      23             : import java.util.Optional;
      24             : import java.util.jar.Manifest;
      25             : import java.util.stream.Stream;
      26             : 
      27             : /**
      28             :  * Scans the plugin returning classes and resources.
      29             :  *
      30             :  * <p>Gerrit uses the scanner to automatically discover the classes and resources exported by the
      31             :  * plugin for auto discovery of exported SSH commands, Servlets and listeners.
      32             :  */
      33             : public interface PluginContentScanner {
      34             : 
      35             :   /** Scanner without resources. */
      36           1 :   PluginContentScanner EMPTY =
      37           1 :       new PluginContentScanner() {
      38             :         @Override
      39             :         public Manifest getManifest() throws IOException {
      40           0 :           return new Manifest();
      41             :         }
      42             : 
      43             :         @Override
      44             :         public Map<Class<? extends Annotation>, Iterable<ExtensionMetaData>> scan(
      45             :             String pluginName, Iterable<Class<? extends Annotation>> annotations)
      46             :             throws InvalidPluginException {
      47           0 :           return Collections.emptyMap();
      48             :         }
      49             : 
      50             :         @Override
      51             :         public Optional<PluginEntry> getEntry(String resourcePath) {
      52           0 :           return Optional.empty();
      53             :         }
      54             : 
      55             :         @Override
      56             :         public InputStream getInputStream(PluginEntry entry) throws IOException {
      57           0 :           throw new NoSuchFileException("Empty plugin");
      58             :         }
      59             : 
      60             :         @Override
      61             :         public Stream<PluginEntry> entries() {
      62           0 :           return Stream.empty();
      63             :         }
      64             :       };
      65             : 
      66             :   /**
      67             :    * Plugin class extension meta-data
      68             :    *
      69             :    * <p>Class name and annotation value of the class provided by a plugin to extend an existing
      70             :    * extension point in Gerrit.
      71             :    */
      72             :   class ExtensionMetaData {
      73             :     public final String className;
      74             :     public final String annotationValue;
      75             : 
      76           1 :     public ExtensionMetaData(String className, String annotationValue) {
      77           1 :       this.className = className;
      78           1 :       this.annotationValue = annotationValue;
      79           1 :     }
      80             :   }
      81             : 
      82             :   /**
      83             :    * Return the plugin meta-data manifest
      84             :    *
      85             :    * @return Manifest of the plugin or null if plugin has no meta-data
      86             :    * @throws IOException if an I/O problem occurred whilst accessing the Manifest
      87             :    */
      88             :   Manifest getManifest() throws IOException;
      89             : 
      90             :   /**
      91             :    * Scans the plugin for declared public annotated classes
      92             :    *
      93             :    * @param pluginName the plugin name
      94             :    * @param annotations annotations declared by the plugin classes
      95             :    * @return map of annotations and associated plugin classes found
      96             :    * @throws InvalidPluginException if the plugin is not valid or corrupted
      97             :    */
      98             :   Map<Class<? extends Annotation>, Iterable<ExtensionMetaData>> scan(
      99             :       String pluginName, Iterable<Class<? extends Annotation>> annotations)
     100             :       throws InvalidPluginException;
     101             : 
     102             :   /**
     103             :    * Return the plugin resource associated to a path
     104             :    *
     105             :    * @param resourcePath full path of the resource inside the plugin package
     106             :    * @return the resource object or Optional.absent() if the resource was not found
     107             :    * @throws IOException if there was a problem retrieving the resource
     108             :    */
     109             :   Optional<PluginEntry> getEntry(String resourcePath) throws IOException;
     110             : 
     111             :   /**
     112             :    * Return the InputStream of the resource entry
     113             :    *
     114             :    * @param entry resource entry inside the plugin package
     115             :    * @return the resource input stream
     116             :    * @throws IOException if there was an I/O problem accessing the resource
     117             :    */
     118             :   InputStream getInputStream(PluginEntry entry) throws IOException;
     119             : 
     120             :   /**
     121             :    * Return all the resources inside a plugin
     122             :    *
     123             :    * @return the enumeration of all resources found
     124             :    */
     125             :   Stream<PluginEntry> entries();
     126             : }