Глава 7. Пакеты и модули

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

TypeName должно быть каноническим именем класса или интерфейса (§6.7).

Класс или интерфейс должен быть членом именованного пакета или членом класса или интерфейса, чье внешнее лексически охватывающее объявление класса или интерфейса (§8.1.3) является членом именованного пакета, в противном случае возникает ошибка компиляции.

Если указанный класс или интерфейс недоступен (§6.6), возникает ошибка компиляции.

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

Если класс или интерфейс, импортируемый объявлением импорта одного типа, объявлен как верхнеуровневый класс или интерфейс (§7.6) в единице компиляции, содержащей объявление import, то объявление import игнорируется.

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

Если единица компиляции содержит и объявление импорта одного типа, импортирующее класс или интерфейс с простым именем x, и объявление импорта одного статического члена (§7.5.3), импортирующее класс или интерфейс с простым именем x, возникает ошибка компиляции, за исключением случаев, когда оба класса или интерфейса одинаковы, в этом случае дублирующее объявление игнорируется.

import java.util.Vector;

import java.util.Vector;
class Vector { Object[] vec; }

import java.util.Vector;
import myVector.Vector;

package myVector;
public class Vector { Object[] vec; }

import java.util;
class Test { util.Random generator; }
  // incorrect: compile-time error

package Vector;
public class Mosquito { int capacity; }

package strange;
import java.util.Vector;
import Vector.Mosquito;
class Test {
    public static void main(String[] args) {
        System.out.println(new Vector().getClass());
        System.out.println(new Mosquito().getClass());
    }
}

class java.util.Vector
class Vector.Mosquito

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

ИмяПакетИлиТип должен представлять собой каноническое имя (§6.7) пакета, класса или интерфейса.

Если ИмяПакетИлиТип обозначает класс или интерфейс (§6.5.4), то класс или интерфейс должен быть членом именованного пакета, или членом класса или интерфейса, внешний лексически охватывающий класс или интерфейс объявления (§8.1.3) является членом именованного пакета, в противном случае возникает ошибка компиляции.

Если именованный пакет не виден текущему модулю (§7.4.3), или именованный класс или интерфейс недоступен (§6.6), то возникает ошибка компиляции.

Не является ошибкой компиляции именование либо java.lang, либо именованного пакета текущей единицы компиляции в объявлении импорта типов по требованию. В таких случаях объявление импорта типов по требованию игнорируется.

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

Если единица компиляции содержит как объявление импорта типов по требованию, так и объявление статического импорта по требованию (§7.5.4), которые имеют одинаковый класс или интерфейс, то эффект такой, как если бы static члены-классы и члены-интерфейсы этого класса или интерфейса (§8.5, §9.5) были импортированы только один раз.

import java.util.*;

Объявление одиночного статического импорта импортирует все доступные static члены с заданным простым именем из класса или интерфейса. Это делает эти static члены доступными под их простым именем в модуле, классе и интерфейсах единицы компиляции, в которой появляется объявление одиночного статического импорта.

ИмяТип должен представлять собой каноническое имя (§6.7) класса или интерфейса.

Класс или интерфейс должен быть членом именованного пакета, или членом класса или интерфейса, внешний лексически охватывающий класс или интерфейс объявления (§8.1.3) является членом именованного пакета, в противном случае возникает ошибка компиляции.

Если именованный класс или интерфейс недоступен (§6.6), то возникает ошибка компиляции.

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

Допустимо, что одно объявление одиночного статического импорта импортирует несколько полей, классов или интерфейсов с одинаковым именем или несколько методов с одинаковым именем и сигнатурой. Это происходит, когда именованный класс или интерфейс наследует несколько полей, вложенных классов, вложенных интерфейсов или методов, все с одинаковым именем, от своих супертипов.

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

Если объявление одиночного статического импорта импортирует класс или интерфейс, простое имя которого x, а единица компиляции также объявляет класс или интерфейс верхнего уровня (§7.6), простое имя которого x, возникает ошибка компиляции.

Если единица компиляции содержит как объявление одиночного статического импорта, импортирующего класс или интерфейс, простое имя которого x, так и объявление одиночного импорта типа (§7.5.1), импортирующего класс или интерфейс, простое имя которого x, то возникает ошибка компиляции, если только два класса или интерфейса не являются одинаковыми, в этом случае дублирующее объявление игнорируется.

Объявление статического импорта по требованию позволяет импортировать все доступные static члены именованного класса или интерфейса по мере необходимости.

