Java语言规范基于JavaSE9 第七章包和模块（五）

最新推荐文章于 2024-06-21 15:51:08 发布

Ynter

最新推荐文章于 2024-06-21 15:51:08 发布

阅读量327

点赞数

分类专栏： IT 文章标签： java

IT 专栏收录该内容

25 篇文章 0 订阅

订阅专栏

7.4 Package Declarations

7.4 包声明

A package declaration appears within an ordinary compilation unit to indicate the package to which the compilation unit belongs.

出现在普通编译单元中的package声明表示该编译单元归属的包。

7.4.1 Named Packages

7.4.1 具名包

A package declaration in an ordinary compilation unit specifies the name (§6.2) of the package to which the compilation unit belongs.

在普通编译单元中的包声明指定了该编译单元所归属的包的名字（第6.2节）。

PackageDeclaration:
{PackageModifier} package Identifier {. Identifier} ;

PackageModifier: Annotation

The package name mentioned in a package declaration must be the fully qualified name of the package (§6.7).

在package声明中提及的包名必须是该包的完全限定名（第6.7节）。

The scope and shadowing of a package declaration is specified in §6.3 and §6.4.

包声明的作用域和遮蔽规则在第6.3节和第6.4节中进行了说明。

The rules for annotation modifiers on a package declaration are specified in §9.7.4 and §9.7.5.

针对包声明上的注解修饰符的规则在第9.7.4节和第9.7.5节中进行了说明。

At most one annotated package declaration is permitted for a given package.

在给定的包上，最多只允许有一个被注解的package声明。

The manner in which this restriction is enforced must, of necessity, vary from implementation to implementation. The following scheme is strongly recommended for file-system-based implementations: The sole annotated package declaration, if it exists, is placed in a source file called package-info.java in the directory containing the source files for the package. This file does not contain the source for a class called package-info; indeed it would be illegal for it to do so, as package-info is not a legal identifier. Typically package-info.java contains only a package declaration, preceded immediately by the annotations on the package. While the file could technically contain the source code for one or more classes with package access, it would be very bad form.

强制遵循这个限制的方式必然会随不同的实现而不同。下面的模式强烈推荐适用于基于文件系统的实现：单个被注解的package声明，应置于名字为package-info.java的文件中，而该文件在包含这个包的源文件的目录中。这个文件并不包含被称为package-info的类的源代码；实际上它并不是类的合法名字，因为package-info不是合法的标识符。通常package-info.java只包含package声明，其前面紧挨着这个包上的注解。尽管从技术上讲，该文件可以包含一个或多个具有包访问权限的类的源代码，但是这是一种非常不好的形式。

It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems. If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java. In this way, package-info.java becomes the sole repository for package-level annotations and documentation. If, in future, it becomes desirable to add any other package-level information, this file should prove a convenient home for this information.

推荐使用package-info.java来代替javadoc以及其他类似的文档生成系统中的package.html。如果有该文件，那么文档生成工具就应该在package-info.java中查找紧挨着（可能被注解的）package声明之前的包文档注释。在这种方式中，package-info.java变成了包级别的注解和文件的单一存储池。如果将来它需要增加其他的包级别信息，那么这个文件必须证明它是适合存储这些信息的载体。

7.4.2 Unnamed Packages

7.4.2 不具名包

An ordinary compilation unit that has no package declaration is part of an unnamed package.

没有任何package声明的普通编译单元是不具名包的一部分。

Unnamed packages are provided by the Java SE Platform principally for convenience when developing small or temporary applications or when just beginning development.

不具名包是Java SE平台提供的一种机制，主要是为了在开发小型或临时应用，或者在刚刚开始开发时提供便捷方式。

An unnamed package cannot have subpackages, since the syntax of a package
declaration always includes a reference to a named top level package.

不具名包不能有子包，因为package声明的语法总是要包含对具名的顶层包的引用。

An implementation of the Java SE Platform must support at least one unnamed package. An implementation may support more than one unnamed package, but is not required to do so. Which ordinary compilation units are in each unnamed package is determined by the host system.

Java SE 平台的实现必须至少支持一个不具名包，它也可以支持多个不具名包，但是这并不是强制要求的。在每个不具名包中包含哪些普通编译单元是由主机系统决定的。

The host system must associate ordinary compilation units in an unnamed package with an unnamed module (§7.7.5), not a named module.

主机系统必须将不具名包中的普通编译单元与不具名模块（第7.7.5节）而不是具名模块关联。

Example 7.4.2-1. Unnamed Package

例子 7.4.2-1. 不具名包

The compilation unit:

编译单元：

class FirstCall {
    public static void main(String[] args) {  
        System.out.println("Mr. Watson, come here. "
                             + "I want you.");
    }
}

defines a very simple compilation unit as part of an unnamed package.

定义了一个非常简单的编译单元，作为不具名包的一部分。

In implementations of the Java SE Platform that use a hierarchical file system for storing packages, one typical strategy is to associate an unnamed package with each directory; only one unnamed package is observable at a time, namely the one that is associated with the “current working directory”. The precise meaning of “current working directory” depends on the host system.

在使用层次结构的文件系统来存储包的Java SE平台的实现中，一种典型的策略是将不具名包与每个目录相关联，在任意时刻，只有一个不具名包是可观察的，即与“当前工作目录”相关联的包。“当前工作目录”的准确含义依赖于主机系统。

7.4.3 Package Observability and Visibility

7.4.3 包的可观察性和可见性

A package is observable if and only if at least one of the following is true:

当且仅当以下至少一种情况为真时，包是可观察的：

• An ordinary compilation unit containing a declaration of the package is observable (§7.3).

• 包含包的声明的某个普通编译单元是可观察的（第7.3节）。

• A subpackage of the package is observable.

• 包的某个子包是可观察的。

The packages java, java.lang, and java.io are always observable.

包java、java.lang和java.io总是可观察的。

One can conclude this from the rule above and from the rules of observable compilation units, as follows. The predefined package java.lang declares the class Object, so the compilation unit for Object is always observable (§7.3). Hence, the java.lang package is observable, and the java package also. Furthermore, since Object is observable, the array type Object[] implicitly exists. Its superinterface java.io.Serializable (§10.1) also exists, hence the java.io package is observable.

我们可以从上述规则以及可观察编译单元的规则中得出下面的结论。预定义包java.lang声明了类Object，因此Object的编译单元总是可观察的（第7.3节），因此，java.lang包是可观察的，而java包也是如此。更进一步，由于Object是可观察的，因此数组类型Object[]隐式地也是如此，它的超接口java.io.Serializable（第10.1节）也是如此，因此java.io包也是可观察的。

A package is visible to a module M if and only if an ordinary compilation unit containing a declaration of the package is visible to M.

当且仅当一个包含对包的声明的普通编译单元对模块M是可见的时，包才对模块M可见。

Package visibility is meant to imply that a package is “really” observable in some module on the system. It is not useful to think that package P is “technically” observable just because a subpackage P.Q is “technically” observable in some module. For example, suppose P.Q is “technically” observable in module M1 and P.R is “technically” observable in module M2; then, P is “technically” observable, but in M1 or M2 or both? During the compilation of some module N that requires M1 only, it matters that P.Q is “really” observable, and it does not matter that P is “technically” observable.

包的可见性意味着包在系统的某些模块上是“真实”可观察的。但这不助于理解包P是“技术上”可观察的，仅仅是因为P的子包P.Q在某些模块中是“技术上”可观察的。例如，假设P.Q在模块M1上是“技术上”可观察的，而P.R在模块M2上是“技术上”可观察的；那么，P是“技术上”可观察的，但是是在M1还是M2还是两者上呢？在编译某些只需要M1的模块N时，重要的是P.Q是“真实”可观察的，而P是“技术上”可观察的并不重要。

A package is uniquely visible to a module M if and only if one of the following holds:

当且仅当以下情况之一成立时，包对模块M是唯一可见的：

• An ordinary compilation unit associated with M contains a declaration of the package, and M does not read any other module that exports the package to M.

• 与模块M相关联的普通编译单元包含包的声明时，模块M不会读取将包指定为导出到M的任何其他模块。

• No ordinary compilation unit associated with M contains a declaration of the package, and M reads exactly one other module that exports the package to M.

• 没有与模块M相关联的普通编译单元包含包的声明时，模块M会完全读取将包指定为导出到M的其他模块。