title: I cannot understand the meaning of EclipseLink MOXy XmlProperty or xml-property, could anyone give more information?
body: <p>What I can find on google are ONLY 3 piece of information, and the most detailed is the design doc as following URL</p>
  
  <p><a href="http://wiki.eclipse.org/EclipseLink/DesignDocs/317962/Phase2.1#.40XmlProperty" rel="nofollow">http://wiki.eclipse.org/EclipseLink/DesignDocs/317962/Phase2.1#.40XmlProperty</a></p>
  
  <p>It does mentioned that "The xml-property metadata tag will be used to configure a property." and two examples without marshaling results are given as following:</p>
  
  <pre><code>Example: type-level property
  The following example will demonstrate how a type-level property can be applied.
  
  Setting xml-property on a type via EclipseLink XML metadata can be accomplished as follows:
  
  &lt;java-type name="org.example.Employee"&gt;
      &lt;xml-properties&gt;
          &lt;xml-property name="identifier" value="101" value-type="java.lang.Integer" /&gt;
          &lt;xml-property name="isTrue" value="false" value-type="java.lang.Boolean" /&gt;
      &lt;/xml-properties&gt;
  &lt;/java-type&gt;
  Setting @XmlProperty on a type via annotations can be accomplished as follows:
  
  org.example.Employee.java
  @XmlProperties({@XmlProperty(name="identifier", value="101", valueType=Integer.class), 
                  @XmlProperty(name="isTrue", value="false", valueType=Boolean.class)})
  public class Employee {
     ...
  }
  Example: property-level property
  The following example will demonstrate how a property-level property can be applied.
  
  Setting xml-property on a property via EclipseLink XML metadata can be accomplished as follows:
  
  &lt;java-type name="org.example.Employee"&gt;
      &lt;java-attributes&gt;
          &lt;xml-element java-attribute="myelement"&gt;
              &lt;xml-properties&gt;
                  &lt;xml-property name="isAttribute" value="false" value-type="java.lang.Boolean" /&gt;
                  &lt;xml-property name="comment" value="this is an element" /&gt;
              &lt;/xml-properties&gt;
          &lt;/xml-element&gt;
      &lt;/java-attributes&gt;
  &lt;/java-type&gt;
  Setting @XmlProperty on a property via annotations can be accomplished as follows:
  
  org.example.Employee.java
  public class Employee {
  
    @XmlProperties({@XmlProperty(name="isAttribute", value="false", valueType=Boolean.class),
                    @XmlProperty(name="comment", value="this is an element")}
    public String myelement;
  }
  </code></pre>
  
  <p>I also tried my example, but I cannot tell any difference between with and without the xml-property stuff. </p>
  
  <p>Can anyone explain to me what does XmlProperty do? What kind of effects does it produce? or When to use XmlProperty? Is there any sample code with marshaling results?</p>
  
  <pre><code>&lt;?xml version="1.0"?&gt;
  &lt;xml-bindings xmlns="http://www.eclipse.org/eclipselink/xsds/persistence/oxm"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.eclipse.org/eclipselink/xsds/persistence/oxm http://www.eclipse.org/eclipselink/xsds/eclipselink_oxm_2_4.xsd"
      version="2.1"&gt;
      &lt;xml-schema element-form-default="QUALIFIED"&gt;
          &lt;xml-ns prefix="ns1" namespace-uri="http://www.example.org/customer" /&gt;
          &lt;xml-ns prefix="ns2" namespace-uri="http://www.example.org/phone" /&gt;
          &lt;xml-ns prefix="ns3" namespace-uri="http://www.example.org/addr" /&gt;
      &lt;/xml-schema&gt;
      &lt;java-types&gt;
          &lt;java-type name="example.gettingstarted.demo1.Customer"&gt;
              &lt;xml-root-element /&gt;
              &lt;xml-type namespace="http://www.example.org/customer"
                  prop-order="name address phoneNumbers" /&gt;
              &lt;xml-properties&gt;
                  &lt;xml-property name="hello" value="false" value-type="java.lang.String" /&gt;
                  &lt;xml-property name="world" value="this is an element"
                      value-type="java.lang.String" /&gt;
              &lt;/xml-properties&gt;
              &lt;java-attributes&gt;
                  &lt;xml-attribute java-attribute="name" xml-path="@name" /&gt;
                  &lt;xml-element java-attribute="address"&gt;
                  &lt;/xml-element&gt;
                  &lt;xml-element java-attribute="phoneNumbers" xml-path="contact-info/phone-number" /&gt;
              &lt;/java-attributes&gt;
          &lt;/java-type&gt;
          &lt;java-type name="example.gettingstarted.demo1.PhoneNumber"&gt;
              &lt;xml-root-element /&gt;
              &lt;xml-type namespace="http://www.example.org/phone"&gt;&lt;/xml-type&gt;
              &lt;java-attributes&gt;
                  &lt;xml-attribute java-attribute="type" /&gt;
                  &lt;xml-value java-attribute="value" /&gt;
              &lt;/java-attributes&gt;
          &lt;/java-type&gt;
          &lt;java-type name="example.gettingstarted.demo1.Address"&gt;
          &lt;/java-type&gt;
      &lt;/java-types&gt;
  &lt;/xml-bindings&gt;
  </code></pre>
  
  <p>Java Files:</p>
  
  <pre><code>package example.gettingstarted.demo5;
  
  import java.util.HashMap;
  import java.util.Map;
  
  import javax.xml.bind.JAXBContext;
  import javax.xml.bind.JAXBException;
  import javax.xml.bind.Marshaller;
  import javax.xml.transform.Source;
  import javax.xml.transform.stream.StreamSource;
  
  import org.eclipse.persistence.jaxb.JAXBContextFactory;
  
  import example.gettingstarted.demo1.Address;
  import example.gettingstarted.demo1.Customer;
  import example.gettingstarted.demo1.PhoneNumber;
  
  /**
   * @author barry
   * make Customer.Address.street as Customer.@street
   */
  public class Demo {
  
      @SuppressWarnings({ "rawtypes", "deprecation" })
      public static void main(String[] args) throws JAXBException {
          // Step 1 - Create the Domain Model
          Customer customer = new Customer();
          customer.setName("Jane Doe");
          Address address = new Address();
          address.setStreet("123 Any Street");
          address.setCity("My Town");
          customer.setAddress(address);
          PhoneNumber workPhoneNumber = new PhoneNumber();
          workPhoneNumber.setType("work");
          workPhoneNumber.setValue("613-555-1111");
          customer.getPhoneNumbers().add(workPhoneNumber);
          PhoneNumber cellPhoneNumber = new PhoneNumber();
          cellPhoneNumber.setType("cell");
          cellPhoneNumber.setValue("613-555-2222");
          customer.getPhoneNumbers().add(cellPhoneNumber);
  
          // Step 2 - Convert the Domain Model to XML
          final Map&lt;String, Source&gt; metadataSourceMap = new HashMap&lt;String, Source&gt;();
          metadataSourceMap.put("example.gettingstarted.demo1", new StreamSource("./example/gettingstarted/demo5/eclipselink-oxm.xml"));
  
          final Map&lt;String, Object&gt; properties = new HashMap&lt;String, Object&gt;();
          properties.put(JAXBContextFactory.ECLIPSELINK_OXM_XML_KEY, metadataSourceMap);
  
          final Class[] classes = new Class[1];
          classes[0] = Customer.class;
  
          JAXBContext jaxbContext = (JAXBContext) JAXBContext.newInstance(classes, properties);
          Marshaller marshaller = jaxbContext.createMarshaller();
          marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
          marshaller.marshal(customer, System.out);
      }
  }
  </code></pre>
  
  <p>And my output is as following, no matter whether the xml-property is applied.</p>
  
  <p>
  
         
            My Town
            123 Any Street
         
         
            613-555-1111
            613-555-2222
         
      </p>