java 核心技术-12版 卷Ⅰ- 4.10.6 包注释
可以直接将类、方法和变量的注释放置在 Java 源文件中，只要用 /** … */文档注释界定就可以了。但是，要想产生包注释，就需要在每一个包目录中添加一个单独的文件。可以有如下两个选择:
- 提供一个名为 package-info.java 的 Java 文件。这个文件必须包含一个初始的 Javadoc 注释，以/**和*/界定，后面是一个 package 语句。它不能包含更多的代码或注释。
- 提供一个名为 package.html 的HTML 文件，抽取标记 body>…</body> 之间的所有文本
在这里，假设你希望HTML 文件将放在名为 docDirectory 的目录下。执行以下步骤:
- 切换到源文件目录，其中包含想要生成文档的源文件。如果有嵌套的包要生成文档，例如： com.horstmann.corejava，就必须切换到包含子目录 com 的目录(如果提供 overview.html 文件的话，这就是这个文件所在的目录)。
- 如果是一个包，应该运行命令
javadoc -d docDirectory nameOfPackage
或者，如果要为多个包生成文档，运行:
javadoc -d docDirectory nameOfPackage1 nameOfPackage …
如果你的文件在无名包中，则应该运行:
javadoc -d docDirectony *.java
如果省略了 -d docDirectory 选项，HTML 文件就会提取列当前目录下。这样可能很混乱，因此我不提倡这种做法。
可以使用很多命令行选项对 javadoc 程序进行微调。例如，可以使用 -author 和 -version 选项在文档中包含 @author 和 @version 标记(默认情况下，这些标记会被略)。另一个很有用的选项是 -link，用来为标准类添加超链接。例如，如果使用命令
javadoc -link http://docs.oracle.com/javase/9/docs/api *.java
那么，所有的标准类库的类都会自动地链接到 Oracle 网站的文档。
如果使用 -linksource 选项，那么每个源文件将会转换为 HITML(不对代码着色，但包含行号)，并且每个类和方法名将变为指向源代码的超链接。
还可以为所有源文件提供一个概要注释。把它放在一个类似 overview.html 的文件中，运行 javadoc 工具，并提供命令行选项 -overview filename。将抽取标记 body>…</body> 之间的所有文本。当用户从导航栏中选择“Overview”时，就会显示这些内容。
有关其他的选项，请查阅 javadoc 工具的联机文档 https://docs.oracle.com/javase/9/javadoc/javadoc.html
java 核心技术-12版 卷Ⅰ- 4.7.1 记录 record
有时，记录就只是数据，而面向对象程序设计提供的数据隐藏有些碍事。考虑一个类Point ，这个类描述平面上的一个点，有x和y 坐标。
当然，可以如下创建一个类
这里隐藏了x和y ，然后通过获取方法来获得这些值，不过，这种做法对我们确实有好处吗？
我们将来想改变Point的实现吗？ 当然，还有极坐标，不过对于图形API ，你可能不会使用极坐标。在实际中，平面上的一个点就用x 和y 坐标来描述。
为了更简洁地定义这些类，JDK 14 引入了一个预览特性：“记录”（record）。最终版本在JDK 16 中发布。
记录（record）是一种特殊形式的类，其状态不可变，而且公共可读。可以如下将Point 定义为一个记录：
record Point(double x ,double y){}
其结果是有一下实例字段的类
private final double x;
private final double y;
在Java语言规范中，一个记录的实例字段称为组件（component）。
这个类有一个构造器
Point(double x,double y)
和以下访问器方法
public double x()
public double y()
注意，访问器方法名为 x 和 y ，而不是getX 和 getY。（Java中实例字段可以与方法同名，这是合法的。）
var p = new Point(3,4);
System.out.println(p.x() + \” \” + p.y());
注释：Java没有遵循get 的约定，因为那有些麻烦。对于布尔字段，通常使用is 而不是get。而且首字母大写可能有问题。如果一个类既有x字段又有X字段，会发生什么？有些程序员不太满意，因为他们原来的类不能轻松地变为记录。不过实际上，那些遗留类中，很多都是可变的，所以并不适合转为记录。
除了字段访问器方法，每个记录有3个自动定义的方法：toString 、equals 和 hashCode 。下一章会更多地了解这些方法。
警告：对于这些自动提供的方法，也可以定义你自己的版本，只要它们有相同的参数和返回类型。例如，下面的定义就是合法的：
record Point(double x,double y){
public double x() {
return y; // Bad 语法允许，但实际开发中非常不推荐
}
}
可以为一个记录增加你自己的方法：
与所有其他类一样，记录可以有静态字段和方法：
不过，不能为记录增加实力字段：
record Point(double x ,double y){
private double r ;// ERROR
}
警告：记录的实例字段自动为final 手段。不过，它们可能是可变对象的引用。
record PointInTime(double x, double y, Date when){}
这样的实例将是可变的；
var pt = new PointInTime(0 ,0 , new Date());
p.when().setTime(0);
如果希望记录实例是不可变的，那么字段就不能使用可变的类型。
提示： 对于完全由一组变量表示的不可变数据，要使用记录而不是类。如果数据是可变的，或者数据表示可能随时间改变，则使用类。记录更易读、更高效，而且在并发程序中更安全。
java 核心技术-12版 卷Ⅰ- 5.9.3 资源
类通常有一些关联的数据文件，例如:
- 图像和声音文件。
- 包含消息字符串和按钮标签的文本文件。
在Java 中，这此关联的文件被称为资源(resource)。
例如，考虑一个显示消息的对话框，如图 5-4 所示。
当然，对于本书的下一版，这个而板中显示的书名和版权年会改变。为了便于追踪这个变化，我们将把这个文本放在一个文件中，而不是作为一个字符串硬编码写到代码中。
但是，应该将类似about.txt 的文件放在哪儿呢?当然，将它与其他程序文件一起放在JAR 文件中会很方便
图 5-4 显示图像和文本资源
Class 类提供了一个很有用的服务可以查找资源文件。下面给出必要的步骤:
- 获得拥有资源的类的 Class 对象，例如 ResourceTest.class。
- 有些方法(如ImageIcon类的 getImage 方法)接受描述资源位置的 URL。那么，可以调用URL url = cl.getResource(\”about.gif\”);
- 否则，使用getResourceAsStream 方法得到一个输入流来读取文件中的数据。
这里的重点在于 Java 虚拟机知道如何查找一个类，所以它能搜索相同位置上的关联资源。例如，假设 ResourceTest类在一个 resources 包中。ResourceTest.class 文件就位于 resource目录中，可以把一个图标文件放在同一个目录下。
除了可以将资源文件与类文件放在同一个目录中，还可以提供一个相对或绝对路径，如
data/about.txt
/corejava/title.txt
文件的自动装载是利用资源加载特性完成的。没有标准的方法来解释资源文件的内容。每个程序必须有自己的方法来解释它的资源文件。
另一个经常使用资源的地方是程序的国际化。与语言相关的字符串(如消息和用户界面标签)都存放在资源文件中，每种语言对应一个文件。国际化API(intermationalization API)将在卷2的第7章中讨论。它支持一种标准方法来组织和访问这些本地化文件。
程序清单 5-14 的程序展示了资源加载。(先不用担心读取文本和显示对话框的代码，这
些内容稍后会详细介绍。) 编译、构建一个 JAR 文件执行:
javac resources/ResourceTest.java
jar cvfe ResourceTest.jar resources.ResourceTest resources/*.class resources/*.gif resources/data/*.txt corejava/*.txt
java -jar ResourceTest.jar
将JA件移到另外一个不同的目录中，再次运行，以确认程序是从JAR 文件而不是从当前目录读取资源.
程序清单5-14 resources/.java
API java.lang.Class 1.0
- URL getResource(String name) 1.1
- InputStream getResourceAsStream(String name) 1.1
- 找到与类位于同一位置的资源，然后返回一个 URL或者输人流，可以用来加载这个资源。如果没有找到资源，则返回 null，所以不会对 IO 错误抛出异常。
本书相关代码下载地址https://horstmann.com/corejava/
找到 Further Information 节点，
点击 Download Code 后面的 12th edition
会得到一个 corejava.zip 解压到你想要存放的位置
进入 v1ch05，在这里打开CMD 窗口
执行如下命令
javac resources/ResourceTest.java
jar cvfe ResourceTest.jar resources.ResourceTest resources/*.class resources/*.gif resources/data/*.txt corejava/*.txt
java -jar ResourceTest.jar
即可执行相关代码
本文作者及来源:Renderbus瑞云渲染农场https://www.renderbus.com
文章为作者独立观点不代本网立场，未经允许不得转载。
投诉举报&联系我们：
