JAXBContext (Java Platform SE 8 )

java.lang.Object
- javax.xml.bind.JAXBContext

```
public abstract class JAXBContext
extends Object
```
JAXBContext类提供客户端的JAXB API入口点。它为管理实现JAXB绑定框架操作所必需的XML / Java绑定信息提供了一个抽象：unmarshal，marshal和validate。

客户端应用程序通常使用newInstance方法的这两种样式之一获取此类的新实例，尽管还有其他专门的方法可用：
- JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
  JAXBContext实例是从冒号分隔的Java包名称列表中初始化的。每个java包都包含JAXB映射类，模式派生类和/或用户注释类。此外，java包可能包含必须处理的JAXB包注释。（参见JLS，第7.4.1节“命名包”）。
- JAXBContext.newInstance( com.acme.foo.Foo.class )
  JAXBContext实例使用作为参数传递的类和从这些类静态访问的类来初始化。详见newInstance(Class...) 。
规范要求：提供者必须提供一个包含以下方法签名的实现类：
```
  public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map<String,Object> properties ) throws JAXBException
 public static JAXBContext createContext( Class[] classes, Map<String,Object> properties ) throws JAXBException 
```
以下JAXB 1.0要求仅适用于模式到java接口/实现绑定。 它不适用于JAXB注释类。 JAXB提供商必须在每个包含模式派生类的包中生成一个jaxb.properties文件。 属性文件必须包含一个名为javax.xml.bind.context.factory的属性，其值是实现createContext API的类的名称。

提供者提供的类不需要分配给javax.xml.bind.JAXBContext ，它只需要提供一个实现createContext API的类。

此外，提供者必须在任何客户端调用元组和解组件方法之前调用DatatypeConverter.setDatatypeConverter api。 这是配置在这些操作期间将使用的数据类型转换器所必需的。

解组

Unmarshaller类为客户端应用程序提供将XML数据转换为Java内容对象树的能力。 unmarshal方法允许在模式中声明的任何全局XML元素作为实例文档的根解组。此外，unmarshal方法允许一个无法识别的根元素，该元素的xsi：type属性的值引用在模式中声明的类型定义作为实例文档的根而被解组。 JAXBContext对象允许在一组模式（ contextPath中列出）中合并全局元素和类型定义。由于模式集中的每个模式都可以属于不同的命名空间，所以将模式统一到解组上下文应该与命名空间无关。这意味着客户端应用程序能够解组是任何在contextPath列出的模式实例的XML文档。例如：
```
  JAXBContext jc = JAXBContext.newInstance( "com.acme.foo:com.acme.bar" );
        Unmarshaller u = jc.createUnmarshaller();
        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) ); // ok
        BarObject barObj = (BarObject)u.unmarshal( new File( "bar.xml" ) ); // ok
        BazObject bazObj = (BazObject)u.unmarshal( new File( "baz.xml" ) ); // error, "com.acme.baz" not in contextPath 
```
客户端应用程序也可以显式生成Java内容树，而不是解组现有的XML数据。对于所有JAXB注释的值类，应用程序可以使用构造函数创建内容。对于模式导出的接口/实现类以及创建未绑定到JAXB注释类的元素，应用程序需要具有对每个包含的java包中存在的每个模式派生的ObjectFactory类的访问和知识contextPath 。对于每个模式派生的java类，都有一个静态工厂方法来生成该类型的对象。例如，假设在编译模式之后，您有一个包含PurchaseOrder的模式导出接口的包com.acme.foo 。为了创建该类型的对象，客户端应用程序将使用如下所示的工厂方法：
```
  com.acme.foo.PurchaseOrder po =
           com.acme.foo.ObjectFactory.createPurchaseOrder(); 
```
一旦客户端应用程序具有模式派生对象的实例，它可以使用mutator方法来设置内容。

有关生成的ObjectFactory类的更多信息，请参见规范的第4.2节Java包 。

规范要求：提供程序必须在每个包中生成一个类，其中包含名为ObjectFactory的包的所有必需对象工厂方法以及静态newInstance( javaContentInterface )方法