ИмяТип должен представлять собой каноническое имя (§6.7) класса или интерфейса.

Класс или интерфейс должен быть членом именованного пакета, или членом класса или интерфейса, внешний лексически охватывающий класс или интерфейс объявления (§8.1.3) является членом именованного пакета, в противном случае возникает ошибка компиляции.

Если именованный класс или интерфейс недоступен (§6.6), то возникает ошибка компиляции.

Два или более объявлений статического импорта по требованию в одной единице компиляции могут именовать один и тот же класс или интерфейс; эффект такой, как если бы было ровно одно такое объявление.

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

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

Если единица компиляции содержит как объявление статического импорта по требованию, так и объявление импорта типов по требованию (§7.5.2), которые имеют одинаковый класс или интерфейс, то эффект такой, как если бы static члены-классы и члены-интерфейсы этого класса или интерфейса (§8.5, §9.5) были импортированы только один раз.

Директива requires указывает имя модуля, от которого текущий модуль зависит.

Директива requires не должна появляться в объявлении модуля java.base, иначе произойдёт ошибка времени компиляции, так как это исходный модуль и у него нет зависимостей (§8.1.4).

Если объявление модуля не выражает зависимость от модуля java.base, и сам модуль не является java.base, то модуль неявно зависит от модуля java.base.

Ключевое слово requires может быть дополнено модификатором transitive. Это вызывает неявную зависимость любого модуля, который requires текущий модуль, от модуля, указанного в директиве requires transitive.

Ключевое слово requires может быть дополнено модификатором static. Это означает, что зависимость, обязательная на стадии компиляции, является необязательной во время выполнения.

Ошибка времени компиляции, если один и тот же модификатор появляется более одного раза после ключевого слова requires.

Если объявление модуля выражает зависимость от модуля java.base, и сам модуль не является java.base, то ошибкой времени компиляции является наличие модификатора после ключевого слова requires.

Ошибка времени компиляции, если более одной директивы requires в объявлении модуля указывает одно и то же имя модуля.

Ошибка времени компиляции, если разрешение, как описано в спецификации пакета java.lang.module, с текущим модулем в качестве единственного корневого модуля, завершается ошибкой по любой из причин, описанных в спецификации пакета java.lang.module.

Например, если директива requires указывает на неопределяемый модуль, или если текущий модуль непосредственно или косвенно выражает зависимость от самого себя.

Если разрешение успешно, то его результат определяет модули, которые считывает текущий модуль. Модули, считанные текущим модулем, определяют, какие обычные единицы компиляции видны текущему модулю (§7.3). Типы, объявленные в этих обычных единицах компиляции (и только в этих обычных единицах компиляции), могут быть доступны коду в текущем модуле (§6.6).

Платформа Java SE различает именованные модули, которые явно объявлены (то есть с помощью объявления модуля), и именованные модули, которые неявно объявлены (то есть автоматические модули). Однако язык программирования Java не различает их: директивы requires относятся к именованным модулям независимо от того, явно они объявлены или неявно.

Хотя автоматические модули удобны для миграции, они ненадежны в том смысле, что их имена и экспортированные пакеты могут измениться, когда их авторы преобразуют их в явно объявленные модули. Компилятор Java рекомендуется выдавать предупреждение, если директива requires относится к автоматическому модулю. Особенно сильное предупреждение рекомендуется, если модификатор transitive появляется в директиве.

module m.A {
    requires m.B;
}

module m.B {
    requires transitive m.C;
}

module m.C {
    requires transitive m.D;
}

module m.D {
    exports p;
}

package p;
public class Point {}

package client;
import p.Point;
public class Test {
    public static void main(String[] args) {
        System.out.println(new Point());
    }
}

javac --module-source-path . -d . --module m.D
javac --module-source-path . -d . --module m.C
javac --module-source-path . -d . --module m.B
javac --module-source-path . -d . --module m.A

java --module-path . --module m.A/client.Test

Директива exports указывает имя пакета, который должен быть экспортирован текущим модулем. Для кода в других модулях это предоставляет доступ во время компиляции и выполнения к типам public и protected в пакете, а также к членам public и protected этих типов (§6.6). Это также предоставляет рефлексивный доступ к этим типам и членам для кода в других модулях.

Директива opens указывает имя пакета, который должен быть открыт текущим модулем. Для кода в других модулях это предоставляет доступ во время выполнения, но не во время компиляции, к типам public и protected в пакете, а также к членам public и protected этих типов. Это также предоставляет рефлексивный доступ ко всем типам в пакете и всем их членам для кода в других модулях.

