JAXBContext (Java EE 5)

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

JAXBContext 类提供到 JAXB API 的客户端入口点。它提供了管理实现 JAXB 绑定框架操作所需的 XML/Java 绑定信息的抽象，这些操作包括：解组、编组和验证。

客户端应用程序通常使用以下两种风格的 newInstance 方法之一来获得此类的新实例，但是该方法还有其他可用的特殊形式：

• JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
  JAXBContext 实例是根据冒号分隔的 Java 包名称的列表进行初始化的。每个 java 包都包含 JAXB 映射类、模式派生类和/或用户注释类。此外，java 包可能包含必须处理的 JAXB 包注释。（请参阅 JLS 第 3 版的第 7.4.1 节“包注释”）。
• JAXBContext.newInstance( com.acme.foo.Foo.class )
  JAXBContext 实例是使用作为参数传递的类以及可从这些类静态获得的类来实现初始化的。有关详细信息，请参见 #newInstance(Class...)。

特别要求：该提供者必须提供包含以下方法签名的实现类：

public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map properties ) throws JAXBException
public static JAXBContext createContext( Class[] classes, Map properties ) throws JAXBException
 

以下 JAXB 1.0 要求只是 java 接口/实现绑定的模式所需要的。它不适用于 JAXB 注释类。JAXB 提供者必须在每个包含模式派生类的包中生成一个 jaxb.properties 文件。该属性文件必须包含名为 javax.xml.bind.context.factory 的属性，其值为实现 createContext API 的类的名称。

该提供者提供的类不一定是可分配给 javax.xml.bind.JAXBContext 的，只是必须提供一个实现 createContext API 的类。

此外，提供者必须在执行 marshal 和 unmarshal 方法的任何客户端调用之前调用 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 注释类的元素的创建，应用程序需要访问和了解每个模式派生的 ObjectFactory 类，这些类存在于 contextPath 中包含的每个 java 包中。对于每个模式派生的 java 类，都有一个生成该类型的对象的静态工厂方法。例如，假定在编译模式之后有一个包 com.acme.foo，它包含一个名为 PurchaseOrder 的模式派生接口。为了创建该类型的对象，客户端应用程序将使用如下工厂方法：

com.acme.foo.PurchaseOrder po = 
com.acme.foo.ObjectFactory.createPurchaseOrder();
 

一旦客户端应用程序有一个模式派生对象的实例，它就可以使用 mutator 方法在该实例上设置内容。

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

特别要求：在包含名为 ObjectFactory 的包所需的所有对象工厂方法以及静态 newInstance( javaContentInterface ) 方法的每个包中，该提供者都必须生成一个类。

编组

Marshaller 类使客户端应用程序能够将 Java 内容树转换回 XML 数据。对使用工厂方法手动创建的内容树进行编组与对作为 unmarshal 操作结果的内容树进行编组没有什么区别。客户端可以将 java 内容树编组回 java.io.OutputStream 或 java.io.Writer 的 XML 数据。编组进程可以生成已注册 ContentHandler 的 SAX2 事件流，也可以生成一个 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 框架的便捷方法。有关详细信息，请参阅 setSchema(javax.xml.validation.Schema) API。

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

以下 JAXB 1.0 限制仅适用于将模式绑定到接口/实现类。因为此绑定不需要通用的运行时系统，所以 JAXB 客户端应用程序不必尝试混合使用不同的提供者提供的运行时对象（JAXBContext、Marshaller 等）。这并不意味着客户端应用程序是不可移植的，只是意味着客户端必须使用由用来编译模式的同一提供者提供的运行时系统。

version	en $Revision: 1.24 $ $Date: 2006/03/08 17:05:01 $
since	JAXB1.0
See also	javax.xml.bind.Marshaller, javax.xml.bind.Unmarshaller, S 7.4.1.1 "Package Annotations" in Java Language Specification, 3rd Edition

英文文档：

The JAXBContext class provides the client's entry point to the JAXB API. It provides an abstraction for managing the XML/Java binding information necessary to implement the JAXB binding framework operations: unmarshal, marshal and validate.

A client application normally obtains new instances of this class using one of these two styles for newInstance methods, although there are other specialized forms of the method available:

