javax.xml.bind

Class JAXBContext

java.lang.Object

javax.xml.bind.JAXBContext

public abstract class JAXBContext
extends Object

的JAXBContext类提供客户的切入点，JAXB API。它用于管理XML / java绑定信息必要实现JAXB绑定框架操作提供一个抽象：解包，元帅和验证。

客户端应用程序通常使用newInstance方法得到其中一个款式这类的新实例，虽然有其他专业的方法形式：

• JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
  送的实例初始化列表中的冒号分隔的java包的名字。每个包中包含了java的JAXB映射类，图式派生类和/或用户注释的类。此外，java包可以包含JAXB包注释必须处理。（参见JLS，第7.4.1”命名的套餐”）。
• JAXBContext.newInstance( com.acme.foo.Foo.class )
  送实例初始化的类（ES）作为参数传递（S）和静态可从这些类的类（ES）。看到newInstance(Class...)详情。

规格要求：提供者必须提供包含以下方法签名的一个实现类：

公共静态JAXBContext createContext（字符串contextpath、ClassLoader classLoader、Map
 
        
        
        
      
        
      <字符串，对象>
       
         
       
         
         
         
  属性）抛出jaxbexception公共静态JAXBContext createContext（类[ ]类，Map
  
         
         
         
       
         
       <字符串>
         ，对象属性）抛出jaxbexception 
       
 
        
        
        
      
        
      

以下的JAXB 1要求只需要架构的java接口/实现结合。它不适用于JAXB注释的类。JAXB提供者必须生成每个包中含有一JAXB。性能模式派生的类文件。属性文件必须包含一个属性指定的值的名称javax. XML绑定。语境。厂实现createcontext类API。

类提供的供应商没有被分配到javax. XML绑定。JAXBContext，它只是提供一个类实现的createcontext API。

此外，供应商必须调用datatypeconverter.setdatatypeconverter API的编组和解组的任何客户端调用方法之前。这是必要的配置数据类型转换器，将在这些操作中的应用。

解组

的Unmarshaller类提供了客户端应用程序将XML数据转换成一棵树的java对象内容的能力。的编码解码方法允许任何全局XML元素中声明的模式来将它们分散为实例文档的根。此外，该分解方法可以识别的根元素，具有xsi：类型属性的值，类型定义中声明的模式来将它们分散为实例文档的根引用。的JAXBContext对象允许全球元素类型定义在一组模式的合并（在contextPath上市）。由于在架构设置每个模式可以属于不同的命名空间，架构一个统一命名空间解编排上下文应该独立。这意味着，客户端应用程序可以是任何数据的XML文档，在contextPath上市模式实例。例如:

JC =送送。newInstance（“COM。极致。foo：COM。极致。酒吧”）；配置createunmarshaller() U = JC；fooobject fooobj =（fooobject）u.unmarshal（新文件（“foo。XML”））；// OKbarobject barobj =（barobject）u.unmarshal（新文件（”吧。XML”））；// OKbazobject bazobj =（bazobject）u.unmarshal（新文件（“巴兹。XML”））；//错误，“COM。极致。巴兹”不contextpath

客户端应用程序可以生成java内容树明确而非解散现有的XML数据。所有的JAXB注释值类，应用程序可以使用构造函数创建内容。模式推导出的不绑定到JAXB注释类元素生成接口/实现类，应用程序需要对每个模式的派生类 ObjectFactory每个java包中包含的contextPath存在访问和知识。每个模式衍生的java类，有一个静态工厂方法生产该类型的对象。例如，假设经过编译模式，你有一个包裹com.acme.foo包含派生接口命名PurchaseOrder架构。为了创建该类型的对象，客户端应用程序将使用像这样的工厂方法：

com.acme.foo.purchaseorder宝=com。极致。foo。createpurchaseorder()化；

一旦客户端应用程序的架构派生类对象的一个实例，它可以使用赋值方法设置内容上。

在生成的ObjectFactory类的更多信息，见4.2节包java规范。

规格要求：提供者必须在每个包中包含所有的那个叫化以及静态newInstance（javacontentinterface）方法封装的必要对象工厂方法生成一个类

编组

的Marshaller类提供了客户端应用程序将一个java内容树回XML数据的能力。编组内容之间有树，手动使用工厂方法和编组内容树，结果unmarshal 创建操作无差异。客户可以看到java内容树返回XML数据到java.io.OutputStream或java.io.Writer。编组过程可以产生SAX2事件流的注册ContentHandler或产生一个DOM节点对象。客户端应用程序可以对输出编码进行控制，以及是否将XML数据作为一个完整的文档或作为一个片段封送。

这里是一个XML文档，然后将解封了一个简单的例子：