Ошибка времени компиляции, если пакет, указанный в exports, не объявлен единицей компиляции, связанной с текущим модулем (§7.3).

Разрешено указать в opens пакет, который не объявлен единицей компиляции, связанной с текущим модулем. (Если этот пакет объявлен наблюдаемой единицей компиляции, связанной с другим модулем, то директива opens не оказывает никакого влияния на этот другой модуль.)

Ошибка времени компиляции, если более одной директивы exports в объявлении модуля указывает одно и то же имя пакета.

Ошибка времени компиляции, если более одной директивы opens в объявлении модуля указывает одно и то же имя пакета.

Ошибка времени компиляции, если директива opens появляется в объявлении открытого модуля.

Если директива exports или opens содержит опуслугу to, то директива является квалифицированной; в противном случае, она является неквалифицированной. Для квалифицированной директивы типы public и protected в пакете, и их члены public и protected, доступны исключительно для кода в модулях, указанных в опуслуге to. Модули, указанные в опуслуге to, называются друзьями текущего модуля. Для неквалифицированной директивы эти типы и их члены доступны для кода в любом модуле.

Разрешено, чтобы опуслуга to директивы exports или opens указывала на модуль, который не наблюдаем (§7.7.6).

Ошибка времени компиляции, если опуслуга to данной директивы exports указывает одно и то же имя модуля более одного раза.

Ошибка времени компиляции, если опуслуга to данной директивы opens указывает одно и то же имя модуля более одного раза.

Директива uses указывает на сервис, для которого код в текущем модуле может обнаруживать поставщиков через java.util.ServiceLoader.

Ошибка времени компиляции, если директива uses указывает на класс перечислений (§8.9).

Сервис может быть объявлен в текущем модуле или в другом модуле. Если сервис не объявлен в текущем модуле, то он должен быть доступен коду текущего модуля (§6.6), иначе произойдёт ошибка времени компиляции.

Ошибка времени компиляции, если более одной директивы uses в объявлении модуля указывают на один и тот же сервис.

Директива provides указывает на сервис, для которого фрагмент with указывает на один или несколько поставщиков сервиса, чтобы java.util.ServiceLoader.

Ошибка времени компиляции, если директива provides указывает на класс перечислений (§8.9) в качестве сервиса.

Сервис может быть объявлен в текущем модуле или в другом модуле. Если сервис не объявлен в текущем модуле, то он должен быть доступен коду текущего модуля (§6.6), иначе произойдёт ошибка времени компиляции.

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

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

Если поставщик сервиса явно объявляет конструктор public без формальных параметров или неявно объявляет конструктор по умолчанию public (§8.8.9), то этот конструктор называется конструктором поставщика.

Если поставщик сервиса явно объявляет метод public static с именем provider без формальных параметров, то этот метод называется методом поставщика.

Если у поставщика сервиса есть метод поставщика, то его тип возвращаемого значения должен (i) либо быть объявлен в текущем модуле, либо в другом модуле и быть доступным коду текущего модуля; и (ii) быть подтипом сервиса, указанного в директиве provides; иначе произойдёт ошибка времени компиляции.

Хотя поставщик сервиса, указанный в директиве provides, должен быть объявлен в текущем модуле, его метод поставщика может иметь тип возвращаемого значения, объявленный в другом модуле. Также обратите внимание, что когда поставщик сервиса объявляет метод поставщика, сам поставщик сервиса не обязательно должен быть подтипом сервиса.

Если у поставщика сервиса нет метода поставщика, то у него должен быть конструктор поставщика и он должен быть подтипом сервиса, указанного в директиве provides; иначе произойдёт ошибка времени компиляции.

Ошибка времени компиляции, если более одной директивы provides в объявлении модуля указывают на один и тот же сервис.

Ошибка времени компиляции, если фрагмент with данной директивы provides указывает на один и тот же поставщика сервиса более одного раза.

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

Безымянные модули предоставляются платформой Java SE для поддержки программ, разработанных до Java SE 9, которые не могли объявлять именованные модули. Кроме того, причины, по которым платформа Java SE предоставляет безымянные пакеты (§7.4.2), в значительной степени применимы к безымянным модулям.

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

Системный хост может связывать обычные модули компиляции в именованном пакете с безымянным модулем.

Правила для безымянных модулей разработаны для максимального взаимодействия с именованными модулями, как следует из этого:

Модуль наблюдаем, если хотя бы одно из следующих условий истинно: