• Вызов компилятора из кода программы: Java Compiler API (JSR 199)
  

• Встраиваемые обработчики аннотаций: Pluggable Annotation Processing API (JSR 269)
  

• Работаем с абстрактным синтаксическим деревом: Compiler Tree API

В этой статье мы расскажем об этих возможностях и продемонстрируем их на примере небольшого приложения, позволяющего проверить набор правил по тому как надо писать Java код в заданном наборе входных файлов. Наше приложение не просто печатает сообщения о нарушении правил, но также и указывает местонахождение некорректного фрагмента кода. В качестве правила для проверки мы используем следующее:

• класс, переопределяющий equals(), должен также переопределять hashcode() (с правильной сигнатурой метода)

public class TestClass implements Serializable {
 int num;
 
 @Override
  public boolean equals(Object obj) {
        if (this == obj)
                return true;
        if ((obj == null) || (obj.getClass() != this.getClass()))
                return false;
        TestClass test = (TestClass) obj;
        return num == test.num;
  }
}
   

Вызов компилятора из кода программы: Java Compiler API

Все знают как использовать javac для компиляции исходного кода на Java в набор .class файлов. Зачем нужен API для компилятора? Ответ прост. Возможность программного вызова компилятора позволяет использовать компилятор в Ваших собственных программах и библиотеках на Java, то есть компиляция может быть одним из сервисов уровня приложения. Для примера, вот пара типовых сценариев применения:

• Программный интерфейс к компилятору позволяет серверам приложений (GlassFish и т.п.) минимизировать время развертывания приложений, избегая, например, необходимости использовать внешний компилятор для компиляции исходного кода сервлета, который был сгененриров из JSP страницы.
  

• Инструменты разработки, такие как интегрированные среды (Netbeans и т.п.), анализаторы кода (FindBugs и т.п.), системы управления сборкой проекта (ant, и другие) могут вызывать компилятор напрямую и значительно снизить временные затраты на компиляцию.
  

Классы, предоставляющие доступ к компилятору, находятся в пакете javax.tools. Класс ToolProvider позволяет получить экземпляр объекта реализующего интерфейс JavaCompiler с помощью метода getSystemJavaCompiler().  Экземпляр компилятора позволяет создавать задания на компиляцию, которые, собственно, и выполняют компиляцию. Набор файлов для компиляции передается через параметры задачи на компиляцию. Для этого используется абстракция файлового менеджера, JavaFileManager, позволяющая получать исходный код из различных источников - файловой системы, базы данных, оперативной памяти и т.д. В нашем примере мы воспользуемся StandardFileManager, реализацию файлового менеджера основанную на java.io.File. Получить экземпляр стандартного файлового менеджера можно с помощью метода getStandardFileManager() у JavaCompiler. 

Следующий фрагмент кода демонстрирует эти шаги:

//Получаем экземпляр JavaCompiler
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
 
//Получаем стандартный файловый менеджер
StandardJavaFileManager fileManager = compiler.
        getStandardFileManager(null, null, null);
        
//Получаем список файлов для компиляции
//(нам нужен единственный файл, TestClass.java)
Iterable<? extends JavaFileObject> compilationUnits1 = 
        fileManager.getJavaFileObjectsFromFiles("TestClass.java");
   

Методу getStandardFileManager() можно передать объект для получения диагностических сообщений о возникших "не фатальных" ошибках. В нашем случае мы игнорируем диагностические сообщения и поэтому передаем null. За подробной информацией о других параметрах рекомендуес заглянуть в Java 6 API. 

В результате работы метода getJavaFileObjectsfromFiles() мы получаем набор объектов типа JavaFileObject, которые соответствуют входным файлам с исходным кодом.

Следующий шаг - создать задание на компиляцию. Для этого воспользуемся методом getTask() у JavaCompiler. Это еще не запуск самой компиляции, для запуска надо вызвать метод call() у созданного объекта CompilationTask. Следующий фрагмент кода демонстрирует создание задания и запуск компиляции:

//Создаем задание
CompilationTask task = compiler.getTask(null, fileManager, null,
                                        null, null, compilationUnits1);
                                        
//Запускаем процесс компиляции
task.call();
   

Если компиляция завершится без ошибок, то в директории появится файл TestClass.class.

Встраиваемые обработчики аннотаций: Pluggable Annotation Processing API

