1吧碾、規(guī)范文檔表示法說明

原文翻譯

Throughout this specification, we refer to classes and interfaces drawn from the Java SE Platform API. Whenever we refer to a class or interface (other than those declared in an example) using a single identifier N, the intended reference is to the class or interface named N in the package java.lang. We use the canonical name (§6.7) for classes or interfaces from packages other than java.lang.
在本規(guī)范中休建，我們引用了從JavaSE平臺API中提取的類和接口。每當我們使用單個標識符N引用一個類或接口（示例中聲明的除外）時，所要引用的是java.lang包中名為N的類或接口芥喇。我們對java.lang以外的包中的類或界面使用規(guī)范名稱（§6.7）权逗。

A cross-reference within this specification is shown as (§x.y). Occasionally, we refer to concepts in the The Java Virtual Machine Specification, Java SE 22 Edition via cross-references of the form (JVMS §x.y).
本規(guī)范中的交叉引用會以（§x.y）的形式展示。偶爾捣染，我們會以（JVMS §x.y）的形式來交叉引用來自Java SE 22版Java虛擬機規(guī)范中的概念骄瓣。

Non-normative text, designed to clarify the normative text of this specification, is given in smaller, indented text.
旨在澄清本規(guī)范規(guī)范性文本的非規(guī)范性文本采用較小的縮進文本。

This is non-normative text. It provides intuition, rationale, advice, examples, etc.
這是非規(guī)范性文本耍攘。它提供了直覺榕栏、理由、建議蕾各、例子等扒磁。

To shorten the description of some rules, especially those that systematically analyze the constructs of the Java programming language, the customary abbreviation "iff" is used to mean "if and only if".
為了縮短對某些規(guī)則的描述，特別是那些系統(tǒng)分析Java編程語言結(jié)構(gòu)的規(guī)則示损，習慣縮寫“iff”用于表示“如果且僅當”渗磅。

The type system of the Java programming language occasionally relies on the notion of a substitution. The notation [F1:=T1,...,Fn:=Tn] denotes substitution of Fi by Ti for 1 ≤ i ≤ n.
Java編程語言的類型系統(tǒng)偶爾會依賴于替換的概念。符號[F1:=T1检访，…始鱼，F(xiàn)n:=Tn]表示在1≤i≤n范圍內(nèi)Ti與Fi是可代換的。

總結(jié)

1脆贵、Java語言的完整類名是包含所在包名的医清，如日期類完整類名：java.util.Date
2、只有java.lang包下的類可以以獨立的類名稱出現(xiàn)在源代碼中卖氨。其他包下的類名稱必須以import引入包名或者用完整的攜帶有包名的類名会烙，方可使用
3负懦、規(guī)范中引用其他章節(jié)內(nèi)容采用（§x.y）的形式，引用JVM規(guī)范內(nèi)容章節(jié)采用（JVMS §x.y）的形式
4柏腻、用于解釋規(guī)范文檔中的特殊詞句的文字纸厉，用較小字體文本在規(guī)范中展現(xiàn)，其解釋的內(nèi)容主要有：直覺五嫂、理由颗品、建議、例子
5沃缘、文檔中也會采用固定的一些縮寫來代替一些名詞描述躯枢，以縮短描述內(nèi)容
6、文檔中會出現(xiàn)符號概念的代換

2槐臀、規(guī)范文檔中使用用的預定義類和接口說明

原文翻譯

As noted above, this specification often refers to classes and interfaces of the Java SE Platform API. In particular, some classes and interfaces have a special relationship with the Java programming language. Examples include classes such as Object, Class, ClassLoader, String, and Thread, and the classes and interfaces in the package java.lang.reflect, among others. This specification constrains the behavior of such classes and interfaces, but does not provide a complete specification for them. The reader is referred to the Java SE Platform API documentation.
如上所述锄蹂，本規(guī)范通常引用Java SE平臺API的類和接口。特別是水慨，一些類和接口與Java編程語言有著特殊的關(guān)系得糜。示例包括Object、Class讥巡、ClassLoader掀亩、String和Thread等類，以及包java.lang.reflect中的類和接口等欢顷。此規(guī)范限制了此類類和接口的行為，但沒有為它們提供完整的規(guī)范捉蚤。讀者可參考Java SE平臺API文檔抬驴。