编组

Marshaller类为客户端应用程序提供将Java内容树转换回XML数据的能力。编组使用工厂方法手动创建的内容树和编组作为unmarshal操作的结果的内容树之间没有区别。客户端可以将Java内容树编组回到XML数据到java.io.OutputStream或java.io.Writer 。编组过程可以替代地将SAX2事件流生成到注册的ContentHandler或生成DOM节点对象。客户端应用程序可以控制输出编码以及是否将XML数据编组为完整的文档或片段。

这是一个简单的示例，它解组XML文档，然后将其重新编排出来：
```
  JAXBContext jc = JAXBContext.newInstance( "com.acme.foo" );

        // unmarshal from foo.xml
        Unmarshaller u = jc.createUnmarshaller();
        FooObject fooObj = (FooObject)u.unmarshal( new File( "foo.xml" ) );

        // marshal to System.out
        Marshaller m = jc.createMarshaller();
        m.marshal( fooObj, System.out ); 
```
验证

自JAXB 1.0以来，验证已经发生了重大变化。 Validator类已被弃用，可选。这意味着建议您不要使用此类，实际上，根据您的JAXB提供程序，它可能甚至不可用。使用JAXB 1.0运行时系统部署时，依赖于Validator的 JAXB 1.0客户端应用程序仍将正常工作。在JAXB 2.0中， Unmarshaller包含了方便的方法来暴露JAXP 1.3 javax.xml.validation框架。有关详细信息，请参阅Unmarshaller.setSchema(javax.xml.validation.Schema) API。

JAXB运行时绑定框架兼容性

以下JAXB 1.0限制仅适用于绑定到接口/实现类的模式。由于此绑定不需要常见的运行时系统，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()` 创建可用于内省JAXB对象 `JAXBIntrospector`对象。
`abstract Marshaller`	`createMarshaller()` 创建一个可用于将java内容树转换为XML数据的 `Marshaller`对象。
`abstract Unmarshaller`	`createUnmarshaller()` 创建一个可以将XML数据转换为java内容树的 `Unmarshaller`对象。
`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

- 字段详细信息
  - JAXB_CONTEXT_FACTORY
```
public static final String JAXB_CONTEXT_FACTORY
```
    包含能够创建新的 JAXBContext对象的类的名称的属性的名称。
    
    另请参见：
    
    Constant Field Values
- 构造方法详细信息
  - JAXBContext
```
protected JAXBContext()
```
- 方法详细信息
  - newInstance
```
public static JAXBContext newInstance(String contextPath)
                               throws JAXBException
```
    获得一个新的JAXBContext类的实例。
    
    这是使用当前线程的上下文类加载器调用newInstance(String,ClassLoader)方法的方便方法。
    异常
    JAXBException -如果创建JAXBContext如遇到错误
    
    无法在包中找到ObjectFactory.class或jaxb.index
    
    contextPath中包含的全局元素之间存在模糊
    
    无法找到上下文工厂提供程序属性的值
    
    在相同的contextPath上混合来自不同提供者的模式派生包
  - newInstance
