add API endpoint for getting file definitions (#4511)

fixes #4508

Author: vladak

Diff for: apiary.apib

@@ -145,6 +145,90 @@ The `Content-type` header of the reply will be set accordingly.
 
             genre as identified by analyzer, could be PLAIN, XREFABLE, IMAGE, DATA, HTML
 
+## File definitions [/file/defs{?path}]
+
+### get file definitions [GET]
+
++ Parameters
+  + path (string) - path of file, relative to source root
+
++ Response 200 (application/json)
+  + Body
+
+            [
+              {
+                "type": "function",
+                "signature": "(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "text": "void AES_cbc_encrypt(const unsigned char *in, unsigned char *out,",
+                "symbol": "AES_cbc_encrypt",
+                "lineStart": 5,
+                "lineEnd": 20,
+                "line": 20,
+                "namespace": null
+              },
+              {
+                "type": "argument",
+                "signature": "(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "text": "AES_cbc_encrypt(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "symbol": "in",
+                "lineStart": 21,
+                "lineEnd": 44,
+                "line": 20,
+                "namespace": null
+              },
+              {
+                "type": "argument",
+                "signature": "(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "text": "AES_cbc_encrypt(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "symbol": "out",
+                "lineStart": 46,
+                "lineEnd": 64,
+                "line": 20,
+                "namespace": null
+              },
+              {
+                "type": "argument",
+                "signature": "(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "text": "AES_cbc_encrypt(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "symbol": "len",
+                "lineStart": 21,
+                "lineEnd": 31,
+                "line": 21,
+                "namespace": null
+              },
+              {
+                "type": "argument",
+                "signature": "(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "text": "AES_cbc_encrypt(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "symbol": "key",
+                "lineStart": 33,
+                "lineEnd": 51,
+                "line": 21,
+                "namespace": null
+              },
+              {
+                "type": "argument",
+                "signature": "(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "text": "AES_cbc_encrypt(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "symbol": "ivec",
+                "lineStart": 21,
+                "lineEnd": 40,
+                "line": 22,
+                "namespace": null
+              },
+              {
+                "type": "argument",
+                "signature": "(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "text": "AES_cbc_encrypt(const unsigned char * in,unsigned char * out,size_t len,const AES_KEY * key,unsigned char * ivec,const int enc)",
+                "symbol": "enc",
+                "lineStart": 42,
+                "lineEnd": 55,
+                "line": 22,
+                "namespace": null
+              }
+            ]
+
+
 ## History [/history{?path,withFiles,start,max}]
 
 ### get history entries [GET]

Diff for: opengrok-indexer/src/main/java/org/opengrok/indexer/analysis/Definitions.java

@@ -18,12 +18,13 @@
  */
 
 /*
- * Copyright (c) 2008, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2023, Oracle and/or its affiliates. All rights reserved.
  * Portions Copyright (c) 2018, Chris Fraire <[email protected]>.
  */
 package org.opengrok.indexer.analysis;
 
 import org.jetbrains.annotations.Nullable;
+import org.opengrok.indexer.util.DTOElement;
 import org.opengrok.indexer.util.WhitelistObjectInputFilter;
 
 import java.io.ByteArrayInputStream;
@@ -206,46 +207,91 @@ public static class Tag implements Serializable {
 
         private static final long serialVersionUID = 1217869075425651465L;
 
+        public int getLine() {
+            return line;
+        }
+
+        public String getSymbol() {
+            return symbol;
+        }
+
         /**
          * Line number of the tag.
          */
+        @DTOElement
         public final int line;
         /**
          * The symbol used in the definition.
          */
+        @DTOElement
         public final String symbol;
+
+        public String getType() {
+            return type;
+        }
+
+        public String getText() {
+            return text;
+        }
+
+        public String getNamespace() {
+            return namespace;
+        }
+
+        public String getSignature() {
+            return signature;
+        }
+
+        public int getLineStart() {
+            return lineStart;
+        }
+
+        public int getLineEnd() {
+            return lineEnd;
+        }
+
         /**
          * The type of the tag.
          */
+        @DTOElement
         public final String type;
         /**
          * The full line on which the definition occurs.
          */
+        @DTOElement
         public final String text;
         /**
          * Namespace/class of tag definition.
          */
+        @DTOElement
         public final String namespace;
         /**
          * Scope of tag definition.
          */
+        @DTOElement
         public final String signature;
         /**
          * The starting offset (possibly approximate) of {@link #symbol} from
          * the start of the line.
          */
+        @DTOElement
         public final int lineStart;
         /**
          * The ending offset (possibly approximate) of {@link #symbol} from
          * the start of the line.
          */
+        @DTOElement
         public final int lineEnd;
 
         /**
          * A non-serialized marker for marking a tag to avoid its reuse.
          */
         private transient boolean used;
 
+        protected Tag() {
+            this(0, null, null, null, null, null, 0, 0);
+        }
+
         protected Tag(int line, String symbol, String type, String text,
                 String namespace, String signature, int lineStart,
                 int lineEnd) {

Diff for: opengrok-web/src/main/java/org/opengrok/web/api/v1/controller/FileController.java

@@ -18,7 +18,7 @@
  */
 
 /*
- * Copyright (c) 2020, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved.
  * Portions Copyright (c) 2020, Chris Fraire <[email protected]>.
  */
 package org.opengrok.web.api.v1.controller;
@@ -35,16 +35,23 @@
 import org.apache.lucene.document.Document;
 import org.apache.lucene.queryparser.classic.ParseException;
 import org.opengrok.indexer.analysis.AbstractAnalyzer;
+import org.opengrok.indexer.analysis.Definitions;
+import org.opengrok.indexer.index.IndexDatabase;
 import org.opengrok.indexer.search.QueryBuilder;
 import org.opengrok.web.api.v1.filter.CorsEnable;
 import org.opengrok.web.api.v1.filter.PathAuthorized;
+import org.opengrok.web.util.DTOUtil;
 import org.opengrok.web.util.NoPathParameterException;
 
 import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.Collection;
+import java.util.List;
+import java.util.Optional;
+import java.util.stream.Collectors;
 
 import static org.opengrok.indexer.index.IndexDatabase.getDocument;
 import static org.opengrok.web.util.FileUtil.toFile;
@@ -54,6 +61,8 @@ public class FileController {
 
     public static final String PATH = "file";
 
+
+
     private StreamingOutput transfer(File file) throws FileNotFoundException {
         if (!file.exists()) {
             throw new FileNotFoundException(String.format("file %s does not exist", file));
@@ -141,4 +150,24 @@ public String getGenre(@Context HttpServletRequest request,
 
         return genre.toString();
     }
+
+    @GET
+    @CorsEnable
+    @PathAuthorized
+    @Path("/defs")
+    @Produces(MediaType.APPLICATION_JSON)
+    public List<Object> getDefinitions(@Context HttpServletRequest request,
+                                                @Context HttpServletResponse response,
+                                                @QueryParam("path") final String path)
+            throws IOException, NoPathParameterException, ParseException, ClassNotFoundException {
+
+        File file = toFile(path);
+        Definitions defs = IndexDatabase.getDefinitions(file);
+        return Optional.ofNullable(defs).
+                map(Definitions::getTags).
+                stream().
+                flatMap(Collection::stream).
+                map(DTOUtil::createDTO).
+                collect(Collectors.toList());
+    }
 }