【译】resin4.0 API——resin.xml

        原文：http://caucho.com/resin-4.0/admin/config-resin-xml.xtp#Resourcesdatabasesqueuescachesandcustom

       resin中，所有的用户自定义配置都配在resin.xml里。resin.xml概要着重描述了资源，集群，域名映射与URL映射控制，以及习惯性配置。

目录

 1.    概念和命名约定

 2.    resin.xml概要

 3.    默认配置：服务默认配置，集群默认配置，web应用默认配置

 4.    服务：一个JVM实例

 5.    监控（watchdog）：保护服务

 6.    集群：执行共同任务的多个服务

 7.    host：HTTP虚拟host

 8.    Web应用：HTTP/Servlet应用（即静态或动态的应用）

 9.    Rewrite：控制URL映射

10.   负载均衡：用于对多个后端服务器负载均衡

11.  日志：JDKjava.util.logging

12.  resource：数据库，队列，缓存

13.  健康：监控，操作，与报告

14.  安全：身份验证与权限约束

1.      概念和命名约定

·cluster（集群）-   一个集群包含多个server。

·environment（环境）  -   应用的（原文是独立类加载环境 insolated class-loader contexts）的上下文，即应用享有的资源。server，host，web-app是最主要的环境。

·host - 一个HTTP虚拟host

·proxy cache（代理缓存） -   HTTP代理缓存（译注：收到请求之后，检查本地的缓存来确定是否要向后端服务器发起请求，向后端发起请求并收到回复的情况下，把响应回复又缓存在本地。类似nginx）

·resource（资源）- 应用可使用的驱动或服务。含：JNDI，CDI，JMS队列，习惯性CDI配置。resin特有的资源含：安全，身份验证，健康检测和重定向/URL映射系统。

·rewrite/dispatch（重定向/调度）  -   定向HTTP请求到servlet和相应响应代码。类似于使用apache的mod_rewrite进行URL地址的重定向。

·server（服务）  -    一个Resin JVM实例。一台机器上可以有多个server。

·watchdog（监控）   -   一个用于监控Resin server的JVM实例，它可以在它认为有必要的时候自动重启server。

·web-app （web应用）– 一个HTTP web应用，里面包含了servlet。

2.      resin.xml概要

例：

<resinxmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin">  <cluster-default>             <!-- shared configuration across allclusters -->    <resin:importpath="classpath:META-INF/caucho/app-default.xml"/>    <resin:importpath="${__DIR__}/health.xml" optional="true"/>  </cluster-default>           <cluster id="my-cluster">    <server-default>      <!-- thread limits, JVM config,keepalives, ports, HTTP -->      <http port="8080"/>    </server-default>    <server id="server-a"address="192.168.1.10" port="6800"/>    <server id="server-b"address="192.168.1.11" port="6800"/>    <host id="www.myhost.com"root-directory="hosts/myhost.com">    <resin:MovedPermanentlyregexp="/old-file" target="/new-path"/>       <web-app-deploypath="webapps"           expand-preserve-fileset="WEB-INF/work/**"/>      <web-app id="/custom">      </web-app>     </host>    </cluster></resin>

<cluster>是server，host，以及通用资源的容器。cluster中的server共用它的配置。

3.      默认配置：服务默认配置，集群默认配置，web应用默认配置（server-default,cluster-default, web-app-default）

想给一组server配一些默认项，比如最大线程数，http端口号时，你可以把这些公共的配置放在<server-default>中。类似的，对于cluster，virtual-host或web-app-default，你可以用<cluster-default>,<host-default>和<web-app-default>去管理这些公共配置。

以下例子中，用<cluster-default>和<resin:import>来管理公共web-app配置，且health-system的配置也通用于所有的cluster。

例子：

<resinxmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin">  <cluster-default>    <resin:importpath="classpath:META-INF/caucho/app-default.xml"/>       <resin:importpath="${__DIR__}/health.xml" optional="true"/>  </cluster-default>  <cluster id="my-cluster-a">    ...  </cluster>  <cluster id="my-cluster-b">    ...  </cluster></resin>  

4.      服务：一个JVM实例

详细配置见serverconfiguration。

一个<server>标签配置cluster中的一个JVM实例。一个server的独立配置不通用于整个集群配置。watchdog根据<server>标签的内容去启动一个Resin JVM，<server>标签中也配置JVM参数。

·  server id 用于标识一个server。

·  局域网IP地址和端口用于和server交互

·  JVM参数，比如-Xmx

·  线程配置如thread-idle-min和thread-idle-max

·  TCP端口（含HTTP端口）的超时时间和cluster端口

·  负载均衡配置，包含负载比重和超时时间

·  使用Unix setuid的用户名和用户组名，保证安全性

<server>配置了cluster中的servers，server使用 --elastic-server和--cluster command-line 启动，server们共享cluster中的<server-default>配置。

5.      监控（watchdog）：保护服务

watchdog监控Resin server的JVM实例，当实例出错的时候，watchdog会自动重启它。watchdog承担为server设置JVM参数的工作，打印日志，处理Unix的setuid。

6.      集群：执行共同任务的多个服务

详细配置说明见：clusteringconfiguration

一个Resin集群包含一组执行共同任务的server，比如说提供HTTP请求服务，负载均衡，或处理JMS队列。每个的server都会属于某个cluster。即使只有一个server，也会隶属于一个cluster。

server共同的任务会被配置在cluster中，无论是传统的HTTP请求，JMS队列或是SOA型的服务。HTTP类型的服务需要特别配置<host>标签，而重定向系统，非HTTP类服务可以使用CanDI型配置。

例子：http servlet的cluster配置

<resinxmlns="http://caucho.com/ns/resin">  ...  <cluster id="http">    <server id="a"address="192.168.1.10" port="6800">      <http port="8080"/>    </server>    <host id="">      <web-app-deploypath="webapps"          expand-preserve-fileset="WEB-INF/work/**"/>    </host>  </cluster></resin>

一个resin cluster也可以用作非HTTP资源。Resin会管理JVM生命周期，watchdog自动重启，系统健康检查以及cluster交互。当然服务也会受自身代码的操纵管理。（废话）

例子：非http servlet的cluster（原文是cluster for httpservlets，应该有问题，此处是non-http配置）

<resinxmlns="http://caucho.com/ns/resin"  xmlns:myservice="urn:java:com.mycom.myservice"> ... <cluster id="http">    <server id="a"address="192.168.1.10" port="6800"/>    <myservice:MyServiceaddress="${resin.address}">      ... <!-- CanDI configuration for theservice -->    </myservice:MyService> </cluster></resin>

<cluster>标签形成了一个class-loader资源环境，这个资源可以被所有的host和server中的所有web-apps共享。公共的CDI资源如数据库，队列和缓存可以配置在cluster中，则可以被整个环境所访问。

7.      host：HTTP虚拟host

详细配置见：virtualhost configuration

用<host>标签可以配置一个HTTP虚拟host。host的名字用id或host-name属性标识。名字为空的host，如id=””这样的是默认host。

host可以专门用<host>标签配置，也可以用<host-deploy>标签隐式配置。host们共享<host-default>中的公共配置。<host-deploy>中包含一个隐式定义的host的目录，比如说”webapps”目录用于<web-app-deploy>。

<host>标签映射一个HTTP url到一个虚拟host上。这个host可以对应一个或多个<web-app-default>、<web-app>、<web-app-deploy>中的web-app。

对于cluster来说，<host-deploy>可以当做命令行部署的目的地。所有cluster中的server可以继承拓展命令行部署的host。

因为host可定义环境资源，因此它可以定义共享资源如数据库，缓存，CDI服务和队列。host也可以定义URL映射规则。

8.      Web应用：HTTP/Servlet应用（即静态或动态的应用）

详细配置见：deployconfiguration

一个web-app是一个基于http请求的应用，用servlet来处理请求。web-apps可以在WEB-INF/web.xml和WEB-INF/resin-web.xml中配置。一般用my-web-app.war这样的文件部署或者通过命令行以集群的形式部署，也可以把它按一个文件夹的形式放在webapps目录下。

在resin.xml配置文件中，web-app可以用<web-app>配置在<host>中或用<web-app-deploy>标签的形式隐式配置。web-app共享<web-app-default>中的公共配置。<web-app-deploy>指定一个webapps目录。

web-app标签的范围内也可放置资源环境，我们可以放置共享资源如数据库，缓存，CDI服务和队列。host也可以定义URL映射规则。

9.      Rewrite：控制URL映射

详细配置见：rewrite/dispatchconfiguration

如果URL需要做变动或想要更美观的URL，你需要控制URL格式或映射URL，resin的rewrite标签可以帮到你。rewrite的功能类似于Apache的mod_rewrite，同时也集成了resin的HTTP和servlet映射功能。

举个例子， wiki需要改变易读URL（readable URL）为servlet可识别的URL来读取参数。以下例子中服务允许接收*.php，*.gif等后缀的URL请求，所有的请求都可以对应到一个页面。它同时也重定向所有其他的URL到/index.php页面。

例子：wiki的分发规则

<web-appxmlns="http://caucho.com/ns/resin"  xmlns:resin="urn:java:com.caucho.resin"><resin:Dispatchtarget="\.(php|gif|css|png|js)"/><resin:Dispatch>  <resin:IfFileExists/></resin:Dispatch><resin:Dispatchregexp="^" target="/index.php"/> </web-app>

Resin的负载均衡，http代理和fast-cgi都再重定向规则里配置。这意味着你可以让HTTP请求由一个web-app处理或者一组后端服务集群处理。

例子：负载均衡

<web-appxmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin">    <resin:LoadBalanceregexp="^/test" cluster="backend-cluster"/></web-app>

10.  负载均衡：用于对多个后端服务器负载均衡

详细配置说明见：loadbalancing configuration

Resin的HTTP负载均衡基于轮询机制分配后端服务器的HTTP流量，在服务器发生故障时可自动切换。负载均衡基于resin的集群，当有添加或删除server的情况时可以自动弹性处理。

负载均衡基于重定向操作，soket参数和超时标准可以在<server>中配置。它可以识别服务器是否有效，超时或过载。

例：负载均衡分发配置

<web-app xmlns="http://caucho.com/ns/resin"  xmlns:resin="urn:java:com.caucho.resin">    <resin:LoadBalanceregexp="^/test" cluster="backend-cluster"/> </web-app>

例：负载均衡超时时间配置

<resinxmlns="http://caucho.com/ns/resin" xmlns:resin="urn:java:com.caucho.resin"><clusterid="backend-cluster>             <server id="a"address="192.168.1.10" port="6800">   <load-balance-socket-timeout>60<load-balance-socket-timeout>   <load-weight>200<load-balance-weight>  </server>  ...

11.  日志：JDKjava.util.logging

详细配置方法见：loggingconfiguration

Resin的日志打印基于JDK的java.util.logging。另外，watchdog会把控制台输出打印到log/jvm-server.log。

JDK的日志打印模块由两个元素构成：log handler和logger。log handler获得日志信息并处理。Resin进行基本的日志格式化并将日志保存到日志文件中。Java代码中使用JDK logger来发送信息。每一个logger都有一个名字，通常命名为java类的名字，并在日志中打印带着个名字标识的日志。比如"com.caucho.util.ThreadPool"。

通过配置，我们可以设置日志的名称和日志等级。日志等级对所有的log-handler生效，设置之后只有符合等级的日志才会被打印。因此一些handler会收到所有的日志信息，但是logger只会接受info等级的信息。

以下log-handler发送所有日志信息到JVM的控制台输出。它也接受所有info等级的日志和MyBean的finer等级日志。所以控制台输出会包含所有的info和finer日志。

例：基本日志配置

<resinxmlns:resin="urn:java:com.caucho.resin">  <log-handler name=""level="all" path="stdout:"               timestamp="[%y-%m-%d%H:%M:%S.%s] {%{thread}} "/>  <logger name=""level="info"/>  <logger name="com.foo.MyBean"level="finer"/>  ...</resin>

12.  resource：数据库，队列，缓存

详细配置见：database configuration

可以用标准XML语法配置所有基于java开发的resource，比如说ActiveMQ队列。Resin可以把resource注册为CDI或JNDI形式，便于应用使用。

一些常用的资源，比如数据库，Resin有专门的标签用于配置。大多数使用基于CDI的形式。

resource和web-app、host、cluster一样使用class-loader环境。因为环境之间是独立的，web-app/foo中的一个foo数据库配置不会影响web-app/bar。

CDI形式的配置是java类与XML之间的直接关联。你可以实例化Java beans，配置他们的CDI标签和属性，然后把它注入其他beans。

举个例子，以下配置配置了一个Resin集群式jcache，它可以以@Inject Named的形式注入任意一个应用。也可以说，你的应用可以使用CDI形式获取jcache实例以及其他Resin配置的实例。

ClusterCache实例在集群之间共享缓存数据。

例：jcache配置

<web-app xmlns="http://caucho.com/ns/resin"       xmlns:resin="urn:java:com.caucho.resin"        xmlns:ee="urn:java:ee">  <resin:ClusterCacheee:Named="test-cache" resin:Jndi="cache/test">   <expire-timeout>1h</expire-timeout>  </resin:ClusterCache>       </web-app>

13.  健康：监控，操作，与报告

详细配置方法见：healthconfiguration

Resin的健康系统持续监控服务器的健康。

·sensors（传感器）：收集Resin内部状态数据。

·meters：保存传感器和JMX数据在内部数据库。

·health-checks：评估Resin系统的健康。

·actions：执行具体操作来处理Resin健康问题。如：发送邮件，收集更多细节信息，或重启服务。

·reports：对服务器历史情况生成pdf报告。

a)        健康检查

运行健康检查需要几分钟时间。期间会检查JVM状态，返回简单的响应来告知服务器的健康状态是OK，WARNING，CRITICAL或者FATAL。如果你使用Nagios管理工具，这个过程是很类似的。Resin有几项固定的健康检查项，它很直接地描述一个用户自定义健康检查。

健康检查的结果中会记录这次检查是否通过，可以设置触发动作比如说发邮件或重启服务。

在下面这个例子中，JvmDeadlockHealthCheck包含了JVM的线程死锁检测。如果检测到线程死锁，健康检查的结果将会是fatal（致命的）。MemoryTenuredHealthCheck用于检测JVM的空闲空间。如果空闲空间过小，他会强制进行一次堆垃圾回收。如果垃圾回收也失败了，则返回一个critical结果。

例：健康检查

<resinxmlns="http://caucho.com/ns/resin"         xmlns:resin="urn:java:com.caucho.resin"><cluster-default>  <health:JvmDeadlockHealthCheck/>  <health:MemoryTenuredHealthCheck>   <memory-free-min>1m</memory-free-min>  </health:MemoryTenuredHealthCheck></cluster-default></resin>

b)        健康操作

健康操作可以根据健康检查结果，JMX值或者根据定时事件触发。每分钟Resin会检测一次是否符合条件启动某个健康操作。

内置的操作有：重启，生成报告，发送邮件，收集信息比如线程快照，执行自定义的PHP页面。自定义操作也可以简单地实现。

以下例子展示了当健康检查结果是fatal或持续处于critical状态超过5分钟时对resin执行重启操作。

例：重启操作

<resinxmlns="http://caucho.com/ns/resin"         xmlns:resin="urn:java:com.caucho.resin"><cluster-default>  <health:Restart>    <health:Or>      <health:IfHealthFatal/>      <health:IfHealthCriticaltime="5m"/>    </health:Or>  </health:Restart>... </cluster-default>...</resin>

c)        健康仪

健康仪收集每分钟的数据然后记录在内部数据库里。这些数据用于展示在/resin-admin中或者生成PDF报告。

以下两个例子来自默认的health.xml配置文件，配置中使用内部的JDK MBeans来存储JDK数据。第一个例子保存了操作系统的屋里存储数据。第二个meter每60s保存一次JIT编译时间。

例：JMX meters

<resin xmlns="http://caucho.com/ns/resin"          xmlns:resin="urn:java:com.caucho.resin"><cluster-default>  <health:JmxMeter>    <name>OS|Memory|Physical MemoryFree</name>   <objectName>java.lang:type=OperatingSystem</objectName>   <attribute>FreePhysicalMemorySize</attribute>  </health:JmxMeter>   <health:JmxDeltaMeter>    <name>JVM|Compilation|CompilationTime</name>   <objectName>java.lang:type=Compilation</objectName>   <attribute>TotalCompilationTime</attribute>  </health:JmxDeltaMeter>... </cluster-default>...</resin>

d)        健康报告

PDF报告中可以自定义选择图或测量数据。每个图包含一组检测数据。比如，一个关于线程的图标可以展示JDK处于不同状态的线程数量（runnable，blocke等等），可以表现出Resin的线程池状态。

例：汇总报告

<resinxmlns="http://caucho.com/ns/resin"         xmlns:resin="urn:java:com.caucho.resin"><cluster-default>  <health:MeterGraphPage>    <name>Summary</name>    <period>6h</period>    <columns>3</columns>    <graph name="RequestCount">      <meter>Resin|Http|RequestCount</meter>    </graph>    <graph name="Threads">      <meter>JVM|Thread|JVM ThreadCount</meter>      <meter>Resin|Thread|ThreadCount</meter>      <meter>Resin|Thread|Thread IdleCount</meter>      <meter>JVM|Thread|JVM RunnableCount</meter>      <meter>JVM|Thread|JVM BlockedCount</meter>      <meter>JVM|Thread|JVM NativeCount</meter>      <meter>JVM|Thread|JVM WaitingCount</meter>    </graph></cluster-default></resin>

14.  安全：身份验证与权限约束

详细配置方法见：securityconfiguration

安全项可以使用CanDI型的资源或者使用servlet <security-constraints>来配置。

·autenticator（身份验证）：检查用户的身份证明（密码）。

·登陆：通过HTTP/servlet验证身份并得到证明。

·constraints（权限约束）：允许或不允许用户访问某些资源。

以下例子使用基本的表单登陆来保护/admin.jsp页面的访问。只有用户有admin权限才可以访问。<resin: XmlAuthenticator>配置身份验证源（基于文件）。<resin:FormLogin>配置了登陆表单。<resin:Allow>限制了可以访问的页面。

例：表单登陆验证

<web-appxmlns:resin="urn:java:com.caucho.resin">   <resin:XmlAuthenticator>    <user name="admin"            password="{SSHA}h5QdSulQyqIgYo7BIJ3YfnRSY56kD847"             role="user,admin"/>  </resin:XmlAuthenticator>   <resin:FormLogin>    <login-page>/login.jsp</login-page>    <error-page>/form_error.jsp</error-page>  </resin:FormLogin>   <resin:Allowurl-pattern="/admin.jsp">     <resin:IfUserInRolerole="admin"/>  </resin:Allow></web-app>