```
public static JAXBContext newInstance(String contextPath,
                                      ClassLoader classLoader)
                               throws JAXBException
```
    获得一个新的JAXBContext类的实例。
    
    客户端应用程序必须提供一个上下文路径，该路径是包含模式派生类和/或完全限定JAXB注释类的分隔的java包名称的冒号（'：'，\ u003A）列表。通过每个包生成的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...) ，从列出的类也与JAXBContext中注册。
    
    在jaxb.index文件中出现的类名的限制是：
    - 不得以“.class”结尾。
    - 类名相对于包含jaxb.index文件的包解析。只允许在包含jaxb.index文件的包中直接发行。
    - 不允许使用完全限定的类名。相对于当前包的限定类名仅允许指定嵌套或内部类。
    为了保持与JAXB 1.0模式到Java接口/实现绑定的兼容性，通过模式定制<jaxb:globalBindings valueClass="false">启用，JAXB提供程序将确保上下文路径上的每个包都有一个jaxb.properties文件，其中包含javax.xml.bind.context.factory属性的值，并且所有值都解析为同一供应商。此要求不适用于JAXB注释类。
    
    如果在contextPath上列出的各种软件包之间存在任何全局XML元素名称冲突 ， 那么将抛出一个JAXBException 。
    
    在同一上下文路径中混合来自多个JAXB提供程序的生成的接口/ impl绑定可能会导致抛出JAXBException 。
    
    发现JAXB实现涉及的步骤在类javadoc中讨论。
    参数
    
    contextPath - 包含模式派生类和/或Java到模式（JAXB注释）映射类的java包名称列表
    
    classLoader - 此类加载器将用于定位实现类。
    
    结果
    
    一个新的一个 JAXBContext的实例
    
    异常
    JAXBException -如果创建JAXBContext如遇到错误
    
    无法在包中找到ObjectFactory.class或jaxb.index
    
    contextPath中包含的全局元素之间存在模糊
    
    无法找到上下文工厂提供程序属性的值
    
    在相同的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 - 提供者特定的属性。可以是null，这意味着与传递一个空的地图相同的东西。
    
    结果
    
    一个新的一个 JAXBContext的实例
    
    异常
    JAXBException -如果创建JAXBContext如遇到错误
    
    无法在包中找到ObjectFactory.class或jaxb.index
    
    contextPath中包含的全局元素之间存在模糊
    
    无法找到上下文工厂提供程序属性的值
    
    在相同的contextPath上混合来自不同提供者的模式派生包
    从以下版本开始：
    
    JAXB2.0
  - newInstance
```
public static JAXBContext newInstance(类... classesToBeBound)
                               throws JAXBException
```
    获得一个新的JAXBContext类的实例。
    
    客户端应用程序必须提供新的上下文对象需要识别的类的列表。不仅新的上下文将识别所有指定的类，而且还将识别从指定的类静态地直接/间接引用的任何类。引用类的子类和引用的类都没有注册到JAXBContext。例如，在以下Java代码中，如果您做了newInstance(Foo.class) ，新创建的JAXBContext将会识别Foo和Bar ，但不会识别Zot或FooBar ：
```
  class Foo {
      @XmlTransient FooBar c;
      Bar b;
 }
 class Bar { int x; }
 class Zot extends Bar { int y; }
 class FooBar { } 
```
    因此，典型的客户端应用程序只需要指定顶级类，但需要注意。
    请注意，对于JAXBContext注册的每个java包，当可选包注释存在时，都必须处理它们。（参见JLS，第7.4.1节“命名包”）。
    
    发现JAXB实现涉及的步骤在类javadoc中讨论。
    参数
    
    classesToBeBound - 要由新的JAXBContext识别的java类的列表。可以是空的，在这种情况下，只能知道定义类的JAXBContext将被返回。
    
    结果
    
    一个新的一个JAXBContext的实例。始终为非空的有效对象。
    
    异常
    JAXBException -如果创建JAXBContext，例如（但不限于）时遇到错误：
    
    没有发现JAXB实现
    
    类使用JAXB注释不正确
    
    类具有冲突注释（即，具有相同类型名称的两个类）
    
    JAXB实现无法找到提供程序特定的带外信息（例如在开发时生成的附加文件）。
    IllegalArgumentException - 如果参数包含 null （即 newInstance(null); ）
    
    从以下版本开始：
    
    JAXB2.0
  - newInstance
