All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.xml.bind.annotation.adapters.XmlAdapter Maven / Gradle / Ivy

/*
 * Copyright (c) 2004, 2018 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0, which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package javax.xml.bind.annotation.adapters;

/**
 * Adapts a Java type for custom marshaling.
 *
 * 

Usage:

* *

* Some Java types do not map naturally to an XML representation, for * example {@code HashMap} or other non JavaBean classes. Conversely, * an XML representation may map to a Java type but an application may * choose to access the XML representation using another Java * type. For example, the schema to Java binding rules bind * xs:DateTime by default to XmlGregorianCalendar. But an application * may desire to bind xs:DateTime to a custom type, * MyXmlGregorianCalendar, for example. In both cases, there is a * mismatch between bound type , used by an application to * access XML content and the value type, that is mapped to an * XML representation. * *

* This abstract class defines methods for adapting a bound type to a value * type or vice versa. The methods are invoked by the JAXB binding * framework during marshaling and unmarshalling: * *

    *
  • XmlAdapter.marshal(...): During marshalling, JAXB * binding framework invokes XmlAdapter.marshal(..) to adapt a * bound type to value type, which is then marshaled to XML * representation.
  • * *
  • XmlAdapter.unmarshal(...): During unmarshalling, * JAXB binding framework first unmarshals XML representation * to a value type and then invokes XmlAdapter.unmarshal(..) to * adapt the value type to a bound type.
  • *
* * Writing an adapter therefore involves the following steps: * *
    *
  • Write an adapter that implements this abstract class.
  • *
  • Install the adapter using the annotation {@link * XmlJavaTypeAdapter}
  • *
* *

Example: Customized mapping of {@code HashMap}

*

The following example illustrates the use of * {@code @XmlAdapter} and {@code @XmlJavaTypeAdapter} to * customize the mapping of a {@code HashMap}. * *

Step 1: Determine the desired XML representation for HashMap. * *

{@code
 *     
 *         this is a value
 *         this is another value
 *         ...
 *     
 * }
* *

Step 2: Determine the schema definition that the * desired XML representation shown above should follow. * *

{@code
 *     
 *     
 *       
 *         
 *       
 *     
 *
 *     
 *       
 *         
 *           
 *         
 *       
 *     
 *
 * }
* *

Step 3: Write value types that can generate the above * schema definition. * *

 *     public class MyHashMapType {
 *         List<MyHashMapEntryType> entry;
 *     }
 *
 *     public class MyHashMapEntryType {
 *         @XmlAttribute
 *         public Integer key; 
 *
 *         @XmlValue
 *         public String value;
 *     }
 * 
* *

Step 4: Write the adapter that adapts the value type, * MyHashMapType to a bound type, HashMap, used by the application. * *

{@code
 *     public final class MyHashMapAdapter extends
 *                        XmlAdapter { ... }
 *      
 * }
* *

Step 5: Use the adapter. * *

 *     public class Foo {
 *         @XmlJavaTypeAdapter(MyHashMapAdapter.class)
 *         HashMap hashmap;
 *         ...
 *     }
 * 
* * The above code fragment will map to the following schema: * *
{@code
 *     
 *       
 *         
 *       
 *     
 * }
* * @param * The type that JAXB doesn't know how to handle. An adapter is written * to allow this type to be used as an in-memory representation through * the {@code ValueType}. * @param * The type that JAXB knows how to handle out of the box. * * @author
  • Sekhar Vajjhala, Sun Microsystems Inc.
  • Kohsuke Kawaguchi, Sun Microsystems Inc.
* @see XmlJavaTypeAdapter * @since 1.6, JAXB 2.0 */ public abstract class XmlAdapter { /** * Do-nothing constructor for the derived classes. */ protected XmlAdapter() {} /** * Convert a value type to a bound type. * * @param v * The value to be converted. Can be null. * @throws Exception * if there's an error during the conversion. The caller is responsible for * reporting the error to the user through {@link javax.xml.bind.ValidationEventHandler}. */ public abstract BoundType unmarshal(ValueType v) throws Exception; /** * Convert a bound type to a value type. * * @param v * The value to be convereted. Can be null. * @throws Exception * if there's an error during the conversion. The caller is responsible for * reporting the error to the user through {@link javax.xml.bind.ValidationEventHandler}. */ public abstract ValueType marshal(BoundType v) throws Exception; }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy