Файл package-info.java
В этом руководстве мы поймем назначение package-info.java и его полезность. Проще говоря, package-info — это файл Java, который можно добавить в любой пакет Java .
2. Назначение package-info
В настоящее время файл package-info.java служит двум целям:
Помимо вышеупомянутого, варианты использования могут быть расширены по мере необходимости. В будущем, если потребуется добавить какую-либо функцию на уровне пакета, этот файл будет идеальным местом.
Давайте подробно рассмотрим текущие варианты использования.
3. Пакет документации
До версии Java 5 документация, относящаяся к пакету, помещалась в HTML-файл package.html . Это обычный файл HTML с комментариями Javadoc, размещенными внутри тега body .
Когда JDK 5 появился на сцене, package.html уступил место новому параметру package-info.java , который теперь предпочтительнее package.html .
Давайте посмотрим на пример документации пакета в файле package-info.java :
/** * This module is about impact of the final keyword on performance * * This module explores if there are any performance benefits from * using the final keyword in our code. This module examines the performance * implications of using final on a variable, method, and class level. * * * @since 1.0 * @author foreach * @version 1.1 */ package com.foreach.finalkeyword; Приведенный выше package-info.java сгенерирует Javadoc:
Итак, так же, как мы пишем Javadoc в других местах, мы можем поместить пакет Javadoc в исходный файл Java.
4. Аннотации пакетов
Предположим, нам нужно применить аннотацию ко всему пакету . В этом случае нам может прийти на помощь package-info.java .
Рассмотрим ситуацию, когда нам нужно объявить поля, параметры и возвращаемые значения ненулевыми по умолчанию. Мы можем достичь этой цели, просто включив аннотацию @NonNullApi для ненулевых параметров и возвращаемых значений, ` а также аннотацию @NonNullFields для ненулевых полей в наш файл package-info.java .`
@NonNullFields и @NonNullApi будут помечать поля, параметры и возвращаемые значения как ненулевые, если они явно не помечены как @Nullable :
@NonNullApi @NonNullFields package com.foreach.nullibility; import org.springframework.lang.NonNullApi; import org.springframework.lang.NonNullFields; Существуют различные аннотации, которые можно использовать на уровне пакета. Например, в проекте Hibernate у нас есть категория аннотаций , а в проекте JAXB также есть аннотации уровня пакета .
5. Как создать файл с информацией о пакете
Создать файл с информацией о пакете довольно просто: мы можем создать его вручную или обратиться за помощью в IDE для его создания.
В IntelliJ IDEA мы можем щелкнуть правой кнопкой мыши пакет и выбрать New->package-info.java :
Опция Eclipse New Java Package позволяет нам сгенерировать package-info.java :
Вышеупомянутый метод работает и для существующих пакетов. Выберите существующий пакет, выберите опцию New-> Package и отметьте опцию Create package-info.java .
Хорошей практикой всегда является обязательное включение package-info.java в правила кодирования наших проектов. В этом могут помочь такие инструменты, как Sonar или Checkstyle .
6. Заключение
Основное различие между использованием файлов HTML и Java заключается в том, что с файлом Java у нас есть дополнительная возможность использования аннотаций Java. Таким образом , java- файл с информацией о пакете является не только домом для пакета Javadocs, но и аннотаций для всего пакета . Кроме того, этот список вариантов использования может быть расширен в будущем .
Class Package
Represents metadata about a run-time package associated with a class loader. Metadata includes annotations, versioning, and sealing.
Annotations for the run-time package are read from package-info.class at the same code source as classes in the run-time package.
The set of classes that make up the run-time package may implement a particular specification. The specification title, version, and vendor (indicating the owner/maintainer of the specification) can be provided when the Package is defined. An application can ask if the Package is compatible with a particular specification version by using the Package.isCompatibleWith(String) method. In addition, information about the actual classes that make up the run-time package can be provided when the Package is defined. This information consists of an implementation title, version, and vendor (indicating the supplier of the classes).
A Package may be explicitly defined with the ClassLoader.definePackage(String, String, String, String, String, String, String, URL) method. The caller supplies the specification and implementation titles, versions, and vendors. The caller also indicates whether the package is sealed. If a Package is not explicitly defined for a run-time package when a class in that run-time package is defined, then a Package is automatically defined by the class’s defining class loader, as follows.
- The name of the package is derived from the binary names of the classes. Since classes in a named module must be in a named package, the derived name is never empty.
- The package is sealed with the module location as the code source, if known.
- The specification and implementation titles, versions, and vendors are unspecified.
- Any annotations on the package are read from package-info.class as specified above.
- The name of the package is either «» (for classes in an unnamed package) or derived from the binary names of the classes (for classes in a named package).
- The package is not sealed.
- The specification and implementation titles, versions, and vendors are unspecified.
- Any annotations on the package are read from package-info.class as specified above.
A Package can be obtained with the Package.getPackage(String) and ClassLoader.getDefinedPackage(String) methods. Every Package defined by a class loader can be obtained with the Package.getPackages() and ClassLoader.getDefinedPackages() methods.
Class Package
Represents metadata about a run-time package associated with a class loader. Metadata includes annotations, versioning, and sealing.
Annotations for the run-time package are read from package-info.class at the same code source as classes in the run-time package.
The set of classes that make up the run-time package may implement a particular specification. The specification title, version, and vendor (indicating the owner/maintainer of the specification) can be provided when the Package is defined. An application can ask if the Package is compatible with a particular specification version by using the Package.isCompatibleWith(String) method. In addition, information about the actual classes that make up the run-time package can be provided when the Package is defined. This information consists of an implementation title, version, and vendor (indicating the supplier of the classes).
A Package may be explicitly defined with the ClassLoader.definePackage(String, String, String, String, String, String, String, URL) method. The caller supplies the specification and implementation titles, versions, and vendors. The caller also indicates whether the package is sealed. If a Package is not explicitly defined for a run-time package when a class in that run-time package is defined, then a Package is automatically defined by the class’s defining class loader, as follows.
- The name of the package is derived from the binary names of the classes. Since classes in a named module must be in a named package, the derived name is never empty.
- The package is sealed with the module location as the code source, if known.
- The specification and implementation titles, versions, and vendors are unspecified.
- Any annotations on the package are read from package-info.class as specified above.
- The name of the package is either «» (for classes in an unnamed package) or derived from the binary names of the classes (for classes in a named package).
- The package is not sealed.
- The specification and implementation titles, versions, and vendors are unspecified.
- Any annotations on the package are read from package-info.class as specified above.
A Package can be obtained with the Package.getPackage(String) and ClassLoader.getDefinedPackage(String) methods. Every Package defined by a class loader can be obtained with the Package.getPackages() and ClassLoader.getDefinedPackages() methods.