1 /*
   2  * Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.
   8  *
   9  * This code is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * version 2 for more details (a copy is included in the LICENSE file that
  13  * accompanied this code).
  14  *
  15  * You should have received a copy of the GNU General Public License version
  16  * 2 along with this work; if not, write to the Free Software Foundation,
  17  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  18  *
  19  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  20  * or visit www.oracle.com if you need additional information or have any
  21  * questions.
  22  */
  23 package org.graalvm.graphio;
  24 
  25 /**
  26  * Representation of methods, fields, their signatures and code locations.
  27  *
  28  * @param <M> type representing methods
  29  * @param <F> type representing fields
  30  * @param <S> type representing signature
  31  * @param <P> type representing source code location
  32  */
  33 public interface GraphElements<M, F, S, P> {
  34     /**
  35      * Recognize method. Can the object be seen as a method?
  36      *
  37      * @param obj the object to check
  38      * @return <code>null</code> if the object isn't a method, non-null value otherwise
  39      */
  40     M method(Object obj);
  41 
  42     /**
  43      * Bytecode for a method.
  44      *
  45      * @param method the method
  46      * @return bytecode of the method
  47      */
  48     byte[] methodCode(M method);
  49 
  50     /**
  51      * Method modifiers.
  52      *
  53      * @param method the method
  54      * @return its modifiers
  55      */
  56     int methodModifiers(M method);
  57 
  58     /**
  59      * Method's signature.
  60      *
  61      * @param method the method
  62      * @return signature of the method
  63      */
  64     S methodSignature(M method);
  65 
  66     /**
  67      * Method name.
  68      *
  69      * @param method the method
  70      * @return name of the method
  71      */
  72     String methodName(M method);
  73 
  74     /**
  75      * Method's declaring class. The returned object shall be a {@link Class} or be recognizable by
  76      * {@link GraphTypes#typeName(java.lang.Object)} method.
  77      *
  78      * @param method the method
  79      * @return object representing class that defined the method
  80      */
  81     Object methodDeclaringClass(M method);
  82 
  83     /**
  84      * Recognizes a field. Can the object be seen as a field?
  85      *
  86      * @param object the object to check
  87      * @return <code>null</code> if the object isn't a field, non-null value otherwise
  88      */
  89     F field(Object object);
  90 
  91     /**
  92      * Field modifiers.
  93      *
  94      * @param field the field
  95      * @return field modifiers
  96      */
  97     int fieldModifiers(F field);
  98 
  99     /**
 100      * Type name of the field.
 101      *
 102      * @param field the field
 103      * @return the name of the field's type
 104      */
 105     String fieldTypeName(F field);
 106 
 107     /**
 108      * Name of a field.
 109      *
 110      * @param field the field
 111      * @return the name of the field
 112      */
 113     String fieldName(F field);
 114 
 115     /**
 116      * Field's declaring class. The returned object shall be a {@link Class} or be recognizable by
 117      * {@link GraphTypes#typeName(java.lang.Object)} method.
 118      *
 119      * @param field the field
 120      * @return object representing class that defined the field
 121      */
 122     Object fieldDeclaringClass(F field);
 123 
 124     /**
 125      * Recognizes signature. Can the object be seen as a signature?
 126      *
 127      * @param object the object to check
 128      * @return <code>null</code> if the object isn't a signature, non-null value otherwise
 129      */
 130     S signature(Object object);
 131 
 132     /**
 133      * Number of parameters of a signature.
 134      *
 135      * @param signature the signature
 136      * @return number of parameters
 137      */
 138     int signatureParameterCount(S signature);
 139 
 140     /**
 141      * Type name of a signature parameter.
 142      *
 143      * @param signature the signature
 144      * @param index index from 0 to {@link #signatureParameterCount(java.lang.Object)} - 1
 145      * @return the type name
 146      */
 147     String signatureParameterTypeName(S signature, int index);
 148 
 149     /**
 150      * Type name of a return type.
 151      *
 152      * @param signature the signature
 153      * @return the type name
 154      */
 155     String signatureReturnTypeName(S signature);
 156 
 157     /**
 158      * Recognize a source position. Can the object be seen as a position?
 159      *
 160      * @param object the object to check
 161      * @return <code>null</code> if the object isn't a position, non-null otherwise
 162      */
 163     P nodeSourcePosition(Object object);
 164 
 165     /**
 166      * Method for a position.
 167      *
 168      * @param pos the position
 169      * @return the method at the position
 170      */
 171     M nodeSourcePositionMethod(P pos);
 172 
 173     /**
 174      * Caller of a position.
 175      *
 176      * @param pos the position
 177      * @return <code>null</code> or another position
 178      */
 179     P nodeSourcePositionCaller(P pos);
 180 
 181     /**
 182      * Byte code index of a position.
 183      *
 184      * @param pos the position
 185      * @return the BCI of the position
 186      */
 187     int nodeSourcePositionBCI(P pos);
 188 
 189     /**
 190      * Stack trace element for a method, index and position.
 191      *
 192      * @param method the method
 193      * @param bci the index
 194      * @param pos the position
 195      * @return stack trace element for the method, index and position
 196      */
 197     StackTraceElement methodStackTraceElement(M method, int bci, P pos);
 198 }