Skip to content

Latest commit

 

History

History
145 lines (102 loc) · 5.83 KB

README.adoc

File metadata and controls

145 lines (102 loc) · 5.83 KB
Raw

Refactobot - Automate code reorganizations in large Java codebases.

Build Status Coverage Status License

Moving or renaming individual classes is a no-brainer in today’s IDEs. But what if you want to rename thousands of classes in hundreds of packages? What if you want to reorganize a large codebase into a new module structure?

Refactobot takes a codebase and some transformations, and applies them to the codebase fully automatically, adapting all references. Transformations may include changing class and package names and moving classes between packages and modules (in a multi-module build). Transformations are programmed in a very simple Kotlin DSL.

Features

Automated and fast

Transforming a codebase just means running a script, and processes thousands of classes within seconds. This means you can reliably reproduce the transformation as many times as needed, as the codebase is still undergoing changes.

Fully preserves formatting, whitespace, and comments

Refactobot only touches references to classes, when they are renamed or moved. All other code and formatting remains exactly as it is.

Declarative and powerful transformation language

Transformations are expressed declaratively in a Kotlin-based DSL. Be it simple move commands, regex-based matching, or custom scripting (in Kotlin) — refactoring scripts usually are just a few lines of simple code.

Structure101 class map import

If you use Structure 101 for planning your refactoring, you can directly export a class map and apply it using Refactobot. If you have a class map from some other source, it should be simple to load.

Battle-tested

Refactobot was used successfully to establish a completely revamped module structure for a 200kloc codebase, which involved moving almost every class to a new place, and introduce uniform naming and packaging conventions.

Hackable

Since every codebase is different, some adaptation may be needed in some cases. Refactobot is easily extensible due to its modular design. On the other hand, do not expect a polished product-like experience. This is for developers!

Usage Examples

Refactobot has no command line interface and is simply invoked from Kotlin code via its simple API. You can find a working test case in FullIntegrationTest, which you can use as a start and adapt to your use case. Below are some examples that illustrate the DSL.

1) Rename some classes, based on regular expressions

If you want to change some class naming schemes, you can use regular expressions on the class name:

val refactobot = Refactobot.configure { // Create and configure the refactobot instance.

    refactor { // In this block, we specify the transformations to apply to the codebase.
        renameFile("""(.*)DaoBean\.java""" to "$1DaoImpl.java")
    }
}

refactobot.run("/path/to/codebase") // The actual invocation of the tool.

2) Fix the base package name

This example shows how you can express your transformation in simple Kotlin code, which operates on the file name and path:

val oldBasePackage = "org/example/legacybasepackage/"
val newBasePackage = "org/example/newbasepackage/"

val refactobot = Refactobot.configure {

    refactor {

        if (this.path.startsWith(oldBasePackage)) {
            this.path = newBasePackage + this.path.removePrefix(oldBasePackage)
        }
    }
}

refactobot.run("/path/to/codebase")

3) Apply a mapping between class names

If you have a map with fully qualified class names, you can use it like this:

val refactobot = Refactobot.configure {

    refactor {
        applyClassMap(mapOf(
            "org.example.codebase.SomeClass" to "org.example.codebase.NewClassName",
            "org.example.codebase.SomeOtherClass" to "org.example.codebase.ShinyNewOtherClassName"
        ))
    }
}

refactobot.run("/path/to/codebase")

Alternatively, if you developed that map with Structure 101, you can import the XML file exported from there:

val refactobot = Refactobot.configure {

    refactor {
        applyClassMap(Structure101ClassmapReader.readClassmapXml("classmap.xml"))
    }
}

refactobot.run("/path/to/codebase")

Assumptions and Limitations

A tool cannot do everything by magic, so there are a few limitations that you should be aware of:

Build-tool-agnostic

Refactobot understands Java, but it does not know (or care about) your build tool, except when discovering module names and directories in a codebase. It was used on a multimodule Maven project, but can equally handle Gradle and other build tools. Of course this means that you must manually handle any necessary changes to your build files, e.g., when module dependencies change.

Some sane Java conventions

Some conventions are industry standard in the Java community, although they are not enforced by the Java compiler. Refactobot relies on these conventions nevertheless. If your codebase violates them, you may think about fixing this first. When detecting such a case, Refactobot tries to give helpful error messages. In particular, we require that:

  • The directory structure reflects the package structure, i.e., files under foo/bar belong to package foo.bar.

  • Each file contains exactly one top-level type (class, interface, enum, …​).

  • Type names start with capital letters. Package names start with small letters.

No *-imports

Currently, *-imports are not supported. I found it easy to work around this, since many IDEs now support expanding *-imports automatically.