J2EE完全参考手册-J2EE部署-pdf.pdf

第 6 章 J2EE 部署 J2EE 部署体系定义了一些协议，使来自不同供应商的部署工具能在任意 J2EE 平台产 品上配置和部署应用程序 （该目标由一个定义于开发工具和 J2EE 平台产品间的统一模型实 现） ；它使得应用程序部署更加容易：部署者不需要为了在不同的平台上部署一个应用程序 而了解所有工具的细节。本章将按如下顺序提供 J2EE 部署技术参考。 ? J2EE 部署简介 ? javax.enterprise.deploy.model 包 API 参考 ? javax.enterprise.deploy.shared 包 API 参考 ? javax.enterprise.deploy.shared.factories 包 API 参考 ? javax.enterprise.deploy.spi 包 API 参考 ? javax.enterprise.deploy.spi.exceptions 包 API 参考 ? javax.enterprise.deploy.spi.factories 包 API 参考 ? javax.enterprise.deploy.spi.status 包 API 参考 6.1 J2EE 部署体系 在 J2EE 部署体系中，表示 J2EE 平台产品所需要的动态部署配置信息的组件采用了 JavaBeans 结构，因为这种结构既适于表示简单又适用于表示复杂组件，同时它还有很强的 平台无关性。这些 Beans 使得开发简单的属性页、编辑器和复杂的定制向导（它可以引导 部署者完成应用程序部署配置各步骤）成为易事。 J2EE 部署 API 包括如下内容： ? J2EE 平台产品必须实现的一套最小工作集。所有的 J2EE 平台产品提供商都必须 向工具提供商提供这套工作集的实现，它使得可移植应用程序可部署到不同的 J2EE 平台产品上。 ? 部署工具所必须实现的一套最小工作集。所有的 J2EE 工具提供商都必提供这套 工作集的实现，以与不同的 J2EE 平台产品交互。 这套 API 描述了三个部署步骤中的两步：安装与配置，第三步（运行）留给了 J2EE 平台产品提供商。这些提供商可以在其自己的部署工具中扩展上述最小工作集以与其他厂 商竞争，这些扩展可能对其他厂商的部署工具不可用。 J2EE 部署 API 由七个包组成。其中一个包（javax.enterprise.deploy.model）由部署工具 提供商实现；四个包（javax.enterprise.deploy.spi 及其三个子包）由 J2EE 产品提供商实现； 另外两个包（javax.enterprise.deploy.shared 和 javax.enterprise.deploy.shared.factories）直接由 这套 API 提供，定义部署工具和 J2EE 平台所共享使用的对象或常数。 第 6 章 J2EE 部署 ·2· 6.1.1 J2EE 产品提供商（J2EE Product Provider） J2EE 产品提供商是 J2EE 兼容产品的实现者和提供者， J2EE 产品提供商角色通常由操 作系统供应商、数据库系统供应商、应用程序服务器供应商或 Web 服务器供应商担任。 J2EE 部署体系为 J2EE 产品部署定义了需求，J2EE 产品的主要任务如下： ? 产生产品专用的部署配置信息。 ? 部署应用程序。 J2EE 产品提供商负责实现 javax.enterprise.deploy.spi 包及其子包内所有接口， 它所提供 的产品必须能与任何遵循 J2EE 部署 API 规范（Java 2 Enterprise Edition Deployment API Specification）的第三方部署工具交互。为此它必须提供如下对象的实现： ? 一个部署管理器（Deployment Manager） 。 ? 部署类厂（Deployment Factories） ，以访问其产品的部署管理器。 ? 其产品所需要的部署配置组件。 图 6-1 描述了 javax.enterprise.deploy.model 包及其子包中几个重要接口之间的关系， 图 中接口的详细描述请参考 6.56.8 节内容。 第 6 章 J2EE 部署 ·3· 图 6-1 J2EE 平台产品部署接口逻辑关系图 6.1.2 工具提供商（Tool Provider） 在开发与包装应用程序组件、部署、管理或监控应用程序时，通常需要使用一些软件 工具， 工具提供者即是这些软件工具的实现者和供应商。 工具提供商角色通常由 J2EE 产品 提供商（为其产品提供工具） 、集成开发环境（IDE）提供商或专门的工具提供商担任。 J2EE 部署体系为部署工具定义了需求，部署工具的主要任务如下： ? 访问 J2EE 应用程序档案。 ? 操作从 J2EE 平台产品中检索到的部署配置信息。 部署工具提供商负责实现 javax.enterprise.deploy.model 包内的所有接口， 此外部署工具 必须提供一种方法以搜索指定的 J2EE 产品部署管理器并与之交互， 以及操作由它提供的配 置 Beans。 图 6-2 描述了 javax.enterprise.deploy.model 包中几个重要接口之间的关系， 图中部署对 第 6 章 J2EE 部署 ·4· 象为 J2EE 应用程序 eshop.ear，该文件包括了一个自身的部署描述符和两个子模块： customer.jar（EJB 模块）和 s.war（WEB 模块） 。部署工具为这些模块和部署描述符分别创 建了各种对象，这些对象的描述请参考 6.2 节。 图 6-2 J2EE 应用程序部署工具接口逻辑关系图 6.1.3 部署者（Deployer） 部署者负责在某一 J2EE 产品上配置与部署 J2EE 模块，部署通常可以分为三个阶段： ? 配置（Configuration） ：部署者按照应用组合者的组装指令并获取所有应用程序组 件提供者所声明的外部资源。 ? 分配 （Distribution） ： 应用程序档案和部署配置信息通过部署 API 安装到服务器上。 ? 开始执行（Start execution） ：部署者请求服务器开始运行应用程序。 第 6 章 J2EE 部署 ·5· 6.2 javax.enterprise.deploy.model 包 javax.enterprise.deploy.model 包内的所有接口由工具提供商实现，图 6-3 描述了 javax.enterprise.deploy.model 包的层次结构，下面两节将分别介绍其接口和类。 图 6-3 javax.enterprise.deploy.model 包结构 6.2.1 接口 DDBean J2EE Deployment API 1.0 javax.enterprise.deploy.model DDBean（即 Deployment Descriptor Bean）接口通常与其子接口 DDBeanRoot（最顶层 的 DDBean） 配合使用。 在部署 J2EE 应用程序时， 每一个部署描述符都与一个 DDBeanRoot 对象关联，一个 DDBeanRoot 对象即是一个指向部署描述符根部的引用；同时一个部署描 述符还与零个或多个 DDBean 对象关联，每一个 DDBean 对象代表部署描述符的一段，该 bean 对象包括一个 XML 标记的文本。 DDBean 和 DDBeanRoot 接口的主要功能是根据平台产品提供商的代码从部署描述符 中读取数据。 接口定义： 第 6 章 J2EE 部署 ·6· public interface DDBean / 公共实例方法 void addXpathListener(String xpath, XpathListener xpl); DDBean getChildBean(String xpath); String getId(); DDBeanRoot getRoot(); String getText(); String getText(String xpath); String getXpath(); void removeXpathListener(String xpath, XpathListener xpl); 子接口：DDBeanRoot 传递给：javax.enterprise.deploy.spi.DConfigBean.getDConfigBean(), javax.enterprise.deploy.model.XpathEvent.XpathEvent() 返回自：javax.enterprise.deploy.spi.DConfigBean.getDDBean() addXpathListener 语法：void addXpathListener(String xpath, XpathListener xpl) 描述：addXpathListener方法为一个特定的XPath登记一个监听器，以监视各种事件。 参数：xpath：XPath字符串，监听器所登记监视的路径；xpl：监听器对象。 getChildBean 语法：DDBean getChildBean(String xpath) 描述：getChildBean方法获取基于指定Xpath的DDBean列表。 参数：xpath：XPath字符串，指向当前bean所在的部署描述符中的一个位置。 返回：DDBean列表，若没有找到匹配的xml数据则返回空值。 getId 语法：String getId() 描述：getId方法获取XML文档中该bean定义的XML标记ATTLIST ID的值。 返回：该 bean 相应的 ATTLIST ID 文本，若该标记没有指定任何属性则返回空值。 getRoot 语法：DDBeanRoot getRoot() 第 6 章 J2EE 部署 ·7· 描述：getRoot方法获取该DDBean树根元素。 返回：位于该 DDBean 树根部的 DDBeanRoot 对象。 getText I 语法：String getText() 描述：getText方法获取关联该bean的XML文本。 返回：部署描述符中与该 bean 关联的 XML 文本。 getText II 语法：String getText(String xpath) 描述：getText方法获取部署描述符中由xpath指定的文本列表。 参数：xpath：XPath字符串，指向部署描述符中的某个位置。 返回：由参数xpath指定的文本列表，若找不到匹配的XML文本，则返回空值。 getXpath 语法：String getXpath() 描述：getXpath方法返回部署描述符中该bean关联的XPath。 返回：部署描述符中该bean关联的XPath。 removeXpathListener 语法：void removeXpathListener(String xpath, XpathListener xpl) 描述：removeXpathListener方法注销参数xpath上的某个监听器。 参数：xpath：待注销的监听器所指定监听的路径；xpl：待注销监听器对象。 DDBeanRoot J2EE Deployment API 1.0 javax.enterprise.deploy.model DDBeanRoot 是最顶层的 DDBean，对应于一个部署描述符。一个 DDBeanRoot 对象即 是一个指向部署描述符根部的引用，它与 DDBean 接口配合工作，根据平台产品提供商的 代码从部署描述符中读取数据。 第 6 章 J2EE 部署 ·8· 接口定义： public interface DDBeanRoot extends DDBean / 公共实例方法 ModuleType getType(); DeployableObject getDeployableObject(); String getModuleDTDVersion(); String getXpath(); 层次： DDBeanRoot (DDBean) 传递给：javax.enterprise.deploy.spi.DeploymentConfiguration.restoreDConfigBean(), javax.enterprise.deploy.spi.DeploymentConfiguration.getDConfigBeanRoot(), 返回自：DDBean.GetRoot(),javax.enterprise.deploy.model.DeployableObject.getDDBeanRoot() getDeployableObject 语法：DeployableObject getDeployableObject() 描述：getDeployableObject方法获取包含该部署描述符的Deployable对象。 返回：包含与该DDBeanRoot对应的部署描述符的Deployable对象。 getModuleDTDVersion 语法：String getModuleDTDVersion() 描述：getModuleDTDVersion方法获取XML文档（即DDBeanRoot所对应的的部署描述 符文件）中DOCTYPE表达式所包含的DTD版本号。 返回：包含DTD版本号的字符串。 getType 语法：ModuleType getType() 描述：getType方法获取部署描述符对应的可部署对象的模块类型（ModuleType） ， ModuleType类型请参考javax.enterprise.deploy.share包，它定义了J2EE模块类型 的枚举值（CAR、JAR、WAR、RAR或EAR） 。 返回：部署描述符对应的可部署对象的模块类型（ModuleType） 。 getXpath 语法：String getXpath() 第 6 章 J2EE 部署 ·9· 描述：getXpath方法返回部署描述符中该bean关联的XPath，因为DDBeanRoot为最顶 层（根部）DDBean，因此其XPath应为“/“。 返回：“/“。 DeployableObject J2EE Deployment API 1.0 javax.enterprise.deploy.model DeployableObject 接口是一个可部署的 J2EE 模块（CAR、JAR、WAR、RAR 或 EAR） 的抽象表示，它提供对模块部署描述符和类文件的访问方法。一个 DeployableObject 对象 维护了对该模块内部署描述符、DDBeanRoot 和所有 DDBean 的引用。 接口定义： public interface DeployableObject / 公共实例方法 ModuleType getType(); DDBeanRoot getDDBeanRoot(); DDBean getChildBean(String xpath); String getText(String xpath); Class getClassFromScope(String className); String getModuleDTDVersion(); 子接口：J2eeApplicationObject 返回自：javax.enterprise.deploy.model.DDBeanRoot.getDeployableObject(), javax.enterprise.deploy.spi.DeploymentConfiguration.getDeployableObject(), javax.enterprise.deploy.model.J2eeApplicationObject.getDeployableObject() getChildBean 语法：DDBean getChildBean(String xpath) 描述：getChildBean方法获取标准DDBean数组，这些bean代表基于指定XPath的XML 文本。 参数：xpath：XPath 字符串，标识将从部署描述符中读取的数据。 返回：DDBean数组，若找不到与指定xpath匹配的数据则返回空值。 第 6 章 J2EE 部署 ·10· getClassFromScope 语法：Class getClassFromScope(String className) 描述：getClassFromScope方法从当前可部署模块中抽取指定的类。 参数：className：待读取的类名。 返回：所读取的Class对象。 getDDBeanRoot 语法：DDBeanRoot getDDBeanRoot() 描述：getDDBeanRoot方法获取代表部署描述符的顶层bean。 返回：代表部署描述符的DDBeanRoot对象。 getModuleDTDVersion 语法：String getModuleDTDVersion() 描述：getModuleDTDVersion方法获取XML文档（即该J2EE模块的部署描述符文件） 中DOCTYPE表达式所包含的DTD版本号。 返回：包含DTD版本号的字符串。 getText 语法：String getText(String xpath) 描述：getText方法获取部署描述符中由参数xpath确定的XML文本。 参数：xpath：XPath字符串，指向部署描述符中某个位置。 返回：由参数xpath指定的文本列表，若找不到匹配的XML文本，则返回空值。 getType 语法：ModuleType getType() 描述：getType方法获取可部署对象的模块类型（ModuleType） ，ModuleType类型请参 考javax.enterprise.deploy.share包， 它定义了J2EE模块类型的枚举值 （CAR、 JAR、 WAR、RAR或EAR） 。 返回：可部署对象的模块类型（ModuleType） 。 第 6 章 J2EE 部署 ·11· J2eeApplicationObject J2EE Deployment API 1.0 javax.enterprise.deploy.model J2eeApplicationObject 是一种特殊的 DeployableObject 接口，它代表一个 J2EE 应用程 序（EAR） ；J2eeApplicationObject 对象是其内部各子模块与部署描述符的抽象容器，并为 其内的每一个子模块维护一个 DeployableObject 对象。 J2eeApplicationObject 接口的主要功能是提供对 EAR 内部成员的访问方法。 接口定义： public interface J2eeApplicationObject extends DeployableObject / 公共实例方法 public DeployableObject getDeployableObject(String uri); public DeployableObject getDeployableObjects(ModuleType type); DeployableObject getDeployableObjects(); String getModuleUris(ModuleType type); String getModuleUris(); public DDBean getChildBean(ModuleType type,String xpath); public String getText(ModuleType type, String xpath); void addXpathListener(ModuleType type, String xpath, XpathListener xpl); void removeXpathListener(ModuleType type, String xpath, XpathListener xpl); 层次： J2eeApplicationObject(DeployableObject) addXpathListener 语法：void addXpathListener(ModuleType type, String xpath, XpathListener xpl) 描述：addXpathListener方法为参数xpath（xpath的检索范围为指定类型的所有部署描 述符）注册监听器，以监视其变化。 参数：type：待查询的部署描述符类型；xpath：所监听的路径；xpl：监听器对象。 getChildBean 语法：public DDBean getChildBean(ModuleType type,String xpath) 描述：getChildBean方法获取基于参数xpath（xpath的检索范围为指定类型的所有部署 描述符）的DDBean列表。 参数：type：待查询的部署描述符类型；xpath：XPath路径字符串，指向部署描述符中 的某个位置。 返回：DDBean列表，若没有找到匹配的xml数据则返回空值。 第 6 章 J2EE 部署 ·12· getDeployableObject 语法：public DeployableObject getDeployableObject(String uri) 描述：getDeployableObject方法获取由参数uri指定的Deployable对象。 参数：uri：待获取的模块路径。 返回：由uri指定的J2EE模块（Deployable对象） ，若找不到与uri匹配的模块则返回空值 。 getDeployableObjects I 程序：public DeployableObject getDeployableObjects() 描述：getDeployableObjects方法获取该应用程序内的所有可部署对象（模块） 。 返回：DeployableObject对象数组。 getDeployableObjects II 程序：public DeployableObject getDeployableObjects(ModuleType type) 描述：getDeployableObjects 方法获取特定类型的所有 Deployable 对象（模块） 。 参数：type：指定模块类型。 返回：DeployableObject 对象数组；若不存在该类型的模块，则返回空值。 getModuleUris I 语法：public String getModuleUris() 描述：getModuleUris 方法获取该应用程序内所有模块的 URI 列表。 返回：所有模块的 URI 构成的数组。 getModuleUris II 语法：public String getModuleUris(ModuleType type) 描述：getModuleUris 方法获取应用程序内指定类型模块的 URI 列表。 参数：type：指定模块类型。 返回：指定类型模块的 URI 构成的数组，若不存在 type 类型的模块，则返回空值。 getText 语法：public String getText(ModuleType type, String xpath) 第 6 章 J2EE 部署 ·13· 描述：getText 方法获取由 xpath 指定的文本列表 （只搜索指定类型模块的部署描述符） 。 参数：type：指定待搜索模块类型；xpath：XPath 字符串，指向部署描述符中的某个 位置。 返回：由xpath指定的文本列表，若找不到匹配的XML文本，则返回空值。 removeXpathListener 语法：void removeXpathListener(ModuleType type, String xpath, XpathListener xpl) 描述：removeXpathListener 方法注销参数 xpath 上的某个监听器（只搜索指定类型模 块的部署描述符） 。 参数：type：待查询模块类型；xpath：待注销的监听器所指定监听的路径；xpl：待注 销监听器对象。 XpathListener J2EE Deployment API 1.0 javax.enterprise.deploy.model XpathListener 是一个监听接口，它用于接收 XpathEvents 事件（BEAN_ADDED、 BEAN_REMOVED 或 BEAN_CHANGED） 。 接口定义： public interface XpathListener / 公共实例方法 void fireXpathEvent(XpathEvent xpe); 传递给：javax.enterprise.deploy.model.J2eeApplicationObject.addXpathListener(), javax.enterprise.deploy.model.DDBean.addXpathListener(), javax.enterprise.deploy.model.J2eeApplicationObject.removeXpathListener(), javax.enterprise.deploy.model.DDBean.removeXpathListener() 第 6 章 J2EE 部署 ·14· 6.2.2 类 XpathEvent J2EE Deployment API 1.0 javax.enterprise.deploy.model XpathEvent 是一个事件类，表示在部署配置过程中加入、删除或改变 DDBean 对象事 件；这三种事件分别对应于其 BEAN_ADDED、BEAN_REMOVED 或 BEAN_CHANGED 字段。开发者可使用 XpathEvent 类的公共实例方法 isAddEvent()、isRemoveEvent()和 isChangeEvent()查询 XpathEvent 实例究竟对应那一种事件。 XpathEvent 类有两个私有属性：bean（只读）和 type（读写，表示事件类型，值可为 BEAN_ADDED、BEAN_CHANGED 或 BEAN_CHANGED） ，在构造函数中必须指定这两 者的初始值。 类定义： public final class XpathEvent /字段 private final DDBean bean; private final Object typ; private PropertyChangeEvent changeEvent; public static final Object BEAN_ADDED; public static final Object BEAN_REMOVED; public static final Object BEAN_CHANGED; /构造函数 public XpathEvent(DDBean dDBean, Object object); /公共实例方法 public PropertyChangeEvent getChangeEvent(); public void setChangeEvent(PropertyChangeEvent propertyChangeEvent); public DDBean getBean(); public boolean isAddEvent(); public boolean isRemoveEvent(); public boolean isChangeEvent(); 传递给：javax.enterprise.deploy.model.XpathListener. fireXpathEvent(), javax.enterprise.deploy.spi.DconfigBean.notifyDDChange() 第 6 章 J2EE 部署 ·15· 6.3 javax.enterprise.deploy.shared 包 工具提供商（Tool Provider）和平台产品提供商（Platform Product Provider）使用了一 些共享对象或常量，这些对象分为五个类，由 javax.enterprise.deploy.shared 提供。 图 6-4 描述了 javax.enterprise.deploy.shared 包的层次结构，下面将分别介绍这五个类。 图 6-4 javax.enterprise.deploy.shared 包结构 ActionType J2EE Deployment API 1.0 javax.enterprise.deploy.shared ActionType 类提供一些由 DeploymentStatus 接口使用的枚举值， DeploymentStatus 接口 通过 getAction 方法获取枚举值以判断何种动作发生在当前操作上。 ActionType 类有三个静态（类）字段（即枚举值，为 ActionType 类型） ：EXECUTE、 CANCEL 和 STOP，分别表示 DeploymentManager 作用指令（action command）正在执行、 取消或停止。ActionType 类的 getActionType 方法将返回指定参数所对应的枚举值。 此外 javax.enterprise.deploy.shared 包内的所有类都有五个同名方法：getValue、 getEnumValueTable、 toString、 getStringTable 和 getOffset， 其中 getValue 方法返回该对象 （也 是一个枚举值）所对应的整数值，getEnumValueTable 方法返回该类所支持的所有枚举值列 表；toString 方法返回该实例（枚举值）名称字符串（若超出枚举值范围，则直接返回整数 串） ， getStringTable 方法返回该类所支持的所有枚举值名称字符串列表； getOffset 方法返回 该枚举值与该类所支持最小枚举值之间的差值。 第 6 章 J2EE 部署 ·16· 类定义： public class ActionType /公共类字段 public static final ActionType EXECUTE; public static final ActionType CANCEL; public static final ActionType STOP; /构造函数 protected ActionType(int value); /方法 public int getValue(); protected String getStringTable(); protected ActionType getEnumValueTable(); public static ActionType getActionType(int value); public String toString(); protected int getOffset(); 层次： ActionType(java.lang.Object) 返回自：javax.enterprise.deploy.spi.status.DeploymentStatus.getAction(), ActionType.getActionType() CommandType J2EE Deployment API 1.0 javax.enterprise.deploy.shared CommandType 类提供一些枚举值以供 DeploymentStatus 接口使用，DeploymentStatus 接口通过 getCommand 方法获取枚举值以判断它所代表的部署命令。 CommandType 类有五个静态 （类） 字段 （即相关枚举值） ： DISTRIBUTE、 REDEPLOY、 START、STOP 和 UNDEPLOY，分别表示 DeploymentManager 操作动作（action operation） 为分发 （distribute） 、 重新部署 （redeploy） 、 启动 （start） 、 停止 （stop） 或撤销部署 （undeploy） 。 CommandType 类的 getCommandType 方法将返回指定参数所对应的枚举值，其另外五 个方法功能与 ActionType 类的同名方法类似。 类定义： public class CommandType /公共类字段 static CommandType DISTRIBUTE; static CommandType REDEPLOY; static CommandType START; static CommandType STOP; static CommandType UNDEPLOY; 第 6 章 J2EE 部署 ·17· /构造函数 protected CommandType(int value); /方法 static CommandType getCommandType(int value) ; protected CommandType getEnumValueTable(); protected int getOffset(); protected String getStringTable(); int getValue(); String toString(); 层次： CommandType (java.lang.Object) 返回自：javax.enterprise.deploy.spi.status.DeploymentStatus.getCommand(), CommandType.getCommandType () DConfigBeanVersionType J2EE Deployment API 1.0 javax.enterprise.deploy.shared DConfigBeanVersionType 类提供版本号枚举值，这些枚举值标识编译部署描述 beans 和部署配置 beans 的 J2EE 版本号；当前该类只提供了两个版本值（V1_3 和 V1_3_1） 。 DConfigBeanVersionType 类的 getDConfigBeanVersionType 方法将返回指定参数所对应 的版本号，其另外五个方法功能与 ActionType 类的同名方法类似。