Package info java для чего она нужна

Файл 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:

./2861acc18324a156dd26284834d9bfc6.png

Итак, так же, как мы пишем 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 :

./4225cc001242e2a48d6bd583d5a7b51e.png

Опция 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, но и аннотаций для всего пакета . Кроме того, этот список вариантов использования может быть расширен в будущем .

Как всегда, код доступен на GitHub .

1. Обзор
2. Назначение package-info
3. Пакет документации
4. Аннотации пакетов
5. Как создать файл с информацией о пакете
6. Заключение

Пакет Java — Java package

A Пакет Java организует Java классы в пространства имен, предоставляя уникальное пространство имен для каждого содержащегося в нем типа. Классы в одном пакете могут обращаться к частным и защищенным членам пакета друг друга.

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

1 Использование пакетов

1.1 Документация Javadoc и аннотации для всего пакета
1.2 Безымянный пакет

Использование пакетов

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

пакет java.awt.event;

Чтобы использовать классы пакета внутри исходного файла Java, удобно импортировать классы из пакета с объявлением import . Следующее объявление

import java.awt.event. *;

импортирует все классы из пакета java.awt.event , а следующее объявление

import java.awt.event.ActionEvent;

импортирует из пакета только класс ActionEvent . После любого из этих объявлений импорта на класс ActionEvent можно ссылаться, используя его простое имя класса:

ActionEvent myEvent = new ActionEvent ();

Классы также можно использовать напрямую без объявления импорта, используя полное имя класса. Например,

java.awt.event.ActionEvent myEvent = new java.awt.event.ActionEvent ();

не требует предшествующего объявления импорта.

Пакетная документация Javadoc и аннотации

Документация, объясняющая пакет в целом, записывается как Javadoc в файле с именем `package-info.java`. Этот файл также является местом для аннотаций, которые будут использоваться во всех классах пакета. См. Спецификация языка Java.

Безымянный пакет

Если объявление пакета не используется, классы помещаются в безымянный пакет. Классы в безымянном пакете не могут быть импортированы классами в любом другом пакете. Официальный учебник по Java не рекомендует этого делать:

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

Защита доступа к пакету

Открытые члены и классы видны повсюду, а частные члены видны только в том же классе. Классы в пакете могут иметь доступ к классам и членам, объявленным с доступом по умолчанию (частный для пакета), а также к членам класса, объявленным с помощью модификатора доступа protected . Доступ по умолчанию (частный для пакета) применяется, если класс или член не были объявлены как public , protected или private . Напротив, классы в других пакетах не могут получить доступ к классам и членам, объявленным с доступом по умолчанию. Однако к членам класса, объявленным как protected , можно получить доступ из классов в том же пакете, а также из классов в других пакетах, которые являются подклассами объявленного класса.

Создание файлов JAR

Файлы JAR создаются с помощью утилиты командной строки jar. Команда

jar cf myPackage.jar *.class

сжимает все файлы.class в файл JAR myPackage.jar. Параметр «c» в командной строке указывает команде jar «создать новый архив». Параметр ‘f’ указывает ему создать файл. Имя файла ставится перед содержимым файла JAR.

Соглашения об именах пакетов

Пакеты обычно определяются с использованием иерархического шаблона именования , с некоторыми уровнями в иерархии, разделенными точками ( . , произносится как «точка»). Хотя пакеты, расположенные ниже в иерархии имен, часто называют «подпакетами» соответствующих пакетов выше в иерархии, между пакетами почти отсутствует семантическая связь. Спецификация языка Java устанавливает соглашения об именах пакетов, чтобы избежать возможности того, что два опубликованных пакета будут иметь одно и то же имя. Соглашения об именах описывают, как создавать уникальные имена пакетов, чтобы широко распространенные пакеты имели уникальные пространства имен. Это позволяет легко и автоматически устанавливать и каталогизировать пакеты по отдельности.

Как правило, имя пакета начинается с доменного имени верхнего уровня организации, затем домена организации, а затем любых поддоменов, перечисленных в обратном порядке. Затем организация может выбрать конкретное имя для своего пакета. Последующие компоненты имени пакета различаются в соответствии с внутренними соглашениями об именовании организации.

Например, если организация в Канаде под названием MySoft создает пакет для работы с дробями, называя пакет ca.mysoft. Fractionsотличает пакет фракций от другого аналогичного пакета, созданного другой компанией. Если немецкая компания MySoft также создает пакет фракций, но называет его de.mysoft.fractions, тогда классы в этих двух пакетах определяются в уникальном и отдельном пространстве имен.

Полные соглашения по устранению неоднозначности в именах пакетов и правила для именования пакетов, когда имя домена в Интернете не может использоваться напрямую в качестве имени пакета, описаны в разделе 7.7 Спецификации языка Java.

Основные пакеты в Java SE 8

java.lang	— базовая функциональность языка и основные типы
java.util	— коллекция структура данных классы
java. io	— файловые операции
java.math	— мультиточная арифметика
java.nio	— Неблокирующий ввод / вывод framework для Java
java.net	— сетевые операции, сокеты, поиск DNS.
java.security	— генерация ключей, шифрование и дешифрование
java.sql	— Java Database Connectivity (JDBC) для доступа к базам данных
java.awt	— базовая иерархия пакетов для собственных компонентов GUI
java. text	— предоставляет классы и интерфейсы для обработки текста, дат, чисел и сообщений способом, независимым от природы. l языков.
java.rmi	— предоставляет пакет RMI.
java.time	— основной API для дат, времени, моментов и продолжительности.
java.beans	— Пакет java.beans содержит классы и интерфейсы, связанные с компонентами JavaBeans.
java.applet	— этот пакет предоставляет классы и методы для создания апплетов и взаимодействия с ними.