В Java SE 5.0 появилась поддержка для добавления и обработки метаинформации в ввиде аннотаций для элементов языка, таких как классы, поля, методы, и т.д. Аннотации обычно используются внешними инструментами или средой исполнения для разных полезных задач - контроль над поведением приложения, генерация кода, и т.п. Обработка аннотаций возможно как на этапе компиляции, так и на этапе исполнения аннотированного кода. 

Обработчики аннотаций - это вспомогательные модули, которые динамически встраиваются в компилятор для анализа исходного кода и обработки аннотаций в этом коде. Обработчики аннотаций могут использовать метаинформацию для выполнения множества разных задач, например:

• Аннотации можно использовать для генерации файлов дескрипторов для описания схемы развертывания приложения, таких как persistence.xml или ejb-jar.xml, используемых в технологии EJB.
  
  

• Обработчики аннотаций могут использовать метаинформацию для генерации кода. Например, обработчик может сгенерировать интерфейсы Home и Remote для аннотированной компоненты EJB.
  
  

• Аннотации можно использовать для проверки корректности кода или развертываемых объектов.

В Java 5.0 для обработки аннотаций можно воспользоваться специальной утилитой apt (Annotation Processing Tool) и связанным с ним программным интерфейсом на основе reflection (com.sun.mirror.*). Утилита APT выполняет подходящие обработчики аннотаций на заданном наборе фвйлов с кодом на Java. Программный интерфейс предоставляет доступ к информации об аннотациях на этапе компиляции в режиме только для чтения. Самый главный минус apt - это не стандартная утилита, то есть это решение специфичное для
JDK от Sun Microsystems.

В Java SE 6 появилась новая возможность - встраиваемые обработчики аннотаций (Pluggable Annotation Processing), позволяющая стандартным способом создавать свои обработчики аннотаций. Обработчики могут быть добавлены в javac динамически и могут работать с о всем множеством аннотаций, которые используются во входных файлах.

Программный интерфейс разделен на две части: определение и взаимодействие с обработчиками событий (пакет javax.annotation.processing) и моделирование языка Java (пакет javax.lang.model).

Пишем свой обработчик аннотаций

В этом разделе мы объясним как написать свой обработчик аннотаций и как добавить его в задание на компиляцию. Наш обработчик аннотаций расширяет AbstractProcessor (реализующий интерфейс Processor) и предоставляет свою реализацию метода process().

Класс обработчика содержит две аннотации на уровне класа - @SupportedAnnotationTypes и @SupportedSourceVersion. Аннотация SupportedSourceVersion используется для указания версии исходного кода, которую поддерживает обработчик аннотаций. Аннотация SupportedAnnotationTypes используется для задания списка аннотаций, в которых заинтересован этот обработчик. Например, @SupportedAnnotationTypes ("javax.persistence.*") означает, что обработчик заинтересован в обработке аннотаций связанных с Java Persistence API.

Отметим, что если список аннотаций для обработки задан как @SupportedAnnotationTypes("*"), то обработчик аннотаций будет вызван даже если в исходном коде аннотации не используются. Такой подход позволяет возспользоваться интерфейсами для моделирования и работы с абстрактным синтаксическим деревом для обработки неразмеченного исходного кода. Используя эти программные интерфесы можно получить много полезной информации о модификаторах, полях, методах и т.д.

Вот пример кода обработчика аннотаций:

@SupportedSourceVersion(SourceVersion.RELEASE_6)
@SupportedAnnotationTypes("*")
public class CodeAnalyzerProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set<? extends TypeElement> annotations,
            RoundEnvironment roundEnvironment) {
        for (Element e : roundEnvironment.getRootElements()) {
                System.out.println("Element is "+ e.getSimpleName());
                // Вставьте сюда код для обработки коневых элементов дерева
        }
        return true;
    }
}
 
   

Отбор обработчиков аннотаций для вызова происходит на основе того, какие аннотации есть в коде, какие обработчики доступны и какие типы аннотаций они поддерживают. Обработка аннотаций может быть многопроходной. Например, на первом проходе обрабатывается исходный код, во время второго прохода происходит обработка результата полученного после первого прохода, и т.д.

Реализация обработчика аннотаций должна перегружать метод process() у AbstractProcessor, который получает два аргумента:

1. Множество аннотаций (TypeElements) найденных в исходном коде.
2. Информацию о текущем проходе по обработке аннотаций, представленную объектом RoundEnvironment.

Если обработчик выполнил обработку аннотаций данного типа, то его метод  process() должен вернуть true - это предотвратит вызов других обработчиков для этого множества аннотаций. Иначе, если process() вернет false, будет вызван следующий подходящий обработчик (если он есть). 

Добавляем обработчик аннотаций

Реализовав свой обработчик аннотаций, его необходимо встроить в процесс компиляции. Обработчик может вызываться утилитой командной строки javac или через программный интерфейс к компилятору.

Утилита javac позволяет указать дополнительные обработчики, используя опцию --processor, которой нужно передать полное имя обработчика. Вот пример вызова javac c указанием обработчика аннотаций:

javac -processor demo.codeanalyzer.CodeAnalyzerProcessor TestClass.java
   

Здесь CodeAnalyzerProcessor - это обработчик аннотаций и TestClass - это входной файл. javac будет искать класс CodeAnalyzerProcessor в текущем пути поиска классов (classpath).

Ниже приведен модифицированный фрагмент кода, вызывающий компилятор с помощью API, который использует наш обработчик аннотаций. Для добавления одного или нескольких обработчиков аннотаций в задание на компиляцию можно воспользоваться методом  setProcessors() у класса CompilationTask. Добавлять обработчики необходимо до того как вы вызвали метод call(). Обратите внимание, что обработка аннотаций происходит до фактической компиляции. Но если код компилируется с ошибками, то и обработка аннотаций не будет произведена.

CompilationTask task = compiler.getTask(null, fileManager, null,
                                        null, null, compilationUnits1);
                                        
//Создаем список для хранения обработчиков аннотаций
LinkedList<AbstractProcessor> processors = new LinkedList<AbstractProcessor>();
 
//Запослняем список нашими обработчиками
processors.add(new CodeAnalyzerProcessor());
 
//Добавляем обработчики в задание на компиляцию
task.setProcessors(processors);
 
//Запускаем компиляцию
task.call();
   

Если Вы запустите этот фрагмент кода, то при обработке файла TestClass.java сработает обработчик аннотаций и напечатает "TestClass."

Работаем с абстрактным синтаксическим деревом: Compiler Tree API

Абстрактное синтаксическое дерево (AST) - это представление кода на Java в виде древовидной структуры, узлами которой являются конструкции языка программирования Java или поддеревья (Tree) из них состоящие. Например, классу Java соответствует ClassTree, декларация метода представляется с помощью MethodTree, декларация переменной - VariableTree, аннотации - AnnotationTree, и т.д. Доступ к этой структуре возможен только в режиме чтения.

Программный интерфейс для работы с абстрактным синтаксическим деревом (AST) предоставляет ряд вспомогательных классов для выполнения операций над деревом - такие как, например, TreeVisitor и TreeScanner. TreeVisitor удобен для проведения более глубокого анализа исходного кода - он позволяет обойти все узлы дерева и собрать необходимую информацию о полях, методах, аннотациях и других эллементах классов. Реализации TreeVisitor основаны на едином шаблоне - при посещении узла дерева вызывается метод типа visitX(), наиболее подходящий типу посещенного узла (например, visitClass() или visitMethod()). 

public class CodeAnalyzerTreeVisitor extends TreePathScanner<Object, Trees>  {
    @Override
    public Object visitClass(ClassTree classTree, Trees trees) {
        ---- ваш код ----
        return super.visitClass(classTree, trees);
    }
    @Override
    public Object visitMethod(MethodTree methodTree, Trees trees) {
        ---- ваш код ----
        return super.visitMethod(methodTree, trees);
    }
}
   

Методы visitX() получают два аргумента - дерево, соответствующее текущему узлу (с типом ClassTree для узла типа класс, MethodTree для узла типа метод и т.п.), и объекта типа Trees. Класс Trees предоставляет набор вспомогательных методов для получения информации о путях в дереве и выступает в качестве посредника между JSR 269 и Compiler Tree API. 

В нашем примере есть только один корневой элемент, который соответствует самом классу TreeClass:

CodeAnalyzerTreeVisitor visitor = new CodeAnalyzerTreeVisitor();
 
@Override
public void init(ProcessingEnvironment pe) {
        super.init(pe);
        trees = Trees.instance(pe);
}
for (Element e : roundEnvironment.getRootElements()) {
        TreePath tp = trees.getPath(e);
        //запускаем обход
        visitor.scan(tp, trees);
}
   

@Override
public Object visitClass(ClassTree classTree, Trees trees) {
         //Сохраняем информацию о посещенном классе в модель
         JavaClassInfo clazzInfo = new JavaClassInfo();
 
        //Получаем путь к текущему узлу
        TreePath path = getCurrentPath();
 
        //Получем описание типа элемента, который соответствует этому классу
        TypeElement e = (TypeElement) trees.getElement(path);
 
        //Запоминаем полное имя класса в модели
        clazzInfo.setName(e.getQualifiedName().toString());
 
        //Запоминаем информацию о предках
        clazzInfo.setNameOfSuperClass(e.getSuperclass().toString());
 
        //Запоминаем информацию о реализованных интерфейсах
        for (TypeMirror mirror : e.getInterfaces()) {
                clazzInfo.addNameOfInterface(mirror.toString());
        }
        return super.visitClass(classTree, trees);
  }
   

Класс JavaClassInfo, который здесь используется, - это класс модели, где мы храним собранную информацию об анализируемом коде. После выполнения обхода дерева с таким методом visitClass() в модели будет собрана информация о полном имени класса, имени его класса предка, реализованных интерфейсах, и т.д. Эта информация используется далее для проверки анализируемого кода.

Задаем информацию о месте в исходном коде

Про показали как получать информацию об элементах дерава AST и сохранять ее в модели класса, метода или поля. С помощью этой информации можно проверить соблюдаются ли соглашения по написанию кода, соответствует ли код спецификации, и т.п.
Это здорово, но как сообщить о найденных ошибках пользователям, так чтобы они смогли их легко исправить? Необходимо сообщать пользователю о конкретном месте в коде, где обнаружена ошибка.

Информация о позициях всех узлов дерева AST доступна с помощью объекта SourcePositions. Объект предоставляет информацию о начале и конце блока кода в исходном файле, который соответствует данному элементу дерева - ClassTree, MethodTree, FieldTree, и т.п. Позиция определяется как отступ в числе символов от начала файла, первый симвой имеет отступ 0.

Следующий фрагмент кода демострирует применение этих фозможностей, получая информацию о местонахождении заданного объекта Tree в компилируемом файле:

public static LocationInfo getLocationInfo(Trees trees, 
                                                TreePath path, Tree tree) {
        LocationInfo locationInfo = new LocationInfo();
        SourcePositions sourcePosition = trees.getSourcePositions();
        long startPosition = sourcePosition.
                        getStartPosition(path.getCompilationUnit(), tree);
        locationInfo.setStartOffset((int) startPosition);
        return locationInfo;
}
   

Однако, если мы хотим указать положение более детально - например, указать точно на имя класса или метода, то описанного метода недостаточно. Но можно поискать в анализируемом файле, как в строке. Для доступа к текстовому содержимому анализируемого файла можно воспользоваться JavaFileObject, как в следующем примере:

//Get the compilation unit tree from the tree path
CompilationUnitTree compileTree = treePath.getCompilationUnit();
 
//Get the java source file which is being processed
JavaFileObject file = compileTree.getSourceFile();
 
// Extract the char content of the file into a string
String javaFile = file.getCharContent(true).toString();
 
//Convert the java file content to a  character buffer
CharBuffer charBuffer = CharBuffer.wrap (javaFile.toCharArray());
   

Следующий фрагмент кода определяет позиции имен классов в исходном коде с помощью java.util.regex.Pattern и java.util.regex.Matcher. Matcher производит поиск первого вхождения токена совпадающего с именем класса в символьном буффере (построенном с помощью java.nio.CharBuffer), начав с первола символа блока соответствующего узлу класса в дереве AST.

LocationInfo clazzNameLoc = (LocationInfo) clazzInfo.getLocationInfo();
 int startIndex = clazzNameLoc.getStartOffset();
 int endIndex = -1;
 if (startIndex >= 0) {
   String strToSearch = buffer.subSequence(startIndex, buffer.length()).toString();
   Pattern p = Pattern.compile(clazzName);
   Matcher matcher = p.matcher(strToSearch);
   matcher.find();
   startIndex = matcher.start() + startIndex;
   endIndex = startIndex + clazzName.length();
  } 
 clazzNameLoc.setStartOffset(startIndex);
 clazzNameLoc.setEndOffset(endIndex);
 clazzNameLoc.setLineNumber(compileTree.getLineMap().getLineNumber(startIndex));
   