• JAXBContext.newInstance( "com.acme.foo:com.acme.bar" )
  The JAXBContext instance is initialized from a list of colon separated Java package names. Each java package contains JAXB mapped classes, schema-derived classes and/or user annotated classes. Additionally, the java package may contain JAXB package annotations that must be processed. (see JLS 3rd Edition, Section 7.4.1. Package Annotations).
• JAXBContext.newInstance( com.acme.foo.Foo.class )
  The JAXBContext instance is intialized with class(es) passed as parameter(s) and classes that are statically reachable from these class(es). See newInstance(Class...) for details.

SPEC REQUIREMENT: the provider must supply an implementation class containing the following method signatures:

 public static JAXBContext createContext( String contextPath, ClassLoader classLoader, Map properties ) throws JAXBException
 public static JAXBContext createContext( Class[] classes, Map properties ) throws JAXBException
 

The following JAXB 1.0 requirement is only required for schema to java interface/implementation binding. It does not apply to JAXB annotated classes. JAXB Providers must generate a jaxb.properties file in each package containing schema derived classes. The property file must contain a property named javax.xml.bind.context.factory whose value is the name of the class that implements the createContext APIs.

The class supplied by the provider does not have to be assignable to javax.xml.bind.JAXBContext, it simply has to provide a class that implements the createContext APIs.

In addition, the provider must call the DatatypeConverter.setDatatypeConverter api prior to any client invocations of the marshal and unmarshal methods. This is necessary to configure the datatype converter that will be used during these operations.

Unmarshalling

The Unmarshaller class provides the client application the ability to convert XML data into a tree of Java content objects. The unmarshal method allows for any global XML element declared in the schema to be unmarshalled as the root of an instance document. Additionally, the unmarshal method allows for an unrecognized root element that has an xsi:type attribute's value that references a type definition declared in the schema to be unmarshalled as the root of an instance document. The JAXBContext object allows the merging of global elements and type definitions across a set of schemas (listed in the contextPath). Since each schema in the schema set can belong to distinct namespaces, the unification of schemas to an unmarshalling context should be namespace independent. This means that a client application is able to unmarshal XML documents that are instances of any of the schemas listed in the contextPath. For example:

        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
 

The client application may also generate Java content trees explicitly rather than unmarshalling existing XML data. For all JAXB-annotated value classes, an application can create content using constructors. For schema-derived interface/implementation classes and for the creation of elements that are not bound to a JAXB-annotated class, an application needs to have access and knowledge about each of the schema derived ObjectFactory classes that exist in each of java packages contained in the contextPath. For each schema derived java class, there is a static factory method that produces objects of that type. For example, assume that after compiling a schema, you have a package com.acme.foo that contains a schema derived interface named PurchaseOrder. In order to create objects of that type, the client application would use the factory method like this:

       com.acme.foo.PurchaseOrder po = 
           com.acme.foo.ObjectFactory.createPurchaseOrder();
 

Once the client application has an instance of the the schema derived object, it can use the mutator methods to set content on it.

For more information on the generated ObjectFactory classes, see Section 4.2 Java Package of the specification.

SPEC REQUIREMENT: the provider must generate a class in each package that contains all of the necessary object factory methods for that package named ObjectFactory as well as the static newInstance( javaContentInterface ) method

Marshalling

The Marshaller class provides the client application the ability to convert a Java content tree back into XML data. There is no difference between marshalling a content tree that is created manually using the factory methods and marshalling a content tree that is the result an unmarshal operation. Clients can marshal a java content tree back to XML data to a java.io.OutputStream or a java.io.Writer. The marshalling process can alternatively produce SAX2 event streams to a registered ContentHandler or produce a DOM Node object. Client applications have control over the output encoding as well as whether or not to marshal the XML data as a complete document or as a fragment.

Here is a simple example that unmarshals an XML document and then marshals it back out:

        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 );
 

Validation

Validation has been changed significantly since JAXB 1.0. The Validator class has been deprecated and made optional. This means that you are advised not to use this class and, in fact, it may not even be available depending on your JAXB provider. JAXB 1.0 client applications that rely on Validator will still work properly when deployed with the JAXB 1.0 runtime system. In JAXB 2.0, the Unmarshaller has included convenince methods that expose the JAXP 1.3 javax.xml.validation framework. Please refer to the Unmarshaller.setSchema(javax.xml.validation.Schema) API for more information.

