[翻译]JBoss AS7 用户指南
[原文] http://community.jboss.org/wiki/JBossAS7UserGuide
?
这是简要的指南，意在帮助那些期望体验JBoss AS7的用户，尽管JBoss AS7还在开发过程中。如果你有任何关于这篇文章内容的反馈，可以通过发表该文的评论或者访问"JBoss AS7 Development"论坛的wiki，或者发给jboss development邮件列表 jboss-development@lists.jboss.org.
?
AS7 当前还处于"Beta"状态，所以用户不应该期望所有的功能像已经发布的AS5 AS6一样的稳定，同样应该了解从一个alpha版本升级到另外版本可能会有重大的改变。
?
?
获得 JBoss AS 7AS7 可以从 jboss.org download page下载. 因为还只是预览版，安装过程只需要解压即可。
?
我们鼓励用户从 AS 7 的源码库取出源代码并且自行编译，这很快并且不会有任何麻烦，只要在你的操作系统上装有git(分布式的版本管理工具)，设置git也非常简单。关于如何取出以及编译AS 7 源码可以参考Hacking On JBoss AS 7 wiki page。
?
?
快速启动一旦你下载了分发包并解压缩，你需要判断你要让AS 7工作在 "domain mode" 还是 "standalone mode"，为了理解这两个选项的意义，可以参考下面的 "Domain Mode vs. Standalone Mode"章节。
?
如果你要工作在 domain mode, 打开字符终端并且 cd 到解压的 bin 目录，然后运行 "domain"启动脚本。
?
?Linux/Unix:
?
?
?
log --Server的日志文件
?
tmp -- Server存储临时文件的地方
?
"Domain Mode" 配置文件?
位于 domain/configuration 目录.
?
domain.xml -- domain的主要配置文件，包括各种给AS instance 的 "profile" 配置文件。一个 profile配置包括各种子系统(subsystem)的配置（比如： embedded JBoss Web instance 是一个子系统，JBoss TS transaction manager 是一个 subsystem, 等等）。包括 子系统要打开的socket group的定义，以及"server groups"的定义，对于一个profile，会映射一组socket定义以及0到多个deployment。每一个单独的Server会被映射(在 host.xml中，下面会讲到)到一个server group；Sever group的配置最大可能的定义了单个server的配置。
?
一个 domain.xml 文件必须位于安装目录的 domain/configuration 下，如果不运行 domain controller，不需要有这个文件；比如：仅仅配置了了 Host Controller用于连接 remote Domain Controller时，此时 domain.xml 会被忽略。
?
用户可以看一下 AS 7 configuration schema, 从 <domain> 元素开始，来学习更多关于 Domain Contoller的内容。
?
?host.xml -- Host Controller的配置文件。每一个安装必须有host.xml文件，包含了 Host Controller的配置信息，主要有：
运行的AS Server instance的名称列表，以及他们所属的server group。配置Host Controller怎么联系 Domain Controller以便注册自己并访问domain配置。既可能配置为如果查找和联系一个remote Domain Controller，也可能配置为告诉Host Controller自己作为 Domain Controller.本地安装的一些特别的配置项。比如，domain.xml中定义named interface能够在host.xm中l映射到一个实际的特定机器的IP地址?
用户可以看一下 AS 7 configuration schema, 从 <host> 元素开始，来学习更多关于 Host Contoller的内容。
?
logging.properties -- 包含Host Controller和 Process Controller的日志配置。也定义每个AS instance初始启动的日志配置配置。一旦Server启动到这个配置生效，启动日志配置会被domain.xml中日志配置所覆盖。
?
"Standalone Mode" 配置文件?
位于 standalone/configuration 目录.
?
standalone.xml -- AS instance的主要配置文件。除此之外，包含了AS instance 运行的"profile"的配置。一个 profile配置包括各种子系统(subsystem)的配置（比如： embedded JBoss Web instance 是一个子系统，JBoss TS transaction manager 是一个 subsystem, 等等）。也包括subsystem可能打开的socket的定义。
?
用户可以看一下 AS 7 configuration schema, 从 <server> 元素开始，来学习更多关于 standalone AS instance的内容。
?
?
?
?
logging.properties -- 包含了启动时初始化的日志配置信息。在Server启动过程进行到standalone.xml中的日志配置信息可用时，启动日志配置会被standalone.xml文件中的日志配置覆盖。
?
通用配置概念?
有一些通用的配置概念对于 Domain Mode 和 Standalone Mode 均适用:
?
扩展(Extensions)?
一个 extension 是一个扩展了Server核心功能的模块。AS core是非常简单和轻量的，大多数与用户相关的功能通过扩展来提供。一个扩展打包成一个模块放置在 modules 目录下。用户如果要激活一个特定的扩展，就在domain.xml或者standalone.xml文件中包含<extension/>标签并指定扩展名。
?
?
AS自动提供了一些标准的路径，用户不需要在配置文件中配置它们：
?
?
jboss.home - AS的跟目录user.home - 用户的home目录user.dir - 用户当前的工作目录java.home - java 安装目录jboss.server.base.dir - 单独server instance的根目录jboss.server.data.dir - server 存储数据文件的目录jboss.server.log.dir - server日志文件的存放目录jboss.server.tmp.dir - server存储临时文件的目录jboss.domain.servers.dir - host controller用户为单个server instance 存放工作文件的目录 (domain mode only)?
用户可以在配置文件中增加<path/>标签和定义自己的路径，并可以覆盖除上面前天个路径之外的所有路径。
?
?
详细内容可以参考 XSD.
?
?
在domain.xml中，<path/>除了 name 属性之外不需要其它的属性，也就是不需要任何关于实际文件系统路径的信息：
?
<path name="x"/>
?
这个配置项的意思是，"有一个名称为'x'的路径，在domain.xml可以被引用，而'x'的指向的实际的文件系统的路径由每一个主机的 host.xml配置文件给出。" 如果使用这种方法，在每台主机的 host.xml中就必须有一个path标签来制定其真实的文件系统路径：
?
?
<path name="x" path="/var/x" />
?
接口(Interfaces)是为 network interface/IP address/host name 定义逻辑名，用于绑定sockets。domain.xml, host.xml和? standalone.xml的配置都包含了一个段落来申明接口。其它的段落则可以使用逻辑名称来引用，而不用指定完整的全名称(不同的机器可能不一样)。
?
一个接口配置包含接口的逻辑名称以及用户解析物理地址的标准信息。标准是两种类型中的热和一个：一个element用于指定该接口需要被绑定到一个通配符地址，或者接口或地址需要匹配的一个包含了一个或多个特征的列表。
?
?
<interface name="global">
?? <!-- Use the wildcard address -->
?? <any-address/>
</interface>
?
<interface name="external">
?? <nic name="eth0"/>
</interface>
?
<interface name="default">
?? <!-- Match any interface/address on the right subnet if it's
??????? up, supports multicast and isn't point-to-point -->
?? <subnet-match value="192.168.0.0/16"/>
?? <up/>
?? <multicast/>
?? <not>
????? <point-to-point/>
?? </not>
</interface>
?
<interface name="loopback">
?? <inet-address value="127.0.0.1"/>
</interface>
?
关于各种标准选项的详细信息，请查看 XSD。
?
domain.xml中的<interface/>标签不需要包含除name属性外的任何属性；也就是它不需要指定这个名称关联的具体IP地址信息：
?
<interface name="internal"/>
?
这个配置是说，"有一个名称为'internal'的接口，公domain.xml其它部分引用。'internal'实际对应的IP地址由每一台主机的host.xml配置文件来指定。" 如果使用该方法，在每台主机的host.xml中，必须要有一个interface元素来指定获取IP地址的标准：
?
<interface name="internal">
?? <nic name="eth1"/>
</interface>
?
Socket绑定以及组绑定(Socket Bindings and Socket Binding Groups)socket binding用户给socket命名。
?
domain.xml和standalone.xml都包含了一个段落用于申明socket binding。其它的段落则可以通过逻辑名称来引用，而不是使用详细的全名(不同的主机可能不一样)。
?
一个 socket binding 包含了以下信息：
?
name -- socket配置的逻辑名称，定义好之后，能够用在配置文件中的其它地方port -- socket绑定的端口(注意：servers通过应用一个增加/减少的数值来改变配置好的端口，下面会讲到)
interface (optional) -- socket要绑定的接口的名称（上面讲到了接口）multicast-address (optional) -- 广播地址，如果socket要使用广播multicast-port (optional) -- 广播端口，如果socket要使用广播fixed-port (optional, defaults to false) -- 如果为true，则申明port的值不能被覆盖?
Socket 绑定配配置被放置在<socket-binding-group/>元素里。这个元素包括一个default-interface属性；如果没有指定interface，这个interface将会作为默认的interface使用。
?
System Properties?
domain.xml, host.xml and standalone.xml，中有很多地方可以设置系统属性。standalone.xml中的值在server启动过程中解析。domain.xml和host.xml中的值在在servers加载的时候解析。
?
Profiles and Subsystemsdomain.xml和standalone.xml中最有意义的配置部分是一个(standalone.xml中)或者多个(domain.xml)"profiles"。profile一组命名的subsystem配置。subsystem是使用extension添加到core server上的功能("Extensions"章节已经讲到)。比如：一个subsystem提供了servlet处理能力；一个subsystem提供EJB容器；一个subsystem提供了JTA，等等。一个profile是一个subsystem的列表,以及每一个subsystem的详细配置。一个包含了大量subsystem的profile意味着这个sever拥有更多的功能。一个只有少量subsystem的profile将拥有较少的功能，但同时也更轻量。
?
?
在domain.xml和standalone中，一个单独的profile配置的内容看起来大致上应该是一样的。唯一的不同是，standalone.xml中只会有一个profile元素(用于运行该server)，而domain.xml可以有多个profile，每一个都可以映射到一个或者多个server组。domain.xml中的profile元素还支持<includes profile="another_profile"/>标签，允许通过重用简单的profile来构造复杂的profile。
?
Standalone Mode配置概念除了上面描述的通用配置概念之外，下面的概念是特定于运行standalone mode的AS 实例。
?
Server Name?
standalone.xml中的 <server/> 根元素有一个 name 属性。如果设置了，这个值就是这个server的名称。如果没有设置，默认的值为 java.net.InetAddress.getLocalHost().getHostName()。在运行环境中，建议用户为每一个server定义一个唯一的名字。server name 对于server中所有运行的service是可见的。
?
Paths and Interfaces上面讲到，domain.xml支持非完整描述的patch(使用真实的文件系统路径)和接口(提供一个标准去检测ip 地址)，在standalone.xml 中，这是不支持的。
?
Socket Binding and Avoiding Port Conflictsstandalone.xml中，只支持一个<socket-binding-group/>元素。
?
?
standalone.xml中，<socket-binding-group/>元素可以包含一个port-offset属性。这个属性的值会加上socket配置的port值。设置port-offset为一个非0的值，可以让多个AS instance使用同样socket binding和interface配置运行在一台机器上，而不会有端口的冲突。
?
domain.xml中的 <socket-binding-group/>没有 port-offset属性；参考下面的 "Domain Mode Configuration Concepts"章节有关于相似配置的内容。
?
?
Profiles?
上面提到，在standalone.xml中只能有一个profile元素。
?
Deploymentsstandalone.xml包含了一节用于列出在这个server上需要部署的内容(deployment content)。Deployment content 既可以通过AS's management APIs上传，也可以通过配置一个 deployment scanner service 并且放置内容到servcie扫描的目录中（比如：deployments/ 目录）。
?
每一个deployment元素包含了以下信息：
?
name -- deployment的唯一标准，必须保证所有deployments中全局唯一。runtime-name -- 运行时deployment的名称，应该等同于deployment file的文件名，用于组成像默认Java EE应用和module的名称。通常，这个值和name一样，但某些情况下，用户希望两个deployment使用相同的runtime-name(比如："foo.war"的两个版本) ，这样，两个deployment有不同的name却有相同的runtime-name。hash -- deployment内容的has值，在depoyment content上传的时候，由服务器生成。Server使用hash在deployment repository中查找content。start -- 布尔值用来指示deployment content是否已经被部署到运行环境（在server启动时，会被自动部署）。?
Domain Mode配置概念(Domain Mode Configuration Concepts)?
除了上面描述通用配置概念之外，下面的概念特定于domain mode下的 AS 实例。
?
Domain.xml vs Host.xml?
Domain configuration被分成两部分：一组configuration元素，定义domain中所有host的配置(存储在作为Domain Controller的主机的domain.xml文件中)，以及一组configuration元素配置每个host的不同部分(存储在每台主机的host.xml文件中)。大多数配置应该来自于domain.xml；host.xml仅仅为了定义在不同的host中必需不同的那部分(比如：IP地址，文件系统路径，以及最重要的server的名称)。
?
每一个主机的 Host Controller负责加载host.xml文件中配置信息。为了做到这点，Host Controller从Domain Controller中得到作用于整个domain的配置的副本，提取出对于这个Server的配置部分(比如：运行server的profile)，并应用特定于该主机的信息(比如：用于命名interface的IP地址)，然后创建一个特别于该server的配置。Host Controller 然后启动 server 进程并且提供给它配置信息。如果配置信息使用 xml 格式描述，看起来就会和 standalone.xml文件一样 -- Host Controller 本质上就是从相关的 domain.xml 和 host.xml 内容中，综合整理出一个 standalone.xml 。
Domain.xml 配置概念(Domain.xml Configuration Concepts?
Profiles?
上面提到，domain.xml 可以包含多个 profiles。domain不同的server可以运行不同profile。
?
Paths and Interfaces?
上面讨论了，domain.xml 中的path 和 interface 元素可以不包含任何东西，而仅仅是它们的name，这种情况下，host.xml将负责提供path和interface的详细信息。
?
?
Deployments?
Domain Controller 维护了一个 deploy content 的库，在domain的server中可以使用它。
?
domain.xml文件包含了一节，用户列出domain中可用的deploy content。Deployment content 使用 AS 的? Management APIs 上传。
?
每一个deployment元素包含了下面的信息：
?
?
The Domain Controller maintains a repository of deployment content that is available for use in the servers in the domain.
The domain.xml file includes a section listing the deployment content available for use in the domain. Deployment content is made available for use by uploading it using the AS's management APIs.
?
Each deployment element includes the following information:
name -- deployment的唯一标准，必须保证所有deployments中全局唯一。runtime-name -- 运行时deployment的名称，应该等同于deployment file的文件名，用于组成像默认Java EE应用和module的名称。通常，这个值和name一样，但某些情况下，用户希望两个deployment使用相同的runtime-name(比如："foo.war"的两个版本) ，这样，两个deployment有不同的name却有相同的runtime-name。hash -- deployment内容的has值，在depoyment content上传的时候，由服务器生成。Server使用hash在deployment repository中查找content。?
注意：在这个domain-level中列出的 deployment 并不意味着会实际部署到任何Server中。仅简单的说明domain已经知道这个内容，并是可用的。Deployment只有在映射到 Server groups 的时候才会部署到server中去(下面会讲到)。
?
Server Groups包括上面"General Configuration Concepts"一节中描述通用配置概念，domain.xml中最重要的元素是Server Groups的定义。每一个AS instance都是一个 server group 的成员。(即使一个group只有一个server，这个server仍然是group的一员)。Domain management system 负责确保一个server group中的所有 server 使用相同的配置。它们被配置使用相同的profile并且有相同的 deployment content。
?
?
?
?
?
Domain可以有多个 server group。
?
下面是一个server group的定义范例：
?
?Host.xml 配置概念(Host.xml Configuration Concepts)
Paths and Interfaces在 domain.xml 中申明但没有完整定义的 path 和 interface，需要在 host.xml 中完整指定。因为 filesystem paths and IP addresses 在不同 host 上不一样，所以需要的详细信息在每一个 host.xml 中都需要提供。
?
System Properties?
System property 可以在 host.xml 最上级元素中申明。这里申明的属性会在host上的server启动时被设置。
?
JVMs?
Host.xml可以包含一个或多个 JVM 配置。配置包括一些详细信息，不如：JVM二进制文件的所在路径, 内存大写，环境变量，等等。 单独的server 配置可以通过名字引用这些 JVM Configuration 中的某一个，Host Controller 会使用该 configuration 去启动 server。
?
注意：domain.xml 中的 server-group 元素以及单个的 server 元素(下面会讲到)也可以定义JVM configuration。如果在多个地方配置，这些元素会被合并，server 元素会优先于 server-group 元素，也优先于host-level 的 JVM 配置。
?
Management Interfaces?
Host Controller 用于支持远程管理的connector 配置。 TODO
?
Domain Controller?
配置 Host Controller 如何查找及联系 Domain Controller：
?
?
??