```
public static JAXBContext newInstance(类[] classesToBeBound,
                                      Map<String,?> properties)
                               throws JAXBException
```
    获得一个新的JAXBContext类的实例。
    
    的超载newInstance(Class...)配置“属性”这一实例化JAXBContext 。
    
    属性的解释取决于实现。实现应该抛出JAXBException如果发现它无法理解的属性。
    参数
    
    classesToBeBound - 要由新的JAXBContext识别的java类的列表。可以是空的，在这种情况下，只能知道定义类的JAXBContext将被返回。
    
    properties - 提供者特定的属性。可以是null，这意味着与传递一个空的地图相同的东西。
    
    结果
    
    一个新的一个JAXBContext的实例。始终为非空的有效对象。
    
    异常
    JAXBException -如果创建JAXBContext，例如（但不限于）时遇到错误：
    
    没有发现JAXB实现
    
    类使用JAXB注释不正确
    
    类具有冲突注释（即，具有相同类型名称的两个类）
    
    JAXB实现无法找到提供程序特定的带外信息（例如在开发时生成的附加文件）。
    IllegalArgumentException - 如果参数包含 null （即 newInstance(null,someMap); ）
    
    从以下版本开始：
    
    JAXB2.0
  - createUnmarshaller
```
public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException
```
    创建一个可用于将XML数据转换为java内容树的 Unmarshaller对象。
    
    结果
    
    一个 Unmarshaller对象
    
    异常
    
    JAXBException - 如果在创建 Unmarshaller对象时遇到错误
  - createMarshaller
```
public abstract Marshaller createMarshaller()
                                     throws JAXBException
```
    创建一个可用于将java内容树转换为XML数据的 Marshaller对象。
    
    结果
    
    一个 Marshaller对象
    
    异常
    
    JAXBException - 如果在创建 Marshaller对象时遇到错误
  - createValidator
```
public abstract Validator createValidator()
                                   throws JAXBException
```
    已弃用自JAXB2.0起
    
    Validator已经在JAXB 2.0中被选为和不推荐使用。有关更多详细信息，请参阅javadoc for Validator 。
    创建一个可用于根据其源模式验证java内容树的Validator对象。
    
    结果
    
    一个 Validator对象
    
    异常
    
    JAXBException - 如果在创建 Validator对象时遇到错误
  - createBinder
```
public <T> Binder<T> createBinder(类<T> domType)
```
    创建可用于关联/原地解组/编组一个 Binder对象。
    
    参数
    
    domType - 通过传入其DOM Node类来选择要使用的DOM API。
    
    结果
    
    总是一个新的有效的 Binder对象。
    
    异常
    
    UnsupportedOperationException - 如果实现不支持对应于 domType的 DOM API。
    
    从以下版本开始：
    
    JAXB2.0
  - createBinder
```
public Binder<Node> createBinder()
```
    为W3C DOM创建一个 Binder 。
    
    结果
    
    总是一个新的有效的 Binder对象。
    
    从以下版本开始：
    
    JAXB2.0
  - createJAXBIntrospector
```
public JAXBIntrospector createJAXBIntrospector()
```
    创建可用于内省JAXB对象 JAXBIntrospector对象。
    
    结果
    
    总是返回一个非空的有效 JAXBIntrospector对象。
    
    异常
    
    UnsupportedOperationException - 在JAXB 1.0实现中调用此方法将抛出UnsupportedOperationException异常。
    
    从以下版本开始：
    
    JAXB2.0
  - generateSchema
```
public void generateSchema(SchemaOutputResolver outputResolver)
                    throws IOException
```
    生成此上下文的模式文档。
    
    参数
    
    outputResolver - 此对象控制将发送模式的输出。
    
    异常
    
    IOException - 如果SchemaOutputResolver抛出一个IOException 。
    
    UnsupportedOperationException - 在JAXB 1.0实现上调用此方法将抛出UnsupportedOperationException异常。
    
    从以下版本开始：
    
    JAXB 2.0

Class JAXBContext

解组

编组

验证

JAXB运行时绑定框架兼容性

发现JAXB实现

Field Summary

构造方法摘要

方法摘要

Methods inherited from class java.lang.Object

字段详细信息

JAXB_CONTEXT_FACTORY

构造方法详细信息

JAXBContext

方法详细信息

newInstance

newInstance

newInstance

newInstance

newInstance

createUnmarshaller

createMarshaller

createValidator

createBinder

createBinder

createJAXBIntrospector

generateSchema