JC =送送。newInstance（“COM。极致。foo”）；从foo.xml /解包配置createunmarshaller() U = JC；fooobject fooobj =（fooobject）u.unmarshal（新文件（“foo。XML”））；/ /元帅到System.out指挥createmarshaller() M = JC；m.marshal（fooobj，System.out）；

验证

验证已自JAXB 1显著变化。的Validator类已经被弃用，可选。这意味着，你最好不要使用这个类，事实上，它甚至可能不可根据您的API提供商。JAXB 1客户端应用程序依赖于Validator仍然正常工作时使用JAXB 1运行系统。在2的Unmarshaller JAXB，包括方便的方法，使JAXP 1.3 javax.xml.validation框架。请参阅Unmarshaller.setSchema(javax.xml.validation.Schema) API的更多信息。

JAXB运行时绑定框架的兼容性

以下的JAXB 1限制只适用于结合模式接口实现类。由于这种结合不需要一个共同的运行系统，一个客户端应用程序不应该试图JAXB混合运行时对象（JAXBContext, Marshaller，等）从不同的供应商。这并不意味着客户端应用程序是不可移植的，它只是意味着一个客户端必须使用由同一个提供程序提供的运行时系统来编译模式。

JAXB实现发现

当一个人的newInstance方法被调用，JAXB实现是通过以下步骤发现。

1. 每包/类显式传递到newInstance(java.lang.String)方法，按指定的顺序，jaxb.properties文件放在包装中，利用相关的类装载器-这是一个类争论the owner class loader，和一包指定的ClassLoader。

   如果一个文件被发现，它是loaded作为属性文件，对JAXB_CONTEXT_FACTORY键的值将被假定为是供应商的工厂类。这个类是通过类加载器加载相关讨论。

   这一阶段的抬头让一些包力一定使用JAXB实现。（例如，架构编译器可能在代码中生成了一些供应商扩展。）

2. 如果系统性能JAXB_CONTEXT_FACTORY存在，那么它的价值被认为是供应商的工厂类。这一阶段的抬头使每个JVM的JAXB实现覆盖。
3. 寻找关联的类加载器/META-INF/services/javax.xml.bind.JAXBContext文件。此文件遵循标准的服务描述符约定，如果存在这样的文件，它的内容被假定为提供程序工厂类。这一阶段的查找是自动发现。它允许用户把JAXB实现在类路径和使用它没有任何进一步的配置。
4. 最后，如果所有的步骤都失败了，那么其余的查找是未指定的。就是说，建议的行为就是寻找一些硬编码平台默认的JAXB实现。这一阶段的抬头是这样JavaSE可以有自己的JAXB实现作为最后的手段。

一旦供应商工厂类被发现，其public static JAXBContext createContext(String,ClassLoader,Map)方法（见参数的语义。newInstance(String, ClassLoader, Map)）或public static JAXBContext createContet(Class[],Map)方法（见参数语义newInstance(Class[], Map)）调用创建一个JAXBContext。

从以下版本开始：

jaxb1.0

另请参见：

Marshaller， Unmarshaller， 7.4.1 "Named Packages" in Java Language Specification

Field Summary

Fields

Modifier and Type	Field and Description
static String	JAXB_CONTEXT_FACTORY 包含创建新对象的能力 JAXBContext类名称的属性的名称。

构造方法摘要

构造方法

Modifier	Constructor and Description
protected	JAXBContext()

方法摘要

Modifier and Type	Method and Description
Binder<Node>	createBinder() 创建一个W3C DOM Binder。
<T> Binder<T>	createBinder(类<T> domType) 创建一个 Binder对象，可以在地方解包/联想/使用编组。
JAXBIntrospector	createJAXBIntrospector() 创建一个 JAXBIntrospector对象可以使用JAXB对象的反思。
abstract Marshaller	createMarshaller() 创建一个 Marshaller对象可用于将一个java内容树转换成XML数据。
abstract Unmarshaller	createUnmarshaller() 创建一个 Unmarshaller对象可用于将XML数据转换成java内容树。
abstract Validator	createValidator() 过时的。 因为jaxb2.0
void	generateSchema(SchemaOutputResolver outputResolver) 为此上下文生成架构文档。
static JAXBContext	newInstance(类... classesToBeBound) 获得一个 JAXBContext类的一个新实例。
static JAXBContext	newInstance(类[] classesToBeBound, Map<String,?> properties) 获得一个 JAXBContext类的一个新实例。
static JAXBContext	newInstance(String contextPath) 获得一个 JAXBContext类的一个新实例。
static JAXBContext	newInstance(String contextPath, ClassLoader classLoader) 获得一个 JAXBContext类的一个新实例。
static JAXBContext	newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties) 获得一个 JAXBContext类的一个新实例。

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JAXB_CONTEXT_FACTORY

public static final String JAXB_CONTEXT_FACTORY

包含创建新对象的能力 JAXBContext类名称的属性的名称。

另请参见：

Constant Field Values

Constructor Detail

JAXBContext

protected JAXBContext()

方法详细信息

newInstance

public static JAXBContext newInstance(String contextPath)
                               throws JAXBException

获得一个JAXBContext类的一个新实例。

这是一个调用newInstance(String,ClassLoader)方法与当前线程的上下文类加载器的便捷方法。

异常

JAXBException -如果在创建 JAXBContext如

1. 未能找到ObjectFactory.class或者jaxb.index包
2. 全球的元素包含在contextpath之间的歧义
3. 未能为上下文工厂提供属性定位一个值
4. 混合模式导出的包从不同的供应商在同一contextpath

出错

newInstance

public static JAXBContext newInstance(String contextPath,
                                      ClassLoader classLoader)
                               throws JAXBException

获得一个JAXBContext类的一个新实例。

客户端应用程序必须提供一个上下文路径这是一个列表的结肠（'：'，' u003a）分离的java包名称包含图式派生类和/或完全合格的JAXB注释的类。源代码生成图式的每包objectfactory.class JAXBContext注册。或者不是在上下文路径上市，程序员注释JAXB映射类，可以在一个jaxb.index资源文件中列出，格式如下。注意java包可以包含图式派生类和用户注释的JAXB类。此外，java包可以包含JAXB包注释必须处理。（参见JLS，第7.4.1”命名的套餐”）。

在contextpath上市每包必须符合下列条件一个或两个否则将抛出一个JAXBException：

1. 它必须包含objectfactory.class
2. 它必须包含jaxb.index

格式jaxb.index

该文件包含一个换行符分开的班级名单。空格和制表符，以及空白行，都将被忽略。注释的字符是#”（0x23）；每一行的所有字符的第一个评论的性格被忽略。该文件必须是UTF-8编码。这是可达的类中定义的newInstance(Class...)，从上市类也注册送。

在类的名字在jaxb.index文件产生的约束：

• 不要以“类”结束。
• 类名称是解决相对含jaxb.index文件包。只有类发生直接在含jaxb.index文件包是允许的。
• 完全限定的类名称是不允许的。一个合格的类名称，相对于当前的包，只允许指定一个嵌套或内部类。

保持与JAXB 1架构的java接口/实现结合的相容性，通过模式定制<jaxb:globalBindings valueClass="false">启用，JAXB提供程序将确保在上下文路径每个包有一个jaxb.properties文件包含的javax.xml.bind.context.factory财产和所有值解析到相同的供应商的价值。本要求不适用于JAXB注释的类。

如果在contextPath上市的各种包有任何全局XML元素名称冲突，将引发一JAXBException。

混合生成的接口/实现在同一上下文路径从多个API提供商绑定可能导致JAXBException抛出。

参与发现JAXB实现步骤是全班javadoc的讨论。

参数

contextPath - java包名称包含图式派生类和/或java架构列表（JAXB注释）映射类

classLoader这类装载器将被用来定位的实现类。

结果

一个 JAXBContext新实例

异常

JAXBException -如果在创建 JAXBContext如

1. 未能找到ObjectFactory.class或者jaxb.index包
2. 全球的元素包含在contextpath之间的歧义
3. 未能为上下文工厂提供属性定位一个值
4. 混合模式导出的包从不同的供应商在同一contextpath

出错

newInstance

public static JAXBContext newInstance(String contextPath,
                                      ClassLoader classLoader,
                                      Map<String,?> properties)
                               throws JAXBException

获得一个JAXBContext类的一个新实例。

这主要是因为newInstance(String, ClassLoader)相同，但这个版本允许你通过在供应商特定的属性来配置JAXBContext实例化。

属性的解释是高达实现。实现应该把JAXBException如果发现的属性，它不懂。

参数

contextPath - java包名称包含图式派生类列表

classLoader这类装载器将被用来定位的实现类。

properties -供应商特定的属性。可以是空的，这意味着同样的东西在一个空的Map通过。

结果

一个 JAXBContext新实例

异常

JAXBException -如果在创建 JAXBContext如

1. 未能找到ObjectFactory.class或者jaxb.index包
2. 全球的元素包含在contextpath之间的歧义
3. 未能为上下文工厂提供属性定位一个值
4. 混合模式导出的包从不同的供应商在同一contextpath

出错

从以下版本开始：

jaxb2.0

newInstance

public static JAXBContext newInstance(类... classesToBeBound)
                               throws JAXBException

获得一个JAXBContext类的一个新实例。

