Глава 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. Это указывает, что зависимость, обязательная во время компиляции, является необязательной во время выполнения.

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

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

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

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

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

Java SE Platform различает именованные модули, которые явно объявлены (то есть, с объявлением модуля), и именованные модули, которые неявно объявлены (то есть, автоматические модули). Однако, язык программирования 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 должна поддерживать как минимум один безымянный модуль. Реализация может поддерживать более одного безымянного модуля, но это не является обязательным. Какие обычные блоки компиляции связаны с каждым безымянным модулем, определяется системным хостом.

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

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

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