48.5. Apusic部署描述文件

独立的Web应用、EJB模块和完整的JavaEE应用都需要部署描述文件apusic-application.xml来配置Apusic相关的属性。apusic-application_5_0.dtd文件定义了apusic-application.xml的结构,确定了它能够包含的元素、子元素和元素的属性。定义在DTD中的元素能够包含:

元素能够包含子元素,例如下面的代码片断定义了apusic-application元素:

<!ELEMENT apusic-application (module*, mail-session*, security-role*)>

可以看出,元素apusic-application能够包含子元素moduls、mail-session和security-role。通过可选的后缀修饰子元素来决定能够包含子元素的数量。具体含义见下表:

子元素后缀含义
element*能够包含零或多个这种子元素
element?能够包含零或一个这种子元素
element+必须包含一个或多个这种子元素
element只能包含一个这种子元素

一些元素没有子元素而是包含字符数据。例如:

<!ELEMENT role-name (#PCDATA)>

在apusic-application.xml中就应该表现下面的形式。注意,字符数据前后都不要有空格:

<role-name>admin</role-name>

元素还能够带有属性,使用ATTLIST标记声明。声明的语法为:

<!ATTLIST element-name attribute-name
 attribute-type default-value>

例如,在apusic-application_4_0.dtd中为module元素定义了名称为uri的属性:

<!ATTLIST module uri CDATA #IMPLIED>

属性的类型(attribute-type)可以为下表中所列的值:

说明
CDATA字符数据
(en1|en2|..)必须为枚举列表中的一个值
ID唯一的ID
IDREF另外一个元素的ID
IDREFS其他元素ID列表
NMTOKEN一个有效的XML名称
NMTOKENS有效的XML名称列表
ENTITY实体
ENTITIES实体列表
NOTATION符合的名称
xml:预先定义的XML值

属性的缺省值(default-value)可以为:

说明
valuevalue为属性的缺省值
#REQUIRED元素必须包含这个属性值
#IMPLIED元素可以不包含这个属性值
#FIXED value属性值是固定值

48.5.1. apusic-application.xml中的元素

这一节将介绍apusic-application.xml中包含的元素。

48.5.1.1. apusic-application元素

apusic-application为根元素,包含下列子元素:

apusic-application元素

元素包含数量描述
module零个或多个代表单个Java EE模块,如Web、EJB模块
mail-session零个或多个 
security-role零个或多个安全角色映射

48.5.1.2. module元素

module元素代表单个Java EE模块,包含下列子元素之一:

module元素

module的子元素为枚举类型,因此它只包含四个子元素中的一个元素。

元素包含数量描述
connector其中一个暂不支持
ejb其中一个代表EJB模块
java其中一个代表应用客户端模块
web其中一个代表web应用模块

module元素还包含一个属性uri:

名称类型缺省值描述
uri字符#IMPLIED模块的URI,相对于应用的最顶层目录

48.5.1.3. ejb元素

ejb元素代表EJB模块,包含下列子元素:

ejb元素

元素包含数量描述
entity | session | message-driven一个或多个EJB的类型
relationship-mapping一个或多个CMP2.0关系映射
cmp-resource零个或一个CMP数据源JNDI名称

48.5.1.4. entity元素

entity元素代表entity bean,包含下列子元素:

entity元素

元素包含数量描述
jndi-name零个或一个指定jndi名称
local-jndi-name零个或一个指定本地jndi名称
cmp零个或一个配置Apusic相关的CMP属性
is-modified-method-name零个或一个指定is-modified方法,容器根据此方法返回的布尔值来决定是否调用ejbStore方法将信息存储到数据库。is-modified方法在BMP和CMP1.x的实体Bean中使用。CMP2.x的实体Bean采用另外的方式实现,无需设置is-modified方法。
ejb-ref零个或多个映射ejb-jar.xml中相应的EJB引用到JNDI名称
ejb-local-ref零个或多个映射ejb-jar.xml中相应的本地EJB引用到JNDI名称
resource-ref零个或多个映射ejb-jar.xml中相应的资源引用到JNDI名称
resource-env-ref零个或多个映射ejb-jar.xml中相应的资源环境引用到JNDI名称

entity元素还包含下列属性:

名称类型缺省值描述
ejb-name字符#REQUIRED匹配ejb-jar.xml中相应的ejb-name
pool-size字符#IMPLIED实例池容量,组件实例池的大小,单位为实例的个数
cache-size字符#IMPLIED缓冲池容量,可保存在EJB缓存中的EJB实例数
transaction-timeout字符#IMPLIED事务的超时时间值,单位为秒
concurrency-strategy字符#IMPLIED并发策略,可以为“Exclusive”,“Parallel”,“ReadOnly”。
  • Exclusive - 容器将维护一个实体Bean的内部缓存,当客户访问其中一个EJB实例时在该实例上设置互斥锁,当事务完成时释放互斥锁,保证所有的事务都是可串行化的。

  • Parallel - 容器将为每个并发访问的客户都分配一个EJB实例,每个事务独立执行,EJB实例状态和持久存储数据之间的同步由数据库系统完成。这种并发控制在EJB容器和数据库之间做的很薄,所以一般不推荐使用,只有在Exclusive方式下查询频繁出现死锁时才考虑使用这种模式。

  • ReadOnly - 实例在运行过程中永远不会执行任何INSERT/UPDATE/DELETE操作,并根据一个可配置的时间周期性读取最新的数据。使实例可以获得最大程度的并发执行。

force-refreshTrue|FalseFalse强制刷新,当concurrency-strategy被设置为“Exclusive”时有效,保证容器在每次事务开始时强制同步实例状态与持久存储中的状态数据。默认值为“False”。
delay-updatesTrue|FalseTrue已不使用
load-for-updateTrue|FalseFalse在SELECT语句中增加了一个FOR UPDATE子句,在读入数据时锁定数据行。
cmp11-promotion字符#IMPLIEDCMP1.1自动提升,对EJB1.1版本的容器管理持久性Entity Bean有效,在运行时是否需要将其自动升级为EJB2.1版本的容器管 理持久性Entity Bean运行。默认值为“True”。
expiration-time字符#IMPLIED缓冲过期时间,实例保持在就绪状态的最大空闲时间。单位是秒。

48.5.1.5. jndi-name元素

jndi-name元素指定JNDI名称,不包含子元素。例如:

<jndi-name>jdbc/Hello</jndi-name>

48.5.1.6. local-jndi-name元素

local-jndi-name元素指定本地JNDI名称,不包含子元素。

48.5.1.7. cmp元素

cmp元素代表Apusic相关的CMP配置信息,包含一个子元素jdbc。

48.5.1.8. jdbc元素

jdbc元素包含下列子元素:

jdbc元素

名称包含数量描述
datasource-name零或一个数据源JNDI名称,已不使用
table-name零或一个CMP映射的数据库表名
auto-create-table零或一个自动产生表,在数据库表不存在的情况下使用
auto-generate-key零或一个自动产生主键
field-mapping零或多个CMP域-数据库表列映射
load-unit零或多个装载单元,Apusic中对于容器管理持久性的Entity Bean,开发者可以通过将状态划分为不同的装载单元,实现Lazy Loading的特性
finder零或多个为CMP1.x find方法设置SQL子句

48.5.1.9. datasource-name元素

datasource-name不包含子元素,代表数据源JNDI名称,已不使用。

48.5.1.10. table-name元素

table-name元素代表CMP映射的数据库表名,不包含子元素。

48.5.1.11. auto-create-table元素

auto-create-table元素代表自动产生表,在数据库表不存在的情况下使用。

48.5.1.12. auto-generate-key元素

auto-generate-key元素代表自动产生主键。

48.5.1.13. field-mapping元素

field-mapping元素代表CMP域-数据库表列映射,包含下列子元素:

field-mapping元素

名称包含数量描述
field-name一个CMP域名称,必须匹配ejb-jar.xml中相应的cmp-field子元素field-name
column-name一个数据库表列名称

48.5.1.14. field-name元素

field-name元素代表CMP域名称,不包含子元素。

48.5.1.15. column-name元素

column-name元素代表数据库表列名称,不包含子元素。

48.5.1.16. load-unit元素

load-unit元素代表装载单元,包含下列子元素:

load-unit元素

名称包含数量描述
unit-name一个装载单元名称
cmp-field | cmr-field一个或多个CMP域和CMR域

48.5.1.17. unit-name元素

unit-name元素代表装载单元名称,不包含子元素。

48.5.1.18. cmp-field元素

cmp-field元素代表CMP域,必须匹配ejb-jar.xml中相应的cmp-field子元素field-name,不包含子元素。

48.5.1.19. cmr-field元素

cmr-field元素代表CMR域,必须匹配ejb-jar.xml中相应的cmr-field子元素cmr-field-name,不包含子元素。

48.5.1.20. finder元素

finder元素代表CMP1.x find方法,包含下列子元素:

finder元素

名称包含数量描述
description零或一个为父元素提供文本描述信息
method一个代表EJB home接口或组件接口中定义的方法
sql-clause一个CMP1.1查询语句

48.5.1.21. description元素

description元素为父元素提供文本描述信息,不包含子元素。

48.5.1.22. method元素

method元素代表EJB home接口或组件接口中定义的方法,包含下列子元素:

method元素

名称包含数量描述
description零或一个为父元素提供文本描述信息
method-intf零或一个用于区分home接口和组件接口中具有相同方法名和方法签名的方法。
method-name一个查询方法的名称
method-params零或一个方法参数列表

48.5.1.23. method-intf元素

method-intf元素用于区分home接口和组件接口中具有相同方法名和方法签名的方法,不包含子元素。method-intf元素必须为下面列表之一:

  • <method-intf>Home</method-intf>

  • <method-intf>Remote</method-intf>

  • <method-intf>LocalHome</method-intf>

  • <method-intf>Local</method-intf>

48.5.1.24. method-name元素

method-name元素代表查询方法的名称,不包含子元素。

48.5.1.25. method-params元素

method-params元素代表方法的参数列表,包含下列子元素:

method-params元素

名称包含数量描述
method-param零或多个方法参数的Java类型全名

48.5.1.26. method-param元素

method-param元素代表方法参数的Java类型全名,不包含子元素。

48.5.1.27. sql-clause元素

sql-clause元素代表CMP1.1的查询语句,不包含子元素。

48.5.1.28. is-modified-method-name元素

is-modified-method-name元素用来指定is-modified方法,容器根据此方法返回的布尔值来决定是否调用ejbStore方法将信息存储到数据库。is-modified方法在BMP和CMP1.x的实体Bean中使用。CMP2.x的实体Bean采用另外的方式实现,无需设置is-modified方法。

48.5.1.29. ejb-ref元素

ejb-ref元素用来映射ejb-jar.xml中相应的EJB引用到JNDI名称,包含下列子元素:

ejb-ref元素

名称包含数量描述
ejb-ref-name一个必须匹配ejb-jar.xml中相应的ejb-ref-name元素
jndi-name一个指定JNDI名称

48.5.1.30. ejb-ref-name元素

ejb-ref-name元素必须匹配ejb-jar.xml中相应的ejb-ref-name元素。该元素不包含子元素。

48.5.1.31. ejb-local-ref元素

ejb-local-ref元素用来映射ejb-jar.xml中相应的本地EJB引用到JNDI名称,包含下列子元素:

ejb-local-ref元素

名称包含数量描述
ejb-ref-name一个必须匹配ejb-jar.xml中相应的ejb-ref-name元素
jndi-name一个指定JNDI名称

48.5.1.32. resource-ref元素

resource-ref元素用来映射ejb-jar.xml中相应的资源引用到JNDI名称,包含下列子元素:

resource-ref元素

名称包含数量描述
res-ref-name一个必须匹配ejb-jar.xml中相应的resource-ref的子元素res-ref-name。
jndi-name一个指定JNDI名称

48.5.1.33. res-ref-name元素

res-ref-name元素必须匹配ejb-jar.xml中相应的resource-ref的子元素res-ref-name。该元素不包含子元素。

48.5.1.34. resource-env-ref元素

resource-env-ref元素用来映射ejb-jar.xml中相应的资源环境引用到JNDI名称,包含下列子元素:

resource-env-ref元素

名称包含数量描述
resource-env-ref-name一个必须匹配ejb-jar.xml中相应的resource-env-ref的子元素resource-env-ref-name。
jndi-name一个指定JNDI名称

48.5.1.35. resource-env-ref-name元素

resource-env-ref-name元素必须匹配ejb-jar.xml中相应的resource-env-ref的子元素resource-env-ref-name。该元素不包含子元素。

48.5.1.36. session元素

session元素代表session bean,包含下列子元素:

session元素

元素包含数量描述
jndi-name零个或一个指定jndi名称
local-jndi-name零个或一个指定本地jndi名称
ejb-ref零个或多个映射ejb-jar.xml中相应的EJB引用到JNDI名称
ejb-local-ref零个或多个映射ejb-jar.xml中相应的本地EJB引用到JNDI名称
resource-ref零个或多个映射ejb-jar.xml中相应的资源引用到JNDI名称
resource-env-ref零个或多个映射ejb-jar.xml中相应的资源环境引用到JNDI名称

session元素还包含下列属性:

名称类型缺省值描述
ejb-name字符#REQUIRED匹配ejb-jar.xml中相应的ejb-name
pool-size字符#IMPLIED实例池容量,组件实例池的大小,单位为实例的个数
cache-size字符#IMPLIED缓冲池容量,可保存在EJB缓存中的EJB实例数
session-timeout字符#IMPLIEDSession Bean组件实例的超时时间
transaction-timeout字符#IMPLIED事务的超时时间值,单位为秒

48.5.1.37. message-driven元素

message-driven元素代表message-driven bean,包含下列子元素:

message-driven元素

元素包含数量描述
message-driven-destination一个配置Apusic相关的message-driven bean目的地
ejb-ref零个或多个映射ejb-jar.xml中相应的EJB引用到JNDI名称
ejb-local-ref零个或多个映射ejb-jar.xml中相应的本地EJB引用到JNDI名称
resource-ref零个或多个映射ejb-jar.xml中相应的资源引用到JNDI名称
resource-env-ref零个或多个映射ejb-jar.xml中相应的资源环境引用到JNDI名称

message-driven元素还包含下列属性:

名称类型缺省值描述
ejb-name字符#REQUIRED匹配ejb-jar.xml中相应的ejb-name
pool-size字符#IMPLIED实例池容量,组件实例池的大小,单位为实例的个数

48.5.1.38. message-driven-destination元素

message-driven-destination元素用来配置Apusic相关的message-driven bean目的地,包含下列子元素:

message-driven-destination元素

名称包含数量描述
connection-factory-name零或一个连接工厂的JNDI名字
destination-name一个JMS消息目的地JNDI名字
auto-create-destination零或一个自动创建目的地
client-id零或一个客户端标识
durable-subscription-name零或一个持久订阅名称

48.5.1.39. connection-factory-name元素

connection-factory-name元素代表连接工厂的JNDI名字,不包含子元素。

48.5.1.40. destination-name元素

destination-name元素代表JMS消息目的地JNDI名字,不包含子元素。

48.5.1.41. auto-create-destination元素

auto-create-destination元素代表自动创建目的地,不包含子元素。

48.5.1.42. client-id元素

client-id元素客户端标识,不包含子元素。

48.5.1.43. durable-subscription-name元素

durable-subscription-name元素代表持久订阅名称,不包含子元素。

48.5.1.44. relationship-mapping元素

relationship-mapping元素代表Apusic相关的CMP2.0关系映射配置,包含下列子元素:

relationship-mapping元素

名称包含数量描述
ejb-relation-name一个必须匹配ejb-jar.xml中ejb-relation的子元素ejb-relation-name
table-name零或一个辅助表名。单向一对多、单向多对多和双向多对多需要辅助表
auto-create-table零或一个自动创建辅助表
source-role零或一个CMP2.0关系中的一个角色
sink-role零或一个CMP2.0关系中的另一个角色

48.5.1.45. ejb-relation-name元素

ejb-relation-name元素必须匹配ejb-jar.xml中ejb-relation的子元素ejb-relation-name。该元素不包含子元素。

48.5.1.46. source-role元素

source-role元素代表CMP2.0关系中的一个角色,包含下列子元素:

source-role元素

名称包含数量描述
field-mapping零或多个CMP域-外键映射

48.5.1.47. sink-role元素

sink-role元素代表CMP2.0关系中的一个角色,包含下列子元素:

sink-role元素

名称包含数量描述
field-mapping零或多个CMP域-外键映射

48.5.1.48. cmp-resource元素

cmp-resource元素代表CMP数据源JNDI名称,包含下列子元素:

cmp-resource元素

名称包含数量描述
jndi-name零或一个CMP数据源JNDI名称,是EJB模块中所有CMP实体EJB所使用的数据源

48.5.1.49. java元素

java元素代表应用客户端模块,包含下列子元素:

java元素

元素包含数量描述
ejb-ref零个或多个映射ejb-jar.xml中相应的EJB引用到JNDI名称
resource-ref零个或多个映射ejb-jar.xml中相应的资源引用到JNDI名称
resource-env-ref零个或多个映射ejb-jar.xml中相应的资源环境引用到JNDI名称

48.5.1.50. web元素

web元素代表web应用模块,包含下列子元素:

web元素

元素包含数量描述
context-root零个或一个web应用的上下文根路径
ejb-ref零个或多个映射ejb-jar.xml中相应的EJB引用到JNDI名称
ejb-local-ref零个或多个映射ejb-jar.xml中相应的本地EJB引用到JNDI名称
resource-ref零个或多个映射ejb-jar.xml中相应的资源引用到JNDI名称
resource-env-ref零个或多个映射ejb-jar.xml中相应的资源环境引用到JNDI名称

48.5.1.51. context-root元素

context-root元素代表web应用的上下文根路径,不包含子元素。

48.5.1.52. mail-session元素

mail-session元素包含下列子元素:

mail-session元素

元素包含数量描述
description零个或一个为父元素提供文本描述信息
jndi-name一个指定JNDI名称
property零个或多个配置mail-session属性信息,一个设置两个属性:“mail.host”和“mail.from”

48.5.1.53. property元素

property元素代表配置相关的属性信息,不包含子元素,但有两个属性:

名称类型缺省值描述
name字符#REQUIRED属性名称
value字符#REQUIRED属性值

48.5.1.54. security-role元素

security-role元素代表Java EE应用安全角色到Apusic用户的映射,包含下列子元素:

security-role元素

元素包含数量描述
role-name一个Java EE应用中定义的角色名
principal | group一个或多个Apusic应用服务器中的用户或组

48.5.1.55. role-name元素

role-name元素代表Java EE应用中定义的角色名,不包含子元素。

48.5.1.56. principal元素

principal元素代表Apusic应用服务器中的用户,不包含子元素。

48.5.1.57. group元素

group元素代表Apusic应用服务器中的用户,不包含子元素。