JAXB Runtime Binding Framework Compatibility

The following JAXB 1.0 restriction only applies to binding schema to interfaces/implementation classes. Since this binding does not require a common runtime system, a JAXB client application must not attempt to mix runtime objects (JAXBContext, Marshaller, etc. ) from different providers. This does not mean that the client application isn't portable, it simply means that a client has to use a runtime system provided by the same provider that was used to compile the schema.

Since:

JAXB1.0

Version:

$Revision: 1.24 $ $Date: 2006/03/08 17:05:01 $

Author:

• Ryan Shoemaker, Sun Microsystems, Inc.
• Kohsuke Kawaguchi, Sun Microsystems, Inc.
• Joe Fialli, Sun Microsystems, Inc.

See Also:

Marshaller, Unmarshaller, S 7.4.1.1 "Package Annotations" in Java Language Specification, 3rd Edition

---

Field Summary
static String	JAXB_CONTEXT_FACTORY           The name of the property that contains the name of the class capable of creating new JAXBContext objects.

 

Constructor Summary
protected	JAXBContext()

 

Method Summary
Binder<Node>	createBinder()           Creates a Binder for W3C DOM.
<T> Binder<T>

createBinder(Class<T> domType)
          Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.  JAXBIntrospector createJAXBIntrospector()
          Creates a JAXBIntrospector object that can be used to introspect JAXB objects. abstract  Marshaller createMarshaller()
          Create a Marshaller object that can be used to convert a java content tree into XML data. abstract  Unmarshaller createUnmarshaller()
          Create an Unmarshaller object that can be used to convert XML data into a java content tree. abstract  Validator createValidator()
          Deprecated. since JAXB2.0  void generateSchema(SchemaOutputResolver outputResolver)
          Generates the schema documents for this context. static JAXBContext newInstance(Class... classesToBeBound)
           Obtain a new instance of a JAXBContext class. static JAXBContext newInstance(Class[] classesToBeBound, Map<String,?> properties)
           Obtain a new instance of a JAXBContext class. static JAXBContext newInstance(String contextPath)
           Obtain a new instance of a JAXBContext class. static JAXBContext newInstance(String contextPath, ClassLoader classLoader)
           Obtain a new instance of a JAXBContext class. static JAXBContext newInstance(String contextPath, ClassLoader classLoader, Map<String,?> properties)
           Obtain a new instance of a JAXBContext class.  

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

The name of the property that contains the name of the class capable of creating new JAXBContext objects.

See Also:

Constant Field Values

Constructor Detail

protected JAXBContext()

英文文档：

JAXBContext

protected JAXBContext()

Method Detail

public static JAXBContext newInstance(String contextPath) throws JAXBException

获得 JAXBContext 类的新实例。

这是 newInstance 方法的一个便捷方法。它使用当前线程的上下文类加载器。要指定如何使用不同的类加载器，可以通过 Thread.setContextClassLoader() api 设置它，或者使用 newInstance 方法。

Throws

JAXBException: 如果在创建 JAXBContext 时遇到错误，比如： 在包中查找 ObjectFactory.class 或 jaxb.index 失败 包含在 contextPath 中的全局元素之间出现混淆 查找上下文工厂提供者属性的值失败 混合使用相同 contextPath 上的不同提供者的模式派生包

英文文档：

newInstance

public static JAXBContext newInstance(String contextPath)
                               throws JAXBException

Obtain a new instance of a JAXBContext class.

This is a convenience method for the newInstance method. It uses the context class loader of the current thread. To specify the use of a different class loader, either set it via the Thread.setContextClassLoader() api or use the newInstance method.

Throws:

JAXBException - if an error was encountered while creating the JAXBContext such as

1. failure to locate either ObjectFactory.class or jaxb.index in the packages
2. an ambiguity among global elements contained in the contextPath
3. failure to locate a value for the context factory provider property
4. mixing schema derived packages from different providers on the same contextPath

---

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

获得 JAXBContext 类的新实例。