Еще один полезный объект в API для работы с абстрактным синтаксическим деревом - LineMap. Этот класс предоставляет возможность связывать позиции в виде отступов и номера строк. Для получения номера строки по отступу можно воспользоваться методом getLineMap() у CompilationUnitTree.

Проверяем соблюдение правил в исходном коде

Теперь, когда мы знаем как получить необходимую информацию из дерева AST, нам осталось реализовать собственно проверку на соблюдение интересующих нас правил в анализаруемом коде. Наша правила хранятся в XML файле, их обработкой занимается специализированный класс RuleEngine. Этот класс читает правила из XML файла и проверяет правила одно за другим. Если входной файл не удовлетворяет правилу, то возвращается список объектов типа ErrorDescription, которые содержат информацию об ошибке и местонахождении ошибки в исходном коде.

ClassFile clazzInfo = ClassModelMap.getInstance().
                getClassInfo(className);
for (JavaCodeRule rule : getRules()) {
        //проверяем правила по очереди
        Collection<ErrorDescription> problems = rule.execute(clazzInfo);
        if (problems != null) {
                problemsFound.addAll(problems);
        }
}
   

Каждое правило реализовано в виде отдельного класса, информация о класса для проверки передается классу-правилу в виде модели. Реализация класса-правила для правила OverrideEqualsHashCode, то есть "класс, переопределяющий equals(), должен также переопределять hashcode() (с правильной сигнатурой метода)",приведена ниже.

Проверка состоит в переборе методов и верификации соблюдения правила для equals() и hashCode(). В нашем тестовом классе TestClass, метод hashcode() отсутствует, хотя есть метод equals(). Поэтому правило вернет ErrorDescription с сообщением об ошибке и информацией о ее местонахождении.

public class OverrideEqualsHashCode extends JavaClassRule {
    @Override
    protected Collection<ErrorDescription> apply(ClassFile clazzInfo) {
        boolean hasEquals = false;
        boolean hasHashCode = false;
        Location errorLoc = null;
        for (Method method : clazzInfo.getMethods()) {
            String methodName = method.getName();
            ArrayList paramList = (ArrayList) method.getParameters();
            if ("equals".equals(methodName) && paramList.size() == 1) {
                if ("java.lang.Object".equals(paramList.get(0))) {
                    hasEquals = true;
                    errorLoc = method.getLocationInfo();
                }
            } else if ("hashCode".equals(methodName) &&
                method.getParameters().size() == 0) {
                hasHashCode = true;
            }
        }
        if (hasEquals) {
            if (hasHashCode) {
                return null;
            } else {
                StringBuffer errrMsg = new StringBuffer();
                errrMsg.append(CodeAnalyzerUtil.
                                getSimpleNameFromQualifiedName(clazzInfo.getName()));
                errrMsg.append(" : The class that overrides 
                                        equals() should ");
                errrMsg.append("override hashcode()");
                Collection<ErrorDescription> errorList = new 
                                                ArrayList<ErrorDescription>();
                errorList.add(setErrorDetails(errrMsg.toString(), 
                                                        errorLoc));
                return errorList;
            }
        }
        return null;
    }
}
   

Запуск демонстрационного примера

Готовый к запуску вариант демонстрационного примера можно скачать по ссылке из раздела Ресурсы. Сохраните файл в локальную директорию и используйте следующую команду для запуска приложения:

java -classpath <JAVA_HOME>\lib\tools.jar;.; demo.codeanalyzer.main.Main <список входных файлов для проверки разделенных запятой>
   

Заключение

В этой статье мы рассказали о некоторых новых возможностях Java SE 6, позволяющих программно вызывать компилятор, производить синтаксический разбор и анализировать исходный код с помощью вставки аннотаций и анализа синтаксического дерева. Использование стандартного API позволяет писать код, который можно использовать в разных окружениях.

Мы конечно же не смогли рассказать о всех возможностях нового API в этой статье, рекомендуем ознакомиться с документацией, чтобы лучше представлять, что Вы можете с помощью него сделать.

Ресурсы

• Исходный код примеров из этой статьи
• Откомпилированная версия демонстрационного приложения (JAR)
  
• JSR-199: Java Compiler API
• JSR 269: Pluggable Annotation Processing API
• Java Compiler Tree API
• Статья о Java Compiler API от Artima (англ.)
  
• Блог Sahoo о разработке плагина для javac используя JSR 269 (англ.)