Пакет java.lang доступен без использования оператора импорта.

Модули

В Java 9 «модули», своего рода набор пакетов, планируются как часть Project Jigsaw; они ранее назывались «суперпакетами» и изначально планировались для Java 7.

Модули будут описывать свои зависимости в объявлении модуля, которое будет помещено в файл с именем module-info.java в корне исходного кода модуля. файловая иерархия. JDK сможет проверить их как во время компиляции, так и во время выполнения. Сам JDK будет модульным для Java 9.

Ссылки

Внешние ссылки

Зачем нужен package-info?

Обычно, чтобы создать новый пакет, вы создаете папку с соответствующим названием, и во всех ее .java файлах добавляете в начале строчку с названием пакета, вида package full.dir.path; . Этого вполне достаточно для работы.

Однако, дополнительно вы можете добавить в пакет его объявление – файл package-info.java . Несмотря на то, что это .java-файл, это не объявление класса. В названии класса дефисы запрещены, так что неоднозначности не возникнет.

Минимальное содержимое файла package-info.java – всё та же строка package full.dir.path; . Такой файл не несет практической пользы. Есть две вещи, которые можно в него добавить, чтобы польза появилась.

Первое – документация пакета. Javadoc-комментарий будет использоваться генератором документации. Пример – описание пакета java.lang. Его исходник вы можете найти в файле java/lang/package-info.java .

Второе возможное применение – аннотации уровня пакета. Для этого аннотация должна иметь Target PACKAGE . Например, некоторые пакеты Spring Framework помечены аннотацией @NonNullApi .

Подробно объявления пакетов описаны в главе 7.4.1 спецификации.

Why is package-info.java useful?

When I run CheckStyle over my Java project it says Missing package-info.java file. for some classes, but not all of them. I can’t really figure out why this message appears only sometimes. Furthermore my project runs perfectly fine without the package-info.java. What does the package-info.java do? Do I really need it for my Java projects?

9,235 1 1 gold badge 29 29 silver badges 43 43 bronze badges
asked Feb 28, 2014 at 12:38
9,044 25 25 gold badges 67 67 silver badges 115 115 bronze badges
You can use them for documenting or annotating at the package level. See this question.
Feb 28, 2014 at 12:42

I’ve been a fan of package-info.java all this time but I wonder if a README.md is more suitable in 2018

Mar 5, 2018 at 20:15

@Sridhar-Sarnobat Besides package-info.java and README.md from Git, there is the possibility of Confluene possibly adding Jira tickets as well. That way also diagrams, workflows or videos may be added.

Mar 5, 2018 at 20:34
Did you know that you can also write other code in there too? Like classes etc. Weird!
Mar 29, 2018 at 8:10

Is package-info used only for documentation and package annotation? Does it something like package level import if classes? For eg if we import a class in package-info.java can use that class in other files of the package without explicitly importing the file in the said file?

Oct 5, 2022 at 8:09

5 Answers 5

It is used to generate javadocs for a package.

/** * Domain classes used to produce . * * These classes contain the . *
 * * @since 1.0 * @author somebody * @version 1.0 */ package com.domain;

Will generate package info for com.domain package:

answered Feb 28, 2014 at 12:46
3,546 1 1 gold badge 21 21 silver badges 28 28 bronze badges
sorry still not clear which part you refere to Example result is it the readme.md ?
Jun 11, 2018 at 19:49

It its actually used for more than generating javadocs. See baeldung.com/java-package-info#package-annotations.

Aug 16, 2022 at 21:26

Annotations

Another good reason to use package-info.java is to add default annotations for use by FindBugs. For instance, if you put this in your package-info file:

@DefaultAnnotation(NonNull.class) package com.my.package;

then when findbugs runs on the code in that package, all methods and fields are assumed to be non-null unless you annotate them with @CheckForNull . This is much nicer and more foolproof than requiring developers to add @NonNull annotations to each method and field.

314k 105 105 gold badges 870 870 silver badges 1186 1186 bronze badges
answered Dec 29, 2016 at 21:43
871 7 7 silver badges 7 7 bronze badges

Not only some findbugs annotations, but a lot of java annotations in common libraries have the java.lang.annotation.ElementType.PACKAGE type as one of the possible values of their own java.lang.annotation.Target annotation, e.g.:

com.google.gwt.core.client.js.JsNamespace com.querydsl.core.annotations.Config com.sun.xml.bind.XmlAccessorFactory groovy.transform.BaseScript java.lang.Deprecated javax.annotation.Generated javax.xml.bind.annotation.XmlAccessorOrder org.hibernate.annotations.TypeDef net.sf.ehcache.pool.sizeof.annotations.IgnoreSizeOf org.apache.hive.common.HiveVersionAnnotation org.apache.wicket.authroles.authorization.strategies.role.annotations.AuthorizeAction org.codehaus.commons.nullanalysis.NotNullByDefault org.eclipse.persistence.oxm.annotations.XmlNameTransformer org.glassfish.jersey.Beta org.jgroups.annotations.Experimental

This package-info.java file would be the file, where you can place such annotations (along with the javadoc).