客户端应用程序必须提供新的上下文对象需要识别的类的列表。不仅新的上下文将识别指定的所有类，但它也将认识到从指定的类直接/间接引用的任何类。子类引用的类或@XmlTransient引用的类没有注册送。例如，在下面的java代码，如果你newInstance(Foo.class)，新创建的JAXBContext会认可Foo和Bar，但不Zot或FooBar：

类Foo {“xmltransient foobar C；酒吧B；}类酒吧{ int x；}类之延伸杆{ y；}类foobar { }

因此，一个典型的客户端应用程序只需要指定顶级类，但它需要小心。

请注意，每个java包注册送，当可选包注释存在，他们必须处理。（参见JLS，第7.4.1”命名的套餐”）。

参与发现JAXB实现步骤是全班javadoc的讨论。

参数

classesToBeBound - java类的列表是由新 JAXBContext认可。可以是空的，在 JAXBContext只知道规格定义的类将被退回的情况。

结果

一个新的 JAXBContext总是非空的有效对象实例。

异常

JAXBException -如果在创建 JAXBContext出错，例如（但不限于）：

1. JAXB实现没有被发现
2. 类使用JAXB注释错误
3. 类有碰撞注释（即，两个具有相同类型名称的类）
4. JAXB实现无法找到提供程序特定的带外信息（如附加文件生成的开发时间。）

IllegalArgumentException如果参数包含 null（即 newInstance(null);）

从以下版本开始：

jaxb2.0

newInstance

public static JAXBContext newInstance(类[] classesToBeBound,
                                      Map<String,?> properties)
                               throws JAXBException

获得一个JAXBContext类的一个新实例。

超载的newInstance(Class...)配置为实例JAXBContext性能。

属性的解释是高达实现。实现应该把JAXBException如果发现的属性，它不懂。

参数

classesToBeBound - java类的列表是由新 JAXBContext认可。可以是空的，在 JAXBContext只知道规格定义的类将被退回的情况。

properties -供应商特定的属性。可以是空的，这意味着同样的东西在一个空的Map通过。

结果

一个 JAXBContext新实例。总是非空有效对象。

异常

JAXBException -如果在创建 JAXBContext出错，例如（但不限于）：

1. JAXB实现没有被发现
2. 类使用JAXB注释错误
3. 类有碰撞注释（即，两个具有相同类型名称的类）
4. JAXB实现无法找到提供程序特定的带外信息（如附加文件生成的开发时间。）

IllegalArgumentException如果参数包含 null（即 newInstance(null,someMap);）

从以下版本开始：

jaxb2.0

createUnmarshaller

public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException

创建一个 Unmarshaller对象可用于将XML数据转换成java内容树。

结果

一个 Unmarshaller对象

异常

JAXBException -如果在创建 Unmarshaller对象时出错

createMarshaller

public abstract Marshaller createMarshaller()
                                     throws JAXBException

创建一个 Marshaller对象可用于将一个java内容树转换成XML数据。

结果

一个 Marshaller对象

异常

JAXBException -如果在创建 Marshaller对象时出错

createValidator

public abstract Validator createValidator()
                                   throws JAXBException

过时的。 因为jaxb2.0

Validator了可选和JAXB 2否决。请参阅javadoc的更多细节 Validator。

创建一个Validator对象可以用来验证一个java内容树对其源模式。

结果

一个 Validator对象

异常

JAXBException -如果在创建 Validator对象时出错

createBinder

public <T> Binder<T> createBinder(类<T> domType)

创建一个 Binder对象，可以在地方解包/联想/使用编组。

参数

domType选择DOM API的使用通过其DOM节点类。

结果

总是一种新的有效 Binder对象。

异常

UnsupportedOperationException如果DOM API对应 domType不实现所支持的。

从以下版本开始：

jaxb2.0

createBinder

public Binder<Node> createBinder()

创建一个W3C DOM Binder。

结果

总是一种新的有效 Binder对象。

从以下版本开始：

jaxb2.0

createJAXBIntrospector

public JAXBIntrospector createJAXBIntrospector()

创建一个 JAXBIntrospector对象可以使用JAXB对象的反思。

结果

总是返回一个非空的有效 JAXBIntrospector对象。

异常

UnsupportedOperationException - JAXB 1实现调用此方法会抛出。

从以下版本开始：

jaxb2.0

generateSchema

public void generateSchema(SchemaOutputResolver outputResolver)
                    throws IOException

为此上下文生成架构文档。

参数

outputResolver这个对象控制输出的模式将被发送。

异常

IOException -如果 SchemaOutputResolver抛出一个 IOException。

UnsupportedOperationException - JAXB 1实现调用此方法会抛出。

从以下版本开始：

JAXB 2