Interface MappingVisitor

All Known Subinterfaces:
MappingWriter, VisitableMappingTree
All Known Implementing Classes:
CsrgFileWriter, EmptyElementFilter, EnigmaDirWriter, EnigmaFileWriter, FlatAsRegularMappingVisitor, ForwardingMappingVisitor, JamFileWriter, JobfFileWriter, MappingDstNsReorder, MappingNsCompleter, MappingNsRenamer, MappingSourceNsSwitch, MemoryMappingTree, MigrationMapFileWriter, MissingDescFilter, NopMappingVisitor, OuterClassNamePropagator, ProGuardFileWriter, RecafSimpleFileWriter, RedundantDstDataFilter, SrgFileWriter, Tiny1FileWriter, Tiny2FileWriter, TsrgFileWriter, VisitOrderVerifier
public interface MappingVisitor
Visitor with order implied context and consecutive dst name visits.

The visitation order is as follows (omitting visit prefixes for brevity, lowercase for cross-references):

  • overall: header -> content -> End -> overall
  • header: Header -> Namespaces [-> Metadata]*
  • content: Content [-> class|Metadata]*
  • class: Class [-> DstName]* -> ElementContent [-> field|method|Comment]*
  • field: Field [-> DstName|DstDesc]* -> ElementContent [-> Comment]
  • method: Method [-> DstName|DstDesc]* -> ElementContent [-> arg|var|Comment]*
  • arg: Arg [-> DstName]* -> ElementContent [-> Comment]
  • var: Var [-> DstName]* -> ElementContent [-> Comment]

The elements with a skip-return (Header/Content/Class/Field/Method/Arg/Var/ElementContent) abort processing the remainder of their associated item in the above listing if requested by a false return value. For example skipping in Class does neither DstName nor ElementContent, but continues with another class or End.

Returning false in End requests another complete visitation pass if the flag MappingFlag.NEEDS_MULTIPLE_PASSES is provided, otherwise the behavior is unspecified. This is used for visitors that first have to acquire some overall mapping knowledge before being able to perform their task. Subsequent visitation passes need to use the same namespaces and data, only a new independent visitation may use something else after a reset().

The same element may be visited more than once unless the flags contain MappingFlag.NEEDS_ELEMENT_UNIQUENESS.

If an exception is thrown during visitation, the visitor is to be considered in an invalid state. reset() must be called to clear the internal state before further visitations can happen.

  • Method Details

    • getFlags

      default Set<MappingFlag> getFlags()

    • reset

      default void reset()
      Reset the visitor, including any chained visitors, to allow for another independent visit (excluding visitEnd=false).

    • visitHeader

      default boolean visitHeader() throws IOException
      Determine whether the header (namespaces, metadata if part of the header) should be visited.
      Returns:
      true if the header is to be visited, false otherwise.
      Throws:
      IOException

    • visitNamespaces

      void visitNamespaces(String srcNamespace, List<String> dstNamespaces) throws IOException
      Throws:
      IOException

    • visitMetadata

      default void visitMetadata(String key, @Nullable @Nullable String value) throws IOException
      Throws:
      IOException

    • visitContent

      default boolean visitContent() throws IOException
      Determine whether the mapping content (classes and anything below, metadata if not part of the header) should be visited.
      Returns:
      true if content is to be visited, false otherwise.
      Throws:
      IOException

    • visitClass

      boolean visitClass(String srcName) throws IOException
      Visit a class.
      Parameters:
      srcName - The fully qualified source name of the class, in internal form (slashes instead of dots, dollar signs for delimiting inner classes).
      Returns:
      Whether the class's content should be visited too.
      Throws:
      IOException

    • visitField

      boolean visitField(String srcName, @Nullable @Nullable String srcDesc) throws IOException
      Throws:
      IOException

    • visitMethod

      boolean visitMethod(String srcName, @Nullable @Nullable String srcDesc) throws IOException
      Throws:
      IOException

    • visitMethodArg

      boolean visitMethodArg(int argPosition, int lvIndex, @Nullable @Nullable String srcName) throws IOException
      Visit a parameter.
      Parameters:
      argPosition - Always starts at 0 and gets incremented by 1 for each additional parameter.
      lvIndex - The parameter's local variable index in the current method, also known as slot. Starts at 0 for static methods, 1 otherwise. For each additional parameter, it gets incremented by 1, or by 2 if it's a double-wide primitive (long or double).
      srcName - The optional source name of the parameter.
      Returns:
      Whether the arg's content should be visited too.
      Throws:
      IOException

    • visitMethodVar

      boolean visitMethodVar(int lvtRowIndex, int lvIndex, int startOpIdx, int endOpIdx, @Nullable @Nullable String srcName) throws IOException
      Visit a variable.
      Parameters:
      lvtRowIndex - The variable's index in the method's LVT (local variable table). It is optional, so -1 can be passed instead. This is the case since LVTs themselves are optional debug information, see JVMS 4.7.13.
      lvIndex - The var's local variable index in the current method, also known as slot. For each additional variable, it gets incremented by 1, or by 2 if it's a double-wide primitive (long or double). The first variable starts at the last parameter's slot plus wideness.
      startOpIdx - Required for cases when the lvIndex alone doesn't uniquely identify a local variable. This is the case when variables get re-defined later on, in which case most decompilers opt to not re-define the existing var, but instead generate a new one (with both sharing the same lvIndex).
      endOpIdx - Counterpart to startOpIdx. Exclusive.
      srcName - The optional source name of the variable.
      Returns:
      Whether the var's content should be visited too.
      Throws:
      IOException

    • visitEnd

      default boolean visitEnd() throws IOException
      Finish the visitation pass.

      Implementors may throw an exception if a second pass is requested without the NEEDS_MULTIPLE_PASSES flag having been passed beforehand, but only if that behavior is documented.

      Returns:
      true if the visitation pass is final, false if it should be started over.
      Throws:
      IOException

    • visitDstName

      void visitDstName(MappedElementKind targetKind, int namespace, String name) throws IOException
      Destination name for the current element.
      Parameters:
      namespace - Namespace index (index into the dstNamespaces list in visitNamespaces(String, List)).
      name - Destination name.
      Throws:
      IOException

    • visitDstDesc

      default void visitDstDesc(MappedElementKind targetKind, int namespace, String desc) throws IOException
      Throws:
      IOException

    • visitElementContent

      default boolean visitElementContent(MappedElementKind targetKind) throws IOException
      Determine whether the element content (comment, sub-elements) should be visited.

      Called after visiting the target itself (e.g. visitClass for targetKind=class), its dst names and descs, but before any child elements or the comment.

      This is also a notification about all available dst names having been passed on.

      Returns:
      true if the contents are to be visited, false otherwise
      Throws:
      IOException

    • visitComment

      void visitComment(MappedElementKind targetKind, String comment) throws IOException
      Comment for the specified element (last content-visited or any parent).
      Parameters:
      comment - Comment as a potentially multi-line string.
      Throws:
      IOException