客户端应用程序必须提供上下文路径，该路径是一个冒号 (':', :) 分隔的 java 包名称列表，它包含模式派生类和/或完全限定的 JAXB 注释类。模式派生的代码是通过为每个包生成的 ObjectFactory.class 在 JAXBContext 中注册的。程序员注释的 JAXB 映射类在 jaxb.index 资源文件中列出，而不是在上下文路径中列出，列出这些类所采用的格式如下所述。注意，java 包可以包含模式派生类和用户注释 JAXB 类。此外，java 包可能包含必须处理的 JAXB 包注释。（请参阅 JLS 第 3 版的第 7.4.1 节“包注释”）。

每个 contextPath 上列出的包都必须满足下面的一个或两个条件，否则将抛出 JAXBException：

1. 必须包含 ObjectFactory.class
2. 必须包含 jaxb.index

jaxb.index 的格式

该文件应该包含换行符分隔的类名称列表。空格、制表符和空行被忽略。注释字符是 '#' (0x23)；每行上的第一个注释字符后面的所有字符都被忽略。文件必须使用 UTF-8 编码。从列出的类中获得的类也可以在 JAXBContext 中注册，正如 #newInstance(Class...) 定义的那样。

对 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 提供者中生成的接口/实现绑定可能导致抛出 JAXBException。

contextPath	包含模式派生类和/或 java 模式（JAXB 注释）映射类的 java 包名称的列表
classLoader	此类加载器将用于定位实现类。
return	新的 JAXBContext 实例
Throws	JAXBException: 如果在创建 JAXBContext 时遇到错误，比如： 在包中查找 ObjectFactory.class 或 jaxb.index 失败 包含在 contextPath 中的全局元素之间出现混淆 查找上下文工厂提供者属性的值失败 混合使用相同 contextPath 上的不同提供者的模式派生包

英文文档：

newInstance

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

Obtain a new instance of a JAXBContext class.

The client application must supply a context path which is a list of colon (':', \u003A) separated java package names that contain schema-derived classes and/or fully qualified JAXB-annotated classes. Schema-derived code is registered with the JAXBContext by the ObjectFactory.class generated per package. Alternatively than being listed in the context path, programmer annotated JAXB mapped classes can be listed in a jaxb.index resource file, format described below. Note that a java package can contain both schema-derived classes and user annotated JAXB classes. Additionally, the java package may contain JAXB package annotations that must be processed. (see JLS 3rd Edition, Section 7.4.1. "Package Annotations").

Every package listed on the contextPath must meet one or both of the following conditions otherwise a JAXBException will be thrown:

1. it must contain ObjectFactory.class
2. it must contain jaxb.index

Format for jaxb.index

The file contains a newline-separated list of class names. Space and tab characters, as well as blank lines, are ignored. The comment character is '#' (0x23); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8. Classes that are reachable, as defined in newInstance(Class...), from the listed classes are also registered with JAXBContext.

Constraints on class name occuring in a jaxb.index file are:

• Must not end with ".class".
• Class names are resolved relative to package containing jaxb.index file. Only classes occuring directly in package containing jaxb.index file are allowed.
• Fully qualified class names are not allowed. A qualified class name,relative to current package, is only allowed to specify a nested or inner class.

To maintain compatibility with JAXB 1.0 schema to java interface/implementation binding, enabled by schema customization , the JAXB provider will ensure that each package on the context path has a jaxb.properties file which contains a value for the javax.xml.bind.context.factory property and that all values resolve to the same provider. This requirement does not apply to JAXB annotated classes.

If there are any global XML element name collisions across the various packages listed on the contextPath, a JAXBException will be thrown.

Mixing generated interface/impl bindings from multiple JAXB Providers in the same context path may result in a JAXBException being thrown.

Parameters:

contextPath - list of java package names that contain schema derived class and/or java to schema (JAXB-annotated) mapped classes

classLoader - This class loader will be used to locate the implementation classes.

Returns:

a new instance of a JAXBContext

Throws:

JAXBException - if an error was encountered while creating the JAXBContext such as

1. failure to locate either ObjectFactory.class or jaxb.index in the packages
2. an ambiguity among global elements contained in the contextPath
3. failure to locate a value for the context factory provider property
4. mixing schema derived packages from different providers on the same contextPath

---

英文文档：

newInstance

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

Obtain a new instance of a JAXBContext class.

This is mostly the same as newInstance(String, ClassLoader), but this version allows you to pass in provider-specific properties to configure the instanciation of JAXBContext.

The interpretation of properties is up to implementations.

Parameters:

contextPath - list of java package names that contain schema derived classes

classLoader - This class loader will be used to locate the implementation classes.

properties - provider-specific properties

Returns:

a new instance of a JAXBContext

Throws:

JAXBException - if an error was encountered while creating the JAXBContext such as

1. failure to locate either ObjectFactory.class or jaxb.index in the packages
2. an ambiguity among global elements contained in the contextPath
3. failure to locate a value for the context factory provider property
4. mixing schema derived packages from different providers on the same contextPath

Since:

JAXB2.0

---

public static JAXBContext newInstance(Class<T>[] classesToBeBound) throws JAXBException

获得 JAXBContext 类的新实例。

客户端应用程序必须提供新上下文对象需要识别的类的列表。 新的上下文不仅要识别所有指定的类，还要识别直接/间接从指定类中静态引用的所有类。所引用类的子类或 @XmlTransient 引用类都不用在 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 第 3 版的第 7.4.1 节“包注释”）。

classesToBeBound	将通过新 JAXBContext 识别的 java 类的列表。可以为空，在这种情况下，将返回只知道规范中定义的类的 JAXBContext。
return	新的 JAXBContext 实例。该实例始终是一个非 null 的有效对象。
Throws	JAXBException: 如果创建 JAXBContext 时遇到错误（但不限于这些错误），如下所示： 未发现任何 JAXB 实现 类以不正确的方式使用了 JAXB 注释 类包含有冲突的注释（比如有相同类型名称的两个类） JAXB 实现不能查找特定于提供者的带外信息（例如在开发时生成的附加文件）。
Throws	IllegalArgumentException: 如果参数中包含 null（即 newInstance(null);）
since	JAXB2.0

英文文档：

newInstance

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

Obtain a new instance of a JAXBContext class.

The client application must supply a list of classes that the new context object needs to recognize. Not only the new context will recognize all the classes specified, but it will also recognize any classes that are directly/indirectly referenced statically from the specified classes. Subclasses of referenced classes nor @XmlTransient referenced classes are not registered with JAXBContext. For example, in the following Java code, if you do newInstance(Foo.class), the newly created JAXBContext will recognize both Foo and Bar, but not Zot or FooBar:

 class Foo {
      @XmlTransient FooBar c;
      Bar b;
 }
 class Bar { int x; }
 class Zot extends Bar { int y; }
 class FooBar { }
 

Therefore, a typical client application only needs to specify the top-level classes, but it needs to be careful.

Note that for each java package registered with JAXBContext, when the optional package annotations exist, they must be processed. (see JLS 3rd Edition, Section 7.4.1. "Package Annotations").

Parameters:

classesToBeBound - list of java classes to be recognized by the new JAXBContext. Can be empty, in which case a JAXBContext that only knows about spec-defined classes will be returned.

Returns:

A new instance of a JAXBContext. Always non-null valid object.

Throws:

JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):

1. No JAXB implementation was discovered
2. Classes use JAXB annotations incorrectly
3. Classes have colliding annotations (i.e., two classes with the same type name)
4. The JAXB implementation was unable to locate provider-specific out-of-band information (such as additional files generated at the development time.)

IllegalArgumentException - if the parameter contains null (i.e., newInstance(null);)

Since:

JAXB2.0

---

英文文档：

newInstance

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

Obtain a new instance of a JAXBContext class.

An overloading of newInstance(Class...) to configure 'properties' for this instantiation of JAXBContext.

The interpretation of properties is implementation specific.

Parameters:

classesToBeBound - list of java classes to be recognized by the new JAXBContext. Can be empty, in which case a JAXBContext that only knows about spec-defined classes will be returned.

Returns:

A new instance of a JAXBContext. Always non-null valid object.

Throws:

JAXBException - if an error was encountered while creating the JAXBContext, such as (but not limited to):

1. No JAXB implementation was discovered
2. Classes use JAXB annotations incorrectly
3. Classes have colliding annotations (i.e., two classes with the same type name)
4. The JAXB implementation was unable to locate provider-specific out-of-band information (such as additional files generated at the development time.)

IllegalArgumentException - if the parameter contains null (i.e., newInstance(null);)

Since:

JAXB2.0

---

abstract public Unmarshaller createUnmarshaller() throws JAXBException
创建一个可以用来将 XML 数据转换为 java 内容树的 Unmarshaller 对象。

return	Unmarshaller 对象
Throws	JAXBException: 如果创建 Unmarshaller 对象时遇到错误

英文文档：

createUnmarshaller

public abstract Unmarshaller createUnmarshaller()
                                         throws JAXBException

Create an Unmarshaller object that can be used to convert XML data into a java content tree.

Returns:

an Unmarshaller object

Throws:

JAXBException - if an error was encountered while creating the Unmarshaller object

---

abstract public Marshaller createMarshaller() throws JAXBException
创建一个可以用来将 java 内容树转换为 XML 数据的 Marshaller 对象。

return	Marshaller 对象
Throws	JAXBException: 如果创建 Marshaller 对象时遇到错误

英文文档：

createMarshaller

public abstract Marshaller createMarshaller()
                                     throws JAXBException

Create a Marshaller object that can be used to convert a java content tree into XML data.

Returns:

a Marshaller object

Throws:

JAXBException - if an error was encountered while creating the Marshaller object

---

abstract public Validator createValidator() throws JAXBException
Validator 已成为一个可选项，并且在 JAXB 2.0 中已过时。有关详细信息，请参阅 Validator 的 javadoc。

创建一个可用于根据源模式验证 java 内容树的 Validator 对象。

return	一个 Validator 对象
Throws	JAXBException: 如果创建 Validator 对象时遇到错误
deprecated	从 JAXB 2.0 开始

英文文档：

createValidator

public abstract Validator createValidator()
                                   throws JAXBException

Deprecated. since JAXB2.0

Validator has been made optional and deprecated in JAXB 2.0. Please refer to the javadoc for Validator for more detail.

Create a Validator object that can be used to validate a java content tree against its source schema.

Returns:

a Validator object

Throws:

JAXBException - if an error was encountered while creating the Validator object

---

英文文档：

createBinder

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

Creates a Binder object that can be used for associative/in-place unmarshalling/marshalling.

Parameters:

domType - select the DOM API to use by passing in its DOM Node class.

Returns:

always a new valid Binder object.

Throws:

UnsupportedOperationException - if DOM API corresponding to domType is not supported by the implementation.

Since:

JAXB2.0

---

public ">Binder createBinder()
为 W3C DOM 创建一个 Binder。

return	总是返回新的有效 Binder 对象。
since	JAXB2.0

英文文档：

createBinder

public Binder<Node> createBinder()

Creates a Binder for W3C DOM.

Returns:

always a new valid Binder object.

Since:

JAXB2.0

---

public JAXBIntrospector createJAXBIntrospector()
创建一个可以用于内省 JAXB 对象的 JAXBIntrospector 对象。

return	总是返回非 null 的有效 JAXBIntrospector 对象。
Throws	UnsupportedOperationException: 在 JAXB 1.0 实现上调用此方法将抛出 UnsupportedOperationException。
since	JAXB2.0

英文文档：

createJAXBIntrospector

public JAXBIntrospector createJAXBIntrospector()

Creates a JAXBIntrospector object that can be used to introspect JAXB objects.

Returns:

always return a non-null valid JAXBIntrospector object.

Throws:

UnsupportedOperationException - Calling this method on JAXB 1.0 implementations will throw an UnsupportedOperationException.

Since:

JAXB2.0

---

public void generateSchema(SchemaOutputResolver outputResolver) throws java.io.IOException
生成此上下文的模式文档。

outputResolver	此对象控制模式将被发送的输出。
Throws	java.io.IOException: 如果 SchemaOutputResolver 抛出 IOException。
Throws	UnsupportedOperationException: 在 JAXB 1.0 实现上调用此方法将抛出 UnsupportedOperationException。
since	JAXB 2.0

英文文档：

generateSchema

public void generateSchema(SchemaOutputResolver outputResolver)
                    throws IOException

Generates the schema documents for this context.

Parameters:

outputResolver - this object controls the output to which schemas will be sent.

Throws:

IOException - if SchemaOutputResolver throws an IOException.

UnsupportedOperationException - Calling this method on JAXB 1.0 implementations will throw an UnsupportedOperationException.

Since:

JAXB 2.0

---

Overview  Package   Class  Tree  Deprecated  Index  Help
PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

Submit a bug or feature

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.