Consequently, this specification does not describe reflection in any detail. Many linguistic constructs have analogs in the Core Reflection API (java.lang.reflect) and the Language Model API (javax.lang.model), but these are generally not discussed here. For example, when we list the ways in which an object can be created, we generally do not include the ways in which the Core Reflection API can accomplish this. Readers should be aware of these additional mechanisms even though they are not mentioned in the text.
因此，本說明書沒有詳細描述反射缆巧。許多語言構(gòu)造在核心反射API（java.lang.reflect）和語言模型API（javax.lang.Model）中都有類似的結(jié)構(gòu)布持，但這里通常不討論這些結(jié)構(gòu)。例如陕悬，當我們列出可以創(chuàng)建對象的方法時题暖，我們通常不包括核心反射API可以實現(xiàn)這一點的方法。讀者應(yīng)該意識到這些額外的機制捉超，即使文本中沒有提到它們胧卤。

總結(jié)

1、本規(guī)范使用的SE平臺的類和接口屬于閹割版的拼岳，沒有完全體現(xiàn)這些類的所有功能枝誊，具體使用時以API文檔為準
2、關(guān)于反射能夠?qū)崿F(xiàn)的功能本規(guī)范也沒有完全描述出來惜纸，不要迷信本規(guī)范叶撒，規(guī)范沒提到的不代表一定不存在

規(guī)范文檔中關(guān)于語言的預覽特性的說明

原文翻譯

A preview feature is:
預覽功能是：

• a new feature of the Java programming language ("preview language feature"), or
  Java編程語言的新功能（“預覽語言功能”）绝骚，或

• a new module, package, class, interface, field, method, constructor, or enum constant in the java.* or javax.* namespace ("preview API")
  java.或javax.命名空間中的新模塊、包祠够、類压汪、接口、字段古瓤、方法止剖、構(gòu)造函數(shù)或enum常量（“預覽API”）

that is fully specified, fully implemented, and yet impermanent. It is available in implementations of a given release of the Java SE Platform to provoke developer feedback based on real world use; this may lead to it becoming permanent in a future release of the Java SE Platform.
這是完全指定的、完全實現(xiàn)的湿滓，但也是短暫的滴须。它可以在給定版本的Java SE平臺的實現(xiàn)中使用，以激發(fā)開發(fā)人員基于現(xiàn)實世界使用的反饋叽奥；這可能導致它在Java SE平臺的未來版本中成為永久性的扔水。

Implementations must disable, at both compile time and run time, the preview features defined by a given release of the Java SE Platform, unless the user indicates via the host system, at both compile time and run time, that preview features are to be enabled.
除非用戶在編譯時和運行時通過主機系統(tǒng)指示要啟用預覽功能，否則實現(xiàn)必須在編譯時或運行時禁用給定版本的Java SE平臺定義的預覽功能朝氓。

The preview features defined by a given release of the Java SE Platform are enumerated in the Java SE Platform Specification for that release. The preview features are specified as follows:
Java SE平臺的給定版本定義的預覽功能在該版本的Java SE平臺規(guī)范中列舉魔市。預覽功能指定如下：

• Preview language features are specified in standalone documents that indicate changes ("diffs") to The Java? Language Specification for that release. The specifications of preview language features are incorporated into The Java? Language Specification by reference, and made a part thereof, if and only if preview features are enabled at compile time.
  預覽語言功能在獨立文檔中指定，這些文檔指示對該版本的Java?語言規(guī)范的更改（“diffs”）赵哲。如果且僅當在編譯時啟用了預覽功能時待德，預覽語言功能的規(guī)范通過引用合并到Java?語言規(guī)范中，并成為其中的一部分枫夺。

  Java SE 22 defines three preview language features: Implicitly Declared Classes and Instance main Methods; Statements Before super``(...); and String Templates. The standalone documents which specify these preview features are available at the Oracle web site which hosts The Java? Language Specification: https://docs.oracle.com/javase/specs/.
  Java SE 22定義了三個預覽語言特性：隱式聲明類和實例主方法将宪；語句在超級``（…）；之前橡庞；和字符串模板较坛。指定這些預覽功能的獨立文檔可在承載Java?語言規(guī)范的Oracle網(wǎng)站上獲得：
  https://docs.oracle.com/javase/specs/.

• Preview APIs are specified within the Java SE API Specification for that release.
  預覽API是在該版本的Java SE API規(guī)范中指定的。

The rules for use of preview language features are as follows:
預覽語言功能的使用規(guī)則如下：

• If preview features are disabled, then any source code reference to a preview language feature, or to a class or interface declared using a preview language feature, causes a compile-time error.
  如果預覽功能被禁用扒最，則任何對預覽語言功能的源代碼引用丑勤，或?qū)κ褂妙A覽語言功能聲明的類或接口的引用，都會導致編譯時錯誤吧趣。

• If preview features are enabled, then any source code reference to a class or interface declared using a preview language feature causes a preview warning, unless one of the following is true:
  如果啟用了預覽功能法竞，則對使用預覽語言功能聲明的類或接口的任何源代碼引用都會導致預覽警告，除非以下情況之一為真：

  • The reference appears in a declaration that is annotated to suppress preview warnings (§9.6.4.5).
    引用出現(xiàn)在聲明中强挫，該聲明被注釋為禁止預覽警告（§9.6.4.5）岔霸。

  • The reference appears in an import declaration (§7.5).
    該引用出現(xiàn)在接口申報單中（§7.5）。

  When preview features are enabled, Java compilers are strongly encouraged to give a non-suppressible warning for every source code reference to a preview language feature. Details of this warning are beyond the scope of this specification, but the intent should be to alert programmers to the possibility of code being affected by future changes to preview language features.
  如果啟用了預覽功能纠拔，強烈建議Java編譯器對每個引用預覽語言功能的源代碼發(fā)出不可抑制的警告秉剑。此警告的詳細信息超出了本規(guī)范的范圍，但其目的應(yīng)該是提醒程序員稠诲，代碼可能會受到未來預覽語言功能更改的影響侦鹏。

Some preview APIs are described as reflective by the Java SE Platform Specification, principally in the java.lang.reflect, java.lang.invoke, and javax.lang.model packages. The rule for use of reflective preview APIs is as follows:
Java SE平臺規(guī)范將一些預覽API描述為反射式API诡曙，主要在Java.lang.reflect、Java.lang.invoke和javax.lang.model包中略水。反射式預覽API的使用規(guī)則如下：

• Whether preview features are enabled or disabled, any source code reference to a reflective preview API element causes a preview warning, unless one of the following is true:
  無論預覽功能是啟用還是禁用价卤，對反射預覽API元素的任何源代碼引用都會導致預覽警告，除非以下情況之一為真：

  • The declaration where the reference appears is within the same module as the declaration of the reflective preview API element.
    引用出現(xiàn)的聲明與反射預覽API元素的聲明位于同一模塊內(nèi)渊涝。

  • The reference appears in a declaration that is annotated to suppress preview warnings.
    引用出現(xiàn)在一個聲明中慎璧，該聲明被注釋為不顯示預覽警告。

  • The reference appears in an import declaration.
    引用出現(xiàn)在接口聲明中跨释。

All preview APIs not described as reflective in the Java SE Platform Specification are normal. The rules for use of normal preview APIs are as follows:
Java SE平臺規(guī)范中未描述為反射的所有預覽API都是正常的胸私。正常預覽API的使用規(guī)則如下：

• If preview features are disabled, then any source code reference to a normal preview API element causes a compile-time error, unless:
  如果預覽功能被禁用，則任何對普通預覽API元素的源代碼引用都會導致編譯時錯誤鳖谈，除非：

  • The declaration where the reference appears is within the same module as the declaration of the normal preview API element.
    引用所在的聲明與普通預覽API元素的聲明位于同一模塊內(nèi)岁疼。

• If preview features are enabled, then any source code reference to a normal preview API element causes a preview warning, unless one of the following is true:
  如果啟用了預覽功能，則對正常預覽API元素的任何源代碼引用都會導致預覽警告缆娃，除非以下情況之一為真：

  • The declaration where the reference appears is within the same module as the declaration of the normal preview API element.
    引用所在的聲明與普通預覽API元素的聲明位于同一模塊內(nèi)捷绒。

  • The reference appears in a declaration that is annotated to suppress preview warnings.
    引用出現(xiàn)在一個聲明中，該聲明被注釋為不顯示預覽警告贯要。

  • The reference appears in an import declaration.
    引用出現(xiàn)在接口聲明中暖侨。

總結(jié)

• 預覽功能分兩類
  1、預覽語言功能（語言新增的新特性）
  2崇渗、預覽API（java.或javax.命名空間中的新模塊字逗、包、類宅广、接口扳肛、字段、方法乘碑、構(gòu)造函數(shù)或enum常量）

• 關(guān)于預覽功能有如下特點

  1、功能實現(xiàn)是完善可用的
  2金拒、有可能在未來會發(fā)生不可預知的變更
  3兽肤、目的是為了鼓勵開發(fā)者使用這些功能并提供反饋以促使在未來成為永久好用的功能
  4、默認情況下預覽功能是被禁用的绪抛，啟用需要開發(fā)者明確指明使用預覽功能

• 預覽功能在本規(guī)范中體現(xiàn)說明

  1资铡、預覽語言功能描述在獨立的文檔中體現(xiàn)。當在編譯時啟用了預覽功能時幢码，預覽語言功能的規(guī)范才會被引入到Java?語言規(guī)范中笤休，并成為其中的一部分，不啟用則不會作為語言規(guī)范的一部分症副。
  2店雅、預覽API是在該版本的Java SE API規(guī)范中指定的

• 預覽語言功能的使用規(guī)則
  1政基、禁用預覽功能時，直接的源代碼引用或者間接引用了預覽語言功能的類和接口闹啦，都會導致編譯失敗沮明。
  2、啟用預覽功能時使用預覽語言功能會觸發(fā)警告窍奋，以下不會觸發(fā)此警告：

  a.只出現(xiàn)在引入聲明中
  b.出現(xiàn)在代碼邏輯中并聲明了禁止觸發(fā)警告

  3荐健、建議Java編譯器的實現(xiàn)者在實現(xiàn)編譯器時對使用了預覽語言功能源代碼發(fā)出不可抑制的警告，向開發(fā)者提示使用風險

• 預覽API是使用規(guī)則

  • 反射預覽API規(guī)則（主要在Java.lang.reflect琳袄、Java.lang.invoke和javax.lang.model包中）
    1江场、無論預覽功能是啟用還是禁用，對反射預覽API元素的任何源代碼引用都會導致預覽警告窖逗，以下不會觸發(fā)此警告：

    a.同一模塊內(nèi)使用
    b.出現(xiàn)在代碼邏輯中并聲明了禁止觸發(fā)警告
    c.只出現(xiàn)在引入聲明中

  • 正常預覽API規(guī)則
    1址否、禁用預覽功能時，任何對預覽API的使用都會編譯失敗滑负，除非在同一模塊內(nèi)使用
    2在张、啟用了預覽功能，任何對預覽API的使用都會觸發(fā)預覽警告矮慕，以下情況除外：

    a.聲明使用在同一個模塊內(nèi)
    b.聲明使用帮匾，并在使用時聲明禁止觸發(fā)警告
    c.只出現(xiàn)